luma.gl/docs/api-reference/shadertools/shadertools-picking.md

picking (Shader Module)

Provides support for color based picking. In particular, supports picking a specific instance in an instanced draw call.

Color based picking lets the application draw a primitive with a fixed color, and by reading the color from a pixel in the resulting Framebuffer it can determine which primitive was drawn topmost at that point without asking the CPU to refer to geometry or raycasting etc.

Usage

In your vertex shader, your inform the picking module what object we are currently rendering by supplying a picking color, perhaps from an attribute.

attribute vec3 aPickingColor;
main() {
  picking_setColor(aPickingColor);
  ...
}

In your fragment shader, you simply apply (call) the picking_filterPickingColor filter function at the very end of the shader. This will return the normal color, or the highlight color, or the picking color, as appropriate.

main() {
  gl_FragColor = ...
  gl_FragColor = picking_filterPickingColor(gl_FragColor);
}

If you would like to apply the highlight color to the currently selected element call picking_filterHighlightColor before calling picking_filterPickingColor. You can also apply other filters on the non-picking color (vertex or highlight color) by placing those instruction between these two function calls.

main() {
  gl_FragColor = picking_filterHighlightColor(color);
   ... apply any filters on gl_FragColor ...
 gl_FragColor = picking_filterPickingColor(gl_FragColor);
}

JavaScript Functions

getUniforms

getUniforms returns an object with key/value pairs representing the uniforms that the picking module shaders need.

getUniforms({enabled, })

• enabled=true (boolean) - Activates picking
• selectedIndex=-1 (number) - The index of the selected item, or -1 if no selection.
• highlightColor= (array)- Color used to highlight the currently selected
• active=false (boolean) - Renders the picking colors instead of the normal colors. Normally only used with an off-screen framebuffer during picking.

Note that the selected item will be rendered using highlightColor.

Vertex Shader Functions

void picking_setPickingColor(vec3)

Sets the color that will be returned by the fragment shader if color based picking is enabled. Typically set from a pickingColor uniform or a pickingColors attribute (e.g. when using instanced rendering, to identify the actual instance that was picked).

Fragment Shader Functions

picking_filterPickingColor

If picking active, returns the current vertex's picking color set by picking_setPickingColor, otherwise returns its argument unmodified.

vec4 picking_filterPickingColor(vec4 color)

picking_filterHighlightColor

Returns picking highlight color if the pixel belongs to currently selected model, otherwise returns its argument unmodified.

vec4 picking_filterHighlightColor(vec4 color)

Remarks

• It is strongly recommended that picking_filterPickingColor is called last in a fragment shader, as the picking color (returned when picking is enabled) must not be modified in any way (and alpha must remain 1) or picking results will not be correct.