feat(core): Remove redundant instance picking colors (#10275)

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`.
+* `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.
 * `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,6 +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.
 
 
 #### `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. As an example management of the `instancePickingColors` buffer is normally left to 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.
 
 
 ## More information

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

@@ -49,7 +49,17 @@ When other gestures (click, drag, etc.) are detected, deck.gl does not repeat pi
 special support is provided for the built-in "picking color" based picking
 system, which most layers use.
 
-To take full control of picking, a layer need to take the following steps:
+The following sections describe common ways to implement custom picking.
+
+### Default Instanced 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:
+
+* 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.
 
 ### Creating A Picking Color Attribute
 

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

@@ -149,6 +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, each layer creates an `instancePickingColors` attribute and automatically calculates it using the length of the `data` array.
-
-For custom picking, read about [Implementing Custom Picking](./picking.md#implementing-custom-picking).
+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.

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

@@ -206,7 +206,6 @@ attribute vec3 instanceNormals;
 attribute vec4 instanceColors;
 attribute vec3 instancePositions;
 attribute vec3 instancePositions64Low;
-attribute vec3 instancePickingColors;
 
 /* New attribute */
 attribute flat instanceRadiusPixels;
@@ -228,7 +227,7 @@ void main(void) {
 
   vColor = vec4(lightColor, instanceColors.a * opacity) / 255.0;
 
-  picking_setPickingColor(instancePickingColors);
+  picking_setPickingColorFromInstanceID();
 }
 `;
 ```

docs/upgrade-guide.md

@@ -1,5 +1,20 @@
 # Upgrade Guide
 
+## Upgrading to v9.4
+
+#### `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.
+
+### `instancePickingColors` attribute is no longer automatically generated
+
+Most built-in and custom instanced layers now derive picking colors from built-in shader instance ids, meaning the default `instancePickingColors` attribute is no longer automatically generated by deck.gl.
+
+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.
+
 ## Upgrading to v9.3
 
 Upgraded dependencies to [luma.gl v9.3](https://luma.gl/docs/upgrade-guide) and [loaders.gl v4.4](https://loaders.gl/docs/upgrade-guide). Your app may be affected if it contains custom layers.

docs/whats-new.md

@@ -8,6 +8,10 @@ This page contains highlights of each deck.gl release. Also check our [vis.gl bl
 
 - Views now support a `parameters` prop for per-view GPU draw state overrides. `GlobeView` uses this to enable back-face culling by default, and applications can override it with `new GlobeView({parameters: {cullMode: 'none'}})`.
 
+### Performance
+
+- Picking in most instanced layers no longer allocates an `instancePickingColors` attribute buffer, instead using shader builtins `instance_index` / `gl_InstanceID`, reducing memory usage and initialization times.
+
 ## deck.gl v9.3
 
 Release date: April 13, 2026

modules/aggregation-layers/src/common/aggregation-layer.ts

@@ -39,9 +39,7 @@ export default abstract class AggregationLayer<
   /** Called when some attributes change, a chance to mark Aggregator as dirty */
   abstract onAttributeChange(id: string): void;
 
-  initializeState(): void {
-    this.getAttributeManager()!.remove(['instancePickingColors']);
-  }
+  initializeState(): void {}
 
   // Extend Layer.updateState to update the Aggregator instance
   // returns true if aggregator is changed

modules/aggregation-layers/src/grid-layer/grid-cell-layer-vertex.glsl.ts

@@ -12,7 +12,6 @@ in vec3 normals;
 in vec2 instancePositions;
 in float instanceElevationValues;
 in float instanceColorValues;
-in vec3 instancePickingColors;
 
 uniform sampler2D colorRange;
 
@@ -30,7 +29,7 @@ vec4 interp(float value, vec2 domain, sampler2D range) {
 }
 
 void main(void) {
-  geometry.pickingColor = instancePickingColors;
+  geometry.pickingColor = picking_getPickingColorFromInstanceID();
 
   if (isnan(instanceColorValues) ||
     instanceColorValues < grid.colorDomain.z ||

modules/aggregation-layers/src/hexagon-layer/hexagon-cell-layer-vertex.glsl.ts

@@ -14,7 +14,6 @@ in vec3 normals;
 in vec2 instancePositions;
 in float instanceElevationValues;
 in float instanceColorValues;
-in vec3 instancePickingColors;
 
 uniform sampler2D colorRange;
 
@@ -34,7 +33,7 @@ vec4 interp(float value, vec2 domain, sampler2D range) {
 }
 
 void main(void) {
-  geometry.pickingColor = instancePickingColors;
+  geometry.pickingColor = picking_getPickingColorFromInstanceID();
 
   if (isnan(instanceColorValues) ||
     instanceColorValues < hexagon.colorDomain.z ||