feat: Row index based picking (#10302)

Author: ibgreen-openai

docs/api-reference/core/deck.md

@@ -773,7 +773,7 @@ Parameters:
 * `y` (number) - y position in pixels
 * `radius` (number, optional) - radius of tolerance in pixels. Default `0`.
 * `layerIds` (string[], optional) - a list of layer ids to query from. If not specified, then all pickable and visible layers are queried.
-* `depth` - Specifies the max number of objects to return. Default `10`. For layers without explicit picking color buffers, only the default depth of 10 unique objects per layer is guaranteed; higher custom depths may return duplicate results for these layers.
+* `depth` - Specifies the max number of objects to return. Default `10`. For layers without explicit picking index buffers, only the default depth of 10 unique objects per layer is guaranteed; higher custom depths may return duplicate results for these layers.
 * `unproject3D` (boolean, optional) - if `true`, `info.coordinate` will be a 3D point by unprojecting the `x, y` screen coordinates onto the picked geometry. Default `false`.
 
 Returns:
@@ -783,7 +783,7 @@ Returns:
 Notes:
 
 * Deep picking is implemented as a sequence of simpler picking operations and can have a performance impact. Should this become a concern, you can use the `depth` parameter to limit the number of matches that can be returned, and thus the maximum number of picking operations.
-* Layers that provide explicit picking color buffers support buffer mutation between picking passes and are not subject to the default-depth unique-object guarantee.
+* Layers that provide explicit picking index buffers support buffer mutation between picking passes and are not subject to the default-depth unique-object guarantee.
 
 
 #### `pickObjects` {#pickobjects}

docs/developer-guide/custom-layers/attribute-management.md

@@ -47,7 +47,7 @@ While most apps rely on their layers to automatically generate appropriate GPU b
 
 While this allows for ultimate performance and control of updates, as well as potential sharing of buffers between layers, the application will need to generate attributes in exactly the format that the layer shaders expect, creating a strong coupling between the application and the layer.
 
-**Note:** The application can provide some buffers and let others be managed by the layer. Explicit picking color buffers are only needed when the logical picking id differs from the rendered instance id.
+**Note:** The application can provide some buffers and let others be managed by the layer. Explicit picking index buffers are only needed when the logical picking id differs from the rendered instance id.
 
 
 ## More information

docs/developer-guide/custom-layers/layer-attributes.md

@@ -55,7 +55,7 @@ For _variable primitive layers_ there are two options:
 
 2) Copy each descriptive attribute `N` times (`N` being the number of vertices generated for that row during tesselation). This is the method that is used in deck.gl today.
 
-3) Add a single `rowIndex` attribute and copy the same index `N` times as above. In this approach, descriptive values could then be read from textures where they are stored a single time. This provides flexibility at the price of performance (texture access latency) and complexity (working with data in textures).
+3) Add a single `rowIndexes` attribute and copy the same index `N` times as above. In this approach, descriptive values could then be read from textures where they are stored a single time. This provides flexibility at the price of performance (texture access latency) and complexity (working with data in textures).
 
 
 Remarks:

docs/developer-guide/custom-layers/picking.md

@@ -55,49 +55,44 @@ The following sections describe common ways to implement custom picking.
 
 Instanced layer shaders can derive picking colors from the built-in instance id when each rendered instance maps to one picked object. In GLSL, use `picking_setPickingColorFromInstanceID()` or assign `geometry.pickingColor = picking_getPickingColorFromInstanceID()`. In WGSL, add `@builtin(instance_index)` to the vertex inputs and use `picking_getPickingColorFromIndex(instanceIndex)`.
 
-Add an explicit picking color attribute only when the logical picking id within the current layer is different from the rendered instance id. For example:
+Add an explicit picking index attribute only when the logical picking id within the current layer is different from the rendered instance id. For example:
 
 * Binary GeoJSON or MVT point sublayers may render local point instances while picking should return a global feature index.
 
-* `PathLayer` tessellates one path into multiple rendered segment or joint instances, so its generated geometry needs explicit picking colors that map back to the source path index instead of each rendered segment's instance id.
+* `PathLayer` tessellates one path into multiple rendered segment or joint instances, so its generated geometry needs explicit picking indexes that map back to the source path index instead of each rendered segment's instance id.
 
-### Creating A Picking Color Attribute
+### Creating A Picking Index Attribute
 
-Add an attribute for each vertex using the layer's [AttributeManager](../../api-reference/core/attribute-manager.md):
+Add an attribute for each vertex or instance using the layer's [AttributeManager](../../api-reference/core/attribute-manager.md). Use the `rowIndexes` attribute name to let deck.gl handle deep-picking buffer mutation.
 
 ```js
-import {GL} from '@luma.gl/webgl/constants';
-
 class MyLayer extends Layer {
   initializeState() {
     this.state.attributeManager.add({
-      customPickingColors: {
-        size: 3,
-        type: GL.UNSIGNED_BYTE,
-        update: this.calculatePickingColors
+      rowIndexes: {
+        size: 1,
+        type: 'uint32',
+        update: this.calculatePickingIndexes
       }
     });
   }
 }
 ```
 
