docs: Update to use UBOs rather than setUniforms (#9208)

visgl · Oct 11, 2024 · 065816e · 065816e
1 parent ab15d9c
commit 065816e
Show file tree

Hide file tree

Showing 3 changed files with 71 additions and 36 deletions.
diff --git a/docs/developer-guide/custom-layers/layer-extensions.md b/docs/developer-guide/custom-layers/layer-extensions.md
@@ -10,26 +10,43 @@ Consider a hypothetical use case: in a `ScatterplotLayer`, we inject a piece of
 
 ```js
 import {ScatterplotLayer} from '@deck.gl/layers';
+import type {ShaderModule} from '@luma.gl/shadertools';
+
+// Declare uniform block & custom shader module
+const uniformBlock = `\
+uniform highlightUniforms {
+  bool enabled;
+} highlight;
+`;
+
+type HighlightProps = {enabled: boolean};
+
+const highlightUniforms = {
+  name: 'trips',
+  fs: uniformBlock, // Only need to add block to fragment stage in this example
+  uniformTypes: {enabled: 'f32'}
+} as const satisfies ShaderModule<TripsProps>;
 
 class FilteredScatterplotLayer extends ScatterplotLayer {
   getShaders() {
-    return {
-      ...super.getShaders(),
-      inject: {
-        // Declare custom uniform
-        'fs:#decl': 'uniform bool highlightRed;',
-        // Standard injection hook - see "Writing Shaders"
-        'fs:DECKGL_FILTER_COLOR': `
-          if (highlightRed) {
-            if (color.r / max(color.g, 0.001) > 2. && color.r / max(color.b, 0.001) > 2.) {
-              // is red
-              color = vec4(1.0, 0.0, 0.0, 1.0);
-            } else {
-              discard;
-            }
+    const shaders = super.getShaders();
+    shaders.inject = {
+      // Standard injection hook - see "Writing Shaders"
+      'fs:DECKGL_FILTER_COLOR': `
+        if (highlight.enabled) {
+          if (color.r / max(color.g, 0.001) > 2. && color.r / max(color.b, 0.001) > 2.) {
+            // is red
+            color = vec4(1.0, 0.0, 0.0, 1.0);
+          } else {
+            discard;
           }
-        `
-      }
+        }
+      `
+    };
+
+    // Add uniform binding to shader modules
+    shaders.modules = [...shaders.modules, highlightUniforms];
+    return shaders;
     };
   }
 
@@ -38,9 +55,8 @@ class FilteredScatterplotLayer extends ScatterplotLayer {
 
     if (props.highlightRed !== oldProps.highlightRed) {
       // Set the custom uniform
-      this.state.model.setUniforms({
-        highlightRed: props.highlightRed
-      });
+      const highlightProps: HighlightProps = {enabled: props.highlightRed};
+      model.shaderInputs.setProps({highlight: highlightProps});
     }
   }
 }
@@ -185,31 +201,49 @@ Back to our example use case. We can implement the red filter with the following
 ```js
 import {LayerExtension} from '@deck.gl/core';
 
+// Declare uniform block & custom shader module
+const uniformBlock = `\
+uniform highlightUniforms {
+  bool enabled;
+} highlight;
+`;
+
+type HighlightProps = {enabled: boolean};
+
+const highlightUniforms = {
+  name: 'trips',
+  fs: uniformBlock, // Only need to add block to fragment stage in this example
+  uniformTypes: {enabled: 'f32'}
+} as const satisfies ShaderModule<TripsProps>;
+
+
 class RedFilter extends LayerExtension {
   getShaders() {
-    return {
-      inject: {
-        // Declare custom uniform
-        'fs:#decl': 'uniform bool highlightRed;',
-        // Standard injection hook - see "Writing Shaders"
-        'fs:DECKGL_FILTER_COLOR': `
-          if (highlightRed) {
-            if (color.r / max(color.g, 0.001) > 2. && color.r / max(color.b, 0.001) > 2.) {
-              // is red
-              color = vec4(1.0, 0.0, 0.0, 1.0);
-            } else {
-              discard;
-            }
+    const shaders = super.getShaders();
+    shaders.inject = {
+      // Standard injection hook - see "Writing Shaders"
+      'fs:DECKGL_FILTER_COLOR': `
+        if (highlight.enabled) {
+          if (color.r / max(color.g, 0.001) > 2. && color.r / max(color.b, 0.001) > 2.) {
+            // is red
+            color = vec4(1.0, 0.0, 0.0, 1.0);
+          } else {
+            discard;
           }
-        `
-      }
+        }
+      `
     };
+
+    // Add uniform binding to shader modules
+    shaders.modules = [...shaders.modules, highlightUniforms];
+    return shaders;
   }
 
   updateState(params) {
     const {highlightRed = true} = params.props;
     for (const model of this.getModels()) {
-      model.setUniforms({highlightRed});
+      const highlightProps: HighlightProps = {enabled: props.highlightRed};
+      model.shaderInputs.setProps({highlight: highlightProps});
     }
   }
 

diff --git a/docs/developer-guide/custom-layers/layer-lifecycle.md b/docs/developer-guide/custom-layers/layer-lifecycle.md
@@ -54,7 +54,7 @@ If the layer does need to be updated,
 is called to perform any necessary operation before the layer is rendered.
 This usually involves recalculating an attribute by calling
 [`state.attributeManager.invalidate`](../../api-reference/core/attribute-manager.md#invalidate)
-and updating uniforms by calling `model.setUniforms`.
+and updating uniforms by calling `model.shaderInputs.setProps({...})`.
 By default, when `props.data` changes, all attributes are invalidated and recalculated.
 
 A composite layer may use

diff --git a/docs/table-of-contents.json b/docs/table-of-contents.json
@@ -63,6 +63,7 @@
           "developer-guide/custom-layers/picking",
           "developer-guide/custom-layers/composite-layers",
           "developer-guide/custom-layers/subclassed-layers",
+          "developer-guide/custom-layers/layer-extensions",
           "developer-guide/custom-layers/primitive-layers",
           "developer-guide/custom-layers/prop-types",
           "developer-guide/custom-layers/attribute-management",