fix(examples): fix lighting example and shader module

docs/api-reference/shadertools/modules/fp32.md

@@ -1,4 +1,4 @@
-# 32-bit Floating Point package
+# 32-bit Floating Point (Shader Module)
 
 Provides "improved" 32-bit math support to GPU shaders on certain platforms,
 mainly compensating for non-IEEE compliant "fast-math" functions that

docs/api-reference/shadertools/modules/fp64.md

@@ -1,4 +1,4 @@
-# 64-bit Floating Point package
+# 64-bit Floating Point (Shader Module)
 
 Provides basic 64-bit math support in GPU shaders:
 

docs/api-reference/shadertools/modules/goraud.md

@@ -0,0 +1,3 @@
+# goraudMaterial (Shader Module)
+
+The `goraudMaterial` shader module provides functions to apply gouraud (per vertex) lighting to your geometry.

docs/api-reference/shadertools/modules/lights.md

@@ -0,0 +1,23 @@
+# lights (Shader Module)
+
+The `lights`` shader module collects uniforms describing the lights in a scene.
+No view dependent uniforms are includes so the resulting uniform block should be reusable for all draw calls in a scene.
+
+## Material modules
+
+Actual lighting computations are done by the various material shader modules, such as:
+
+- `phongMaterial`
+- `goraudmaterial`
+- `pbrMaterial`
+
+Different draw calls can use different material uniform buffers and/or different material modules.
+
+All material modules depend on this lighting module and base lighting calculations
+on the lights defined by this module, meaning that the same lighting uniform buffer can be
+bound.
+
+## Defining lights
+
+The lights module lets the application define the ambient light color and a number of additional lights that can either be point lights (e.g, a light bulb) or directional lights (e.g. sunlight).
+

docs/api-reference/shadertools/modules/pbr.md

@@ -1,12 +1,18 @@
-# PBR (Shader Module)
+# pbrMaterial (Shader Module)
 
-An implementation of PBR (Physically-Based Rendering) based on the [Khronos Reference Implementation](https://github.com/KhronosGroup/glTF-WebGL-PBR).
+Implements Physically Based Shading of a microfacet surface defined by a glTF material.
 
-A reference implementation for Physically Based Shading of a microfacet surface defined by a glTF material.
+Lighting is expected to be defined by the `lights` module.
 
-References:
+
+## References
 
 - [Real Shading in Unreal Engine 4](http://blog.selfshadow.com/publications/s2013-shading-course/karis/s2013_pbs_epic_notes_v2.pdf)
 - [Physically Based Shading at Disney](http://blog.selfshadow.com/publications/s2012-shading-course/burley/s2012_pbs_disney_brdf_notes_v3.pdf)
 - [README.md - Environment Maps](https://github.com/KhronosGroup/glTF-WebGL-PBR/#environment-maps)
 - ["An Inexpensive BRDF Model for Physically based Rendering" by Christophe Schlick](https://www.cs.virginia.edu/~jdl/bib/appearance/analytic%20models/schlick94b.pdf)
+
+## Attribution
+
+This implementation of PBR (Physically-Based Rendering) is a fork of the [Khronos Reference Implementation](https://github.com/KhronosGroup/glTF-WebGL-PBR) under the Apache 2.0 license.
+

docs/api-reference/shadertools/modules/phong.md

@@ -0,0 +1,3 @@
+# phongMaterial (Shader Module)
+
+This `phongMaterial` shader module provides functions to apply phong (per fragment) lighting to your geometry.

docs/api-reference/shadertools/modules/picking.md

@@ -2,22 +2,38 @@
 
 Provides support for color-based picking. 
 
-Color based picking lets the application draw each primitive with a picking color that can later be used to retrieve the index of this specific primitive.
+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.
 
-In particular, supports picking a specific instance in an instanced draw call.
 
 ## 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.
 
-```glsl
+```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
@@ -27,36 +43,72 @@ main() {
 }
 ```
 
-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.
+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.
 
-```glsl
+```ts
 main() {
-  gl_FragColor = picking_filterHighlightColor(color);
-  //  ... apply any filters on gl_FragColor ...
+  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()
+
+`getUniforms()` takes an object with key/value pairs, returns an object with key/value pairs representing the uniforms that the `picking` module shaders need.
 
-`getUniforms` 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 
 
-`getUniforms({pickingActive, ...})`
+| 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
+### picking_setPickingColor()
 
-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).
+```ts
+void picking_setPickingColor(vec3 pickingColor)
+```
 
-`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
 
@@ -68,18 +120,37 @@ Sets the attribute value that needs to be picked.
 
 ## Fragment Shader Functions
 
-### picking_filterPickingColor
+### picking_filterColor
 
-If picking active, returns the current vertex's picking color set by `picking_setPickingColor`, otherwise returns its argument unmodified.
+```ts
+fn picking_filterColor(color: vec4<f32>) -> vec4<f32>
+vec4 picking_filterColor(vec4 color)
+```
 
-`vec4 picking_filterPickingColor(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_filterHighlightColor
+### 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.
 
-`vec4 picking_filterHighlightColor(vec4 color)`
+
+### 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 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.
+- 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.
+