Add example for rendering custom point symbols

examples/earthquake-custom-symbol.html

@@ -0,0 +1,9 @@
+---
+layout: example.html
+title: Earthquakes with custom symbols
+shortdesc: Demonstrates the use of `ol.render.toCanvas` to create custom icon symbols.
+docs: >
+  This example parses a KML file and renders the features as a vector layer.  The layer is given a <code>style</code> that renders earthquake locations with a custom lightning symbol and a size relative to their magnitude.
+tags: "KML, vector, style, canvas, symbol"
+---
+<div id="map" class="map"></div>

examples/earthquake-custom-symbol.js

@@ -0,0 +1,71 @@
+goog.require('ol.Map');
+goog.require('ol.View');
+goog.require('ol.format.KML');
+goog.require('ol.geom.Polygon');
+goog.require('ol.layer.Tile');
+goog.require('ol.layer.Vector');
+goog.require('ol.render');
+goog.require('ol.source.Stamen');
+goog.require('ol.source.Vector');
+goog.require('ol.style.Fill');
+goog.require('ol.style.Icon');
+goog.require('ol.style.Stroke');
+goog.require('ol.style.Style');
+
+
+var styleCache = {};
+var styleFunction = function(feature, resolution) {
+  // 2012_Earthquakes_Mag5.kml stores the magnitude of each earthquake in a
+  // standards-violating <magnitude> tag in each Placemark.  We extract it from
+  // the Placemark's name instead.
+  var name = feature.get('name');
+  var magnitude = parseFloat(name.substr(2));
+  var size = parseInt(10 + 40 * (magnitude - 5), 10);
+  var style = styleCache[size];
+  if (!style) {
+    var canvas =
+        /** @type {HTMLCanvasElement} */ (document.createElement('canvas'));
+    var render = ol.render.toContext(
+        /** @type {CanvasRenderingContext2D} */ (canvas.getContext('2d')),
+        {size: [size + 2, size + 2], pixelRatio: size / 10});
+    render.setFillStrokeStyle(
+        new ol.style.Fill({ color: 'rgba(255, 153, 0, 0.4)' }),
+        new ol.style.Stroke({ color: 'rgba(255, 204, 0, 0.2)', width: 1 }));
+    render.drawPolygonGeometry(new ol.geom.Polygon(
+        [[[0, 0], [4, 2], [6, 0], [10, 5], [6, 3], [4, 5], [0, 0]]]));
+    style = new ol.style.Style({
+      image: new ol.style.Icon({
+        img: canvas,
+        imgSize: [canvas.width, canvas.height],
+        rotation: 1.2
+      })
+    });
+    styleCache[size] = style;
+  }
+  return style;
+};
+
+var vector = new ol.layer.Vector({
+  source: new ol.source.Vector({
+    url: 'data/kml/2012_Earthquakes_Mag5.kml',
+    format: new ol.format.KML({
+      extractStyles: false
+    })
+  }),
+  style: styleFunction
+});
+
+var raster = new ol.layer.Tile({
+  source: new ol.source.Stamen({
+    layer: 'toner'
+  })
+});
+
+var map = new ol.Map({
+  layers: [raster, vector],
+  target: 'map',
+  view: new ol.View({
+    center: [0, 0],
+    zoom: 2
+  })
+});

src/ol/render.js

@@ -8,6 +8,9 @@ goog.require('ol.vec.Mat4');
 /**
  * Binds a Canvas Immediate API to a canvas context, to allow drawing geometries
  * to the context's canvas.
+ *
+ * The units for geometry coordinates are css pixels relative to the top left
+ * corner of the canvas element.
  * ```js
  * var canvas = document.createElement('canvas');
  * var render = ol.render.toContext(canvas.getContext('2d'),
@@ -16,6 +19,7 @@ goog.require('ol.vec.Mat4');
  * render.drawPolygonGeometry(
  *     new ol.geom.Polygon([[[0, 0], [100, 100], [100, 0], [0, 0]]]));
  * ```
+ *
  * Note that {@link ol.render.canvas.Immediate#drawAsync} and
  * {@link ol.render.canvas.Immediate#drawFeature} cannot be used.
  *