-Populate the attribute by providing a different picking color for every object that you need to differentiate. The default implementation of [`layer.encodePickingColor()`](../../api-reference/core/layer.md#encodepickingcolor) and [`layer.decodePickingColor()`](../../api-reference/core/layer.md#decodepickingcolor) is likely sufficient, but you may need to implement your own pair.
+Populate the attribute by providing the logical object index for every rendered vertex or instance that you need to differentiate.
 
 ```js
 class MyLayer extends Layer {
 
   ...
 
-  calculatePickingColors(attribute) {
+  calculatePickingIndexes(attribute) {
       const {data} = this.props;
       const {value} = attribute;
 
       let i = 0;
       for (const object of data) {
-        const pickingColor = this.encodePickingColor(i);
-        value[i * 3] = pickingColor[0];
-        value[i * 3 + 1] = pickingColor[1];
-        value[i * 3 + 2] = pickingColor[2];
+        value[i] = i;
         i++;
       }
   }
@@ -129,15 +124,15 @@ All core layers (including composite layers) support picking using luma.gl's `pi
 
 #### Vertex Shader
 
-Vertex shader should set current picking color using `picking_setPickingColor` method provided by picking shader module.
+Vertex shader should set current picking color using helpers provided by the picking shader module.
 
 ```glsl
-attribute vec3 customPickingColors;
+in float rowIndexes;
 
 void main(void) {
   ...
 
-  picking_setPickingColor(customPickingColors);
+  geometry.pickingColor = picking_getPickingColorFromIndex(rowIndexes);
 }
 ```
 

docs/developer-guide/custom-layers/primitive-layers.md

@@ -149,4 +149,4 @@ By always using the following shader functions for handling projections and scal
 
 If your layer is instanced (`data` prop is an array and each element is rendered as one primitive), then you may take advantage of the default implementation of the [layer picking methods](../../api-reference/core/layer.md#layer-picking-methods).
 
-By default, instanced layer shaders can derive picking colors from the built-in instance id. Add an explicit picking color attribute only when the logical picking id within the current layer is different from the rendered instance id. See [Implementing Custom Picking](./picking.md#implementing-custom-picking) for custom picking details and examples.
+By default, instanced layer shaders can derive picking colors from the built-in instance id. Add an explicit picking index attribute only when the logical picking id within the current layer is different from the rendered instance id. See [Implementing Custom Picking](./picking.md#implementing-custom-picking) for custom picking details and examples.

docs/upgrade-guide.md

@@ -4,7 +4,7 @@
 
 #### `pickMultipleObjects()` pick depth limits
 
-For layers that use built-in shader instance ids instead of explicit picking color buffers, `pickMultipleObjects()` now only guarantees the default `depth` of 10 unique objects per layer. Applications that call `pickMultipleObjects()` with a custom `depth` above the default may receive duplicate results for these layers. Layers with explicit picking color buffers keep their previous buffer-mutation behavior.
+For layers that use built-in shader instance ids instead of explicit picking index buffers, `pickMultipleObjects()` now only guarantees the default `depth` of 10 unique objects per layer. Applications that call `pickMultipleObjects()` with a custom `depth` above the default may receive duplicate results for these layers. Layers with explicit picking index buffers keep their previous buffer-mutation behavior.
 
 ### `instancePickingColors` attribute is no longer automatically generated
 
@@ -13,7 +13,7 @@ Most built-in and custom instanced layers now derive picking colors from built-i
 In rare cases, custom WebGL layer shaders may need an update if they explicitly read the `instancePickingColors` attribute.
 
 - In such cases, use the new picking shader helper functions to derive the color from the instance id, for example `picking_setPickingColorFromInstanceID()` in GLSL or `picking_getPickingColorFromIndex(instanceIndex)` in WGSL.
-- However, if the logical picking id is different from the rendered instance id, layers can still continue to register and populate an explicit picking color attribute as before.
+- However, if the logical picking id is different from the rendered instance id, layers can register and populate an explicit `rowIndexes` attribute.
 
 ## Upgrading to v9.3
 

modules/core/src/lib/layer-state.ts

@@ -37,7 +37,8 @@ export default class LayerState<LayerT extends Layer> extends ComponentState<Lay
    */
   usesPickingColorCache: boolean;
   /**
-   * If the layer has picking buffer (pickingColors or instancePickingColors)
+   * If the layer has a picking buffer
+   * (rowIndexes, pickingColors or instancePickingColors)
    */
   hasPickingBuffer?: boolean;
   /**

modules/core/src/lib/layer.ts

@@ -17,7 +17,7 @@ import memoize from '../utils/memoize';
 import {mergeShaders} from '../utils/shader';
 import {projectPosition, getWorldPosition} from '../shaderlib/project/project-functions';
 import typedArrayManager from '../utils/typed-array-manager';
-import {disablePickingIndex} from '../shaderlib/picking/picking';
+import {disablePickingIndex, PICKING_INVALID_INDEX} from '../shaderlib/picking/picking';
 
 import Component from '../lifecycle/component';
 import LayerState, {ChangeFlags} from './layer-state';
@@ -59,6 +59,18 @@ const areViewportsEqual = memoize(
 
 let pickingColorCache = new Uint8ClampedArray(0);
 
+function getPickingAttribute(attributes: Record<string, Attribute>): Attribute | undefined {
+  return attributes.rowIndexes || attributes.pickingColors || attributes.instancePickingColors;
+}
+
+function getPickingIndexAttribute(attributes: Record<string, Attribute>): Attribute | undefined {
+  return attributes.rowIndexes;
+}
+
+function getPickingColorAttribute(attributes: Record<string, Attribute>): Attribute | undefined {
+  return attributes.pickingColors || attributes.instancePickingColors;
+}
+
 const defaultProps: DefaultProps<LayerProps> = {
   // data: Special handling for null, see below
   data: {type: 'data', value: EMPTY_ARRAY, async: true},
@@ -498,16 +510,17 @@ export default abstract class Layer<PropsT extends {} = {}> extends Component<
       // Only generate picking buffer if needed
       if (hasPickingBuffer !== needsPickingBuffer) {
         this.internalState!.hasPickingBuffer = needsPickingBuffer;
-        const {pickingColors, instancePickingColors} = attributeManager.attributes;
-        const pickingColorsAttribute = pickingColors || instancePickingColors;
-        if (pickingColorsAttribute) {
-          if (needsPickingBuffer && pickingColorsAttribute.constant) {
-            pickingColorsAttribute.constant = false;
-            attributeManager.invalidate(pickingColorsAttribute.id);
+        const pickingAttribute = getPickingAttribute(attributeManager.attributes);
+        if (pickingAttribute) {
+          if (needsPickingBuffer && pickingAttribute.constant) {
+            pickingAttribute.constant = false;
+            attributeManager.invalidate(pickingAttribute.id);
           }
-          if (!pickingColorsAttribute.value && !needsPickingBuffer) {
-            pickingColorsAttribute.constant = true;
-            pickingColorsAttribute.value = [0, 0, 0];
+          if (!pickingAttribute.value && !needsPickingBuffer) {
+            pickingAttribute.constant = true;
+            pickingAttribute.value = getPickingIndexAttribute(attributeManager.attributes)
+              ? [PICKING_INVALID_INDEX]
+              : [0, 0, 0];
           }
         }
       }
@@ -808,8 +821,23 @@ export default abstract class Layer<PropsT extends {} = {}> extends Component<
     }
 
     // @ts-ignore (TS2531) this method is only called internally with attributeManager defined
-    const {pickingColors, instancePickingColors} = this.getAttributeManager().attributes;
-    const colors = pickingColors || instancePickingColors;
+    const attributes = this.getAttributeManager().attributes;
+    const indexes = getPickingIndexAttribute(attributes);
+    const colors = getPickingColorAttribute(attributes);
+
+    const externalIndexAttribute =
+      indexes && data.attributes && (data.attributes[indexes.id] as BinaryAttribute);
+    if (externalIndexAttribute && externalIndexAttribute.value) {
+      const values = externalIndexAttribute.value;
+      for (let index = 0; index < data.length; index++) {
+        const i = indexes.getVertexOffset(index);
+        if (values[i] === objectIndex) {
+          this._disablePickingIndex(index);
+        }
+      }
+      return;
+    }
+
     const externalColorAttribute =
       colors && data.attributes && (data.attributes[colors.id] as BinaryAttribute);
     if (externalColorAttribute && externalColorAttribute.value) {
@@ -833,8 +861,18 @@ export default abstract class Layer<PropsT extends {} = {}> extends Component<
   // TODO - simplify subclassing interface
   protected _disablePickingIndex(objectIndex: number): void {
     // @ts-ignore (TS2531) this method is only called internally with attributeManager defined
-    const {pickingColors, instancePickingColors} = this.getAttributeManager().attributes;
-    const colors = pickingColors || instancePickingColors;
+    const attributes = this.getAttributeManager().attributes;
+    const indexes = getPickingIndexAttribute(attributes);
+    if (indexes) {
+      const start = indexes.getVertexOffset(objectIndex);
+      const end = indexes.getVertexOffset(objectIndex + 1);
+      const invalidIndexes = new Uint32Array(end - start);
+      invalidIndexes.fill(PICKING_INVALID_INDEX);
+      indexes.buffer.write(invalidIndexes, start * invalidIndexes.BYTES_PER_ELEMENT);
+      return;
+    }
+
+    const colors = getPickingColorAttribute(attributes);
     if (!colors) {
       if (this.internalState) {
         disablePickingIndex(this.internalState.disabledPickingIndices, objectIndex);
@@ -852,23 +890,25 @@ export default abstract class Layer<PropsT extends {} = {}> extends Component<
   /** (Internal) Re-enable all picking indices after multi-depth picking */
   restorePickingColors(): void {
     // @ts-ignore (TS2531) this method is only called internally with attributeManager defined
-    const {pickingColors, instancePickingColors} = this.getAttributeManager().attributes;
-    const colors = pickingColors || instancePickingColors;
-    if (!colors) {
+    const attributes = this.getAttributeManager().attributes;
+    const pickingAttribute = getPickingAttribute(attributes);
+    if (!pickingAttribute) {
       if (this.internalState) {
         this.internalState.disabledPickingIndices.length = 0;
       }
       return;
     }
+    const colors = getPickingColorAttribute(attributes);
     // The picking color cache may have been freed and then reallocated. This ensures we read from the currently allocated cache.
     if (
       // @ts-ignore (TS2531) this method is only called internally with internalState defined
       this.internalState.usesPickingColorCache &&
+      colors &&
       (colors.value as Uint8ClampedArray).buffer !== pickingColorCache.buffer
     ) {
       colors.value = pickingColorCache.subarray(0, (colors.value as Uint8ClampedArray).length);
     }
-    colors.updateSubBuffer({startOffset: 0});
+    pickingAttribute.updateSubBuffer({startOffset: 0});
   }
 
   /* eslint-disable max-statements */

modules/core/src/shaderlib/picking/picking.ts

@@ -6,11 +6,12 @@ import {picking} from '@luma.gl/shadertools';
 import log from '../../utils/log';
 
 export const PICKING_MAX_DISABLED_INDICES = 10;
+export const PICKING_INVALID_INDEX = 16777215;
 
 export function disablePickingIndex(disabledPickingIndices: number[], objectIndex: number): void {
   if (disabledPickingIndices.length === PICKING_MAX_DISABLED_INDICES) {
     log.warn(
-      `pickMultipleObjects can only exclude ${PICKING_MAX_DISABLED_INDICES} previously picked objects for layers without picking color buffers`
+      `pickMultipleObjects can only exclude ${PICKING_MAX_DISABLED_INDICES} previously picked objects for layers without picking buffers`
     )();
   } else {
     disabledPickingIndices.push(objectIndex);
@@ -42,7 +43,7 @@ function packDisabledPickingIndices(disabledPickingIndices: number[], startIndex
 
 const pickingHelpersGLSL = /* glsl */ `\
 vec3 picking_getPickingColorFromIndex(float objectIndex) {
-  if (objectIndex < 0.0 || objectIndex > 16777214.0) {
+  if (objectIndex < 0.0 || objectIndex >= ${PICKING_INVALID_INDEX}.0) {
     return vec3(0.0);
   }
 
@@ -67,6 +68,10 @@ vec3 picking_getPickingColorFromIndex(float objectIndex) {
   );
 }
 
+vec3 picking_getPickingColorFromIndex(uint objectIndex) {
+  return picking_getPickingColorFromIndex(float(objectIndex));
+}
+
 vec3 picking_getPickingColorFromInstanceID() {
   return picking_getPickingColorFromIndex(float(gl_InstanceID));
 }
@@ -109,7 +114,7 @@ fn picking_isColorValid(color: vec3<f32>) -> bool {
 }
 
 fn picking_getPickingColorFromIndex(objectIndex: u32) -> vec3<f32> {
-  if (objectIndex > 16777214u) {
+  if (objectIndex >= ${PICKING_INVALID_INDEX}u) {
     return vec3<f32>(0.0);
   }
 

modules/geo-layers/src/mesh-layer/mesh-layer-vertex.glsl.ts

@@ -11,7 +11,7 @@ in vec3 normals;
 in vec3 colors;
 in vec2 texCoords;
 in vec4 uvRegions;
-in vec3 featureIdsPickingColors;
+in float rowIndexes;
 
 // Instance attributes
 in vec4 instanceColors;
@@ -40,7 +40,7 @@ void main(void) {
   geometry.uv = uv;
 
   if (mesh.pickFeatureIds) {
-    geometry.pickingColor = featureIdsPickingColors;
+    geometry.pickingColor = picking_getPickingColorFromIndex(rowIndexes);
   } else {
     geometry.pickingColor = picking_getPickingColorFromInstanceID();
   }