# Shader Module: Picking

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 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_filterFinal

 If is picking enabled and active, returns the current vertex's picking color set by `picking_setPickingColor`. Otherwise returns its argument, unmodified.

`vec4 picking_filterFinal(vec4 color)`



### picking_filterHighlight

Returns the picking color set by `picking_setPickingColor`, if is picking enabled and active. Otherwise returns its argument, unmodified.

`vec4 picking_filterHighlight(vec4 color)`


## Remarks

* It is strongly recommended that `picking_filterColor` 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.
