Merge pull request #9966 from jahow/allow-disable-canvas-reuse

Document how to circumvent the canvas reuse optimization

changelog/upgrade-notes.md

@@ -4,6 +4,23 @@
 
 #### Backwards incompatible changes
 
+##### Usage of `Map.forEachLayerAtPixel`
+
+Due to performance considerations, the layers in a map will sometimes be rendered into one
+single canvas instead of separate elements.
+This means `Map.forEachLayerAtPixel` will bring up false positives.
+
+The easiest solution to avoid that is to assign different `className` properties to each layer like so:
+```js
+new Layer({
+   // ...
+   className: 'my-layer'
+})
+```
+
+Please note that this may incur a significant performance loss when dealing with many layers and/or
+targetting mobile devices.
+
 ##### Removal of `TOUCH` constant from `ol/has`
 
 If you were previously using this constant, you can check if `'ontouchstart'` is defined in `window` instead.

src/ol/PluggableMap.js

@@ -587,6 +587,10 @@ class PluggableMap extends BaseObject {
    * Detect layers that have a color value at a pixel on the viewport, and
    * execute a callback with each matching layer. Layers included in the
    * detection can be configured through `opt_layerFilter`.
+   *
+   * Note: this may give false positives unless the map layers have had different `className`
+   * properties assigned to them.
+   *
    * @param {import("./pixel.js").Pixel} pixel Pixel.
    * @param {function(this: S, import("./layer/Layer.js").default, (Uint8ClampedArray|Uint8Array)): T} callback
    *     Layer callback. This callback will receive two arguments: first is the

src/ol/layer/BaseImage.js

@@ -6,6 +6,7 @@ import Layer from './Layer.js';
 
 /**
  * @typedef {Object} Options
+ * @property {string} [className='ol-layer'] A CSS class name to set to the layer element.
  * @property {number} [opacity=1] Opacity (0, 1).
  * @property {boolean} [visible=true] Visibility.
  * @property {import("../extent.js").Extent} [extent] The bounding extent for layer rendering.  The layer will not be

src/ol/layer/BaseVector.js

@@ -8,6 +8,7 @@ import {createDefaultStyle, toFunction as toStyleFunction} from '../style/Style.
 
 /**
  * @typedef {Object} Options
+ * @property {string} [className='ol-layer'] A CSS class name to set to the layer element.
  * @property {number} [opacity=1] Opacity (0, 1).
  * @property {boolean} [visible=true] Visibility.
  * @property {import("../extent.js").Extent} [extent] The bounding extent for layer rendering.  The layer will not be

src/ol/layer/Graticule.js

@@ -52,6 +52,7 @@ const INTERVALS = [
 
 /**
  * @typedef {Object} Options
+ * @property {string} [className='ol-layer'] A CSS class name to set to the layer element.
  * @property {number} [opacity=1] Opacity (0, 1).
  * @property {boolean} [visible=true] Visibility.
  * @property {import("../extent.js").Extent} [extent] The bounding extent for layer rendering.  The layer will not be

src/ol/layer/Heatmap.js

@@ -10,6 +10,7 @@ import WebGLPointsLayerRenderer from '../renderer/webgl/PointsLayer.js';
 
 /**
  * @typedef {Object} Options
+ * @property {string} [className='ol-layer'] A CSS class name to set to the layer element.
  * @property {number} [opacity=1] Opacity (0, 1).
  * @property {boolean} [visible=true] Visibility.
  * @property {import("../extent.js").Extent} [extent] The bounding extent for layer rendering.  The layer will not be

src/ol/layer/Layer.js

@@ -17,6 +17,7 @@ import SourceState from '../source/State.js';
 
 /**
  * @typedef {Object} Options
+ * @property {string} [className='ol-layer'] A CSS class name to set to the layer element.
  * @property {number} [opacity=1] Opacity (0, 1).
  * @property {boolean} [visible=true] Visibility.
  * @property {import("../extent.js").Extent} [extent] The bounding extent for layer rendering.  The layer will not be
@@ -71,6 +72,11 @@ import SourceState from '../source/State.js';
  *
  * A generic `change` event is fired when the state of the source changes.
  *
+ * Please note that for performance reasons several layers might get rendered to
+ * the same HTML element, which will cause {@link module:ol/Map~Map#forEachLayerAtPixel} to
+ * give false positives. To avoid this, apply different `className` properties to the
+ * layers at creation time.
+ *
  * @fires import("../render/Event.js").RenderEvent#prerender
  * @fires import("../render/Event.js").RenderEvent#postrender
  *

src/ol/layer/VectorImage.js

@@ -7,6 +7,7 @@ import CanvasVectorImageLayerRenderer from '../renderer/canvas/VectorImageLayer.
 
 /**
  * @typedef {Object} Options
+ * @property {string} [className='ol-layer'] A CSS class name to set to the layer element.
  * @property {number} [opacity=1] Opacity (0, 1).
  * @property {boolean} [visible=true] Visibility.
  * @property {import("../extent.js").Extent} [extent] The bounding extent for layer rendering.  The layer will not be

src/ol/layer/VectorTile.js

@@ -11,6 +11,7 @@ import {assign} from '../obj.js';
 
 /**
  * @typedef {Object} Options
+ * @property {string} [className='ol-layer'] A CSS class name to set to the layer element.
  * @property {number} [opacity=1] Opacity (0, 1).
  * @property {boolean} [visible=true] Visibility.
  * @property {import("../extent.js").Extent} [extent] The bounding extent for layer rendering.  The layer will not be