mirror of
https://github.com/visgl/luma.gl.git
synced 2025-12-08 17:36:19 +00:00
157 lines
7.4 KiB
Markdown
157 lines
7.4 KiB
Markdown
# picking (Shader Module)
|
||
|
||
Provides support for color-based picking.
|
||
|
||
The `picking` modules supports picking and highlighting for both instanced and non-instanced data:
|
||
- pick a specific *instance* in an instanced draw call
|
||
- highlight all fragments of an *instance* based on its picking color
|
||
- pick "group of primitives" with the same picking color in non-instanced draw-calls
|
||
- highlight "group of primitives" with the same picking color in non-instanced draw-calls
|
||
|
||
Color based picking lets the application draw a primitive with a color that can later be used to index this specific primitive.
|
||
|
||
Highlighting allows application to specify a picking color corresponding to an object that need to be highlighted and the highlight color to be used.
|
||
|
||
|
||
## 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.
|
||
|
||
```ts
|
||
attribute vec3 aPickingColor;
|
||
main() {
|
||
picking_setPickingColor(aPickingColor);
|
||
...
|
||
}
|
||
```
|
||
|
||
In your fragment shader, you simply apply (call) the `picking_filterColor` 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.
|
||
|
||
```ts
|
||
main() {
|
||
gl_FragColor = ...
|
||
gl_FragColor = picking_filterPickingColor(gl_FragColor);
|
||
}
|
||
```
|
||
|
||
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.
|
||
|
||
```glsl
|
||
main() {
|
||
gl_FragColor = ...
|
||
gl_FragColor = picking_filterPickingColor(gl_FragColor);
|
||
}
|
||
```
|
||
|
||
If highlighting is not needed, you simply apply (call) the `picking_filterPickingColor` filter function at the very end of the shader. This will return the normal color or the picking color, as appropriate.
|
||
|
||
```ts
|
||
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.
|
||
|
||
```ts
|
||
main() {
|
||
gl_FragColor = ...
|
||
gl_FragColor = picking_filterHighlightColor(gl_FragColor);
|
||
... apply any filters on gl_FragColor ...
|
||
gl_FragColor = picking_filterPickingColor(gl_FragColor);
|
||
}
|
||
```
|
||
|
||
## JavaScript Functions
|
||
|
||
### getUniforms()
|
||
|
||
`getUniforms()` takes an object with key/value pairs, returns an object with key/value pairs representing the uniforms that the `picking` module shaders need.
|
||
|
||
Uniforms for the picking module, which renders picking colors and highlighted item.
|
||
When active, renders picking colors, assumed to be rendered to off-screen "picking" buffer.
|
||
When inactive, renders normal colors, with the exception of selected object which is rendered with highlight
|
||
|
||
| Setting | Description |
|
||
| -------------------------------------- | ------------------------------------------------------------------- |
|
||
| `isActive`?: boolean | Whether in picking or normal rendering (+highlighting) mode |
|
||
| `isAttribute`: boolean | Set to true when picking an attribute value instead of object index |
|
||
| `useNormalizedColors`?: boolean | Color range 0-1 or 0-255 |
|
||
| `isHighlightActive`?: boolean | Do we have a highlighted item? |
|
||
| `highlightedObjectColor`?: NumberArray | Set to a picking color to visually highlight that item |
|
||
| `highlightColor`?: NumberArray | Color of visual highlight of "selected" item |
|
||
|
||
- `isActive` - When true, renders picking colors. Set when rendering to off-screen "picking" buffer. When false, renders normal colors, with the exception of selected object which is rendered with highlight
|
||
|
||
<!---
|
||
- `pickingActive`=`false` (_boolean_) - Renders the picking colors instead of the normal colors. Normally only used with an off-screen framebuffer during picking.
|
||
- `pickingSelectedColor`=`null` (_array|null_) - The picking color of the selected (highlighted) object.
|
||
- `pickingHighlightColor`= `[0, 255, 255, 255]` (_array_) - Color used to highlight the currently selected object.
|
||
- `pickingAttribute`=`false` (_boolean_) - Renders a color that encodes an attribute value. Normally only used with an off-screen framebuffer during picking.
|
||
|
||
opts can contain following keys:
|
||
|
||
- `pickingSelectedColorValid` (_boolean_) - When true current instance picking color is ignored, hence no instance is highlighted.
|
||
- `pickingSelectedColor` (_array_) - Picking color of the currently selected instance.
|
||
- `pickingHighlightColor` (_array_)- Color used to highlight the currently selected instance.
|
||
- `pickingActive`=`false` (_boolean_) - When true, renders the picking colors instead of the normal colors. Normally only used with an off-screen framebuffer during picking. Default value is `false`.
|
||
|
||
Note that the selected item will be rendered using `pickingHighlightColor`, if blending is enabled for the draw, alpha channel can be used to control the blending result.
|
||
-->
|
||
|
||
## Vertex Shader Functions
|
||
|
||
### picking_setPickingColor()
|
||
|
||
```ts
|
||
void picking_setPickingColor(vec3 pickingColor)
|
||
```
|
||
|
||
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).
|
||
|
||
### picking_setPickingAttribute
|
||
|
||
Sets the attribute value that needs to be picked.
|
||
|
||
`void picking_setPickingAttribute(float value)`
|
||
`void picking_setPickingAttribute(vec2 value)`
|
||
`void picking_setPickingAttribute(vec3 value)`
|
||
|
||
## Fragment Shader Functions
|
||
|
||
### picking_filterColor
|
||
|
||
```ts
|
||
fn picking_filterColor(color: vec4<f32>) -> vec4<f32>
|
||
vec4 picking_filterColor(vec4 color)
|
||
```
|
||
|
||
| Picking Enabled | Item Highlighted | Returned color |
|
||
| --------------- | ---------------- | --------------------------------------------------------------------- |
|
||
| ✅ | – | Returns picking color (representing index of this color) |
|
||
| ❌ | ✅ | Returns the current highlight color (to show this item as "selected") |
|
||
| ❌ | ❌ | returns the original color (unmodified `color` argument) |
|
||
|
||
### picking_filterPickingColor()
|
||
|
||
```ts
|
||
vec4 picking_filterPickingColor(vec4 color)
|
||
```
|
||
|
||
If picking active, returns the current vertex's picking color set by `picking_setPickingColor`, otherwise returns its argument unmodified.
|
||
|
||
Returns picking highlight color if the pixel belongs to currently selected model, otherwise returns its argument unmodified.
|
||
|
||
|
||
### picking_filterPickingColor()
|
||
|
||
`vec4 picking_filterPickingColor(vec4 color)`
|
||
|
||
If picking active, returns the current vertex's picking color set by `picking_setPickingColor`, otherwise returns its argument unmodified.
|
||
|
||
## Remarks
|
||
|
||
- It is 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.
|
||
|