From 58928301049ef0b3249f7844c11d5afee7ad3470 Mon Sep 17 00:00:00 2001 From: Andras Schmelczer Date: Tue, 27 Oct 2026 21:18:05 +0000 Subject: [PATCH] Fix custom drawable API docs --- docs/assets/highlight.css | 54 ++++++++----- ...ality-autoscaler.FpsQualityAutoscaler.html | 2 +- docs/functions/compile.compile.html | 2 +- .../functions/run-animation.runAnimation.html | 4 +- docs/index.html | 21 ++++- ...rawable-descriptor.DrawableDescriptor.html | 25 +++--- documentation-readme.md | 77 +++++++++++++++++++ src/drawables/drawable-descriptor.ts | 11 ++- 8 files changed, 157 insertions(+), 39 deletions(-) diff --git a/docs/assets/highlight.css b/docs/assets/highlight.css index cdcac12..28e7e6e 100644 --- a/docs/assets/highlight.css +++ b/docs/assets/highlight.css @@ -1,28 +1,32 @@ :root { - --light-hl-0: #0000FF; - --dark-hl-0: #569CD6; + --light-hl-0: #AF00DB; + --dark-hl-0: #C586C0; --light-hl-1: #000000; --dark-hl-1: #D4D4D4; --light-hl-2: #001080; --dark-hl-2: #9CDCFE; - --light-hl-3: #AF00DB; - --dark-hl-3: #C586C0; - --light-hl-4: #795E26; - --dark-hl-4: #DCDCAA; - --light-hl-5: #098658; - --dark-hl-5: #B5CEA8; - --light-hl-6: #A31515; - --dark-hl-6: #CE9178; - --light-hl-7: #0070C1; - --dark-hl-7: #4FC1FF; - --light-hl-8: #800000; - --dark-hl-8: #808080; - --light-hl-9: #800000; - --dark-hl-9: #569CD6; - --light-hl-10: #E50000; - --dark-hl-10: #9CDCFE; - --light-hl-11: #0000FF; - --dark-hl-11: #CE9178; + --light-hl-3: #A31515; + --dark-hl-3: #CE9178; + --light-hl-4: #0000FF; + --dark-hl-4: #569CD6; + --light-hl-5: #267F99; + --dark-hl-5: #4EC9B0; + --light-hl-6: #098658; + --dark-hl-6: #B5CEA8; + --light-hl-7: #008000; + --dark-hl-7: #6A9955; + --light-hl-8: #795E26; + --dark-hl-8: #DCDCAA; + --light-hl-9: #0070C1; + --dark-hl-9: #4FC1FF; + --light-hl-10: #800000; + --dark-hl-10: #808080; + --light-hl-11: #800000; + --dark-hl-11: #569CD6; + --light-hl-12: #E50000; + --dark-hl-12: #9CDCFE; + --light-hl-13: #0000FF; + --dark-hl-13: #CE9178; --light-code-background: #FFFFFF; --dark-code-background: #1E1E1E; } @@ -40,6 +44,8 @@ --hl-9: var(--light-hl-9); --hl-10: var(--light-hl-10); --hl-11: var(--light-hl-11); + --hl-12: var(--light-hl-12); + --hl-13: var(--light-hl-13); --code-background: var(--light-code-background); } } @@ -56,6 +62,8 @@ --hl-9: var(--dark-hl-9); --hl-10: var(--dark-hl-10); --hl-11: var(--dark-hl-11); + --hl-12: var(--dark-hl-12); + --hl-13: var(--dark-hl-13); --code-background: var(--dark-code-background); } } @@ -72,6 +80,8 @@ --hl-9: var(--light-hl-9); --hl-10: var(--light-hl-10); --hl-11: var(--light-hl-11); + --hl-12: var(--light-hl-12); + --hl-13: var(--light-hl-13); --code-background: var(--light-code-background); } @@ -88,6 +98,8 @@ --hl-9: var(--dark-hl-9); --hl-10: var(--dark-hl-10); --hl-11: var(--dark-hl-11); + --hl-12: var(--dark-hl-12); + --hl-13: var(--dark-hl-13); --code-background: var(--dark-code-background); } @@ -103,4 +115,6 @@ .hl-9 { color: var(--hl-9); } .hl-10 { color: var(--hl-10); } .hl-11 { color: var(--hl-11); } +.hl-12 { color: var(--hl-12); } +.hl-13 { color: var(--hl-13); } pre, code, math[display='block'] { background: var(--code-background); } diff --git a/docs/classes/graphics_rendering_fps-quality-autoscaler.FpsQualityAutoscaler.html b/docs/classes/graphics_rendering_fps-quality-autoscaler.FpsQualityAutoscaler.html index 2f27bb4..afa8435 100644 --- a/docs/classes/graphics_rendering_fps-quality-autoscaler.FpsQualityAutoscaler.html +++ b/docs/classes/graphics_rendering_fps-quality-autoscaler.FpsQualityAutoscaler.html @@ -16,7 +16,7 @@

When using this, the size of the canvas must be fixed with CSS.

The addDeltaTime method should be called once every frame.

Usage:

-
 const renderer = await compile(...);
 const autoscaler = new FpsQualityAutoscaler(renderer);
+
 const renderer = await compile(...);
 const autoscaler = new FpsQualityAutoscaler(renderer);
 

 
 
 

 

 

@@ -45,7 +46,7 @@ code of [[CircleFactory]] or [[InvertedTunnelFactory]].

 the value of empty is used to pad out arrays.

 

+
  • Defined in drawables/drawable-descriptor.ts:78
    • 
 
    
 
 
    objectCountScaler?: number
    
@@ -54,7 +55,7 @@ the value of empty is used to pad out arrays.
    
 
    By default, its value is 1
    
 
    
+
  • Defined in drawables/drawable-descriptor.ts:62
    • 
 
    
 
 
    propertyUniformMapping: { [property: string]: string }
    
@@ -62,7 +63,7 @@ the value of empty is used to pad out arrays.
    
 getObjectToSerialize and the name of the arrays used in the GLSL code.
    
 
    
+
  • Defined in drawables/drawable-descriptor.ts:18
    • 
 
    
 
 
    sdf?: { distanceFunctionName: string; isInverted?: boolean; shader: string }
    
@@ -74,10 +75,14 @@ getObjectToSerialize and the name of the arrays used in the GLSL code.
    
 
  • 
 
    distanceFunctionName: string
    
 
    The name of the function defined in the value of shader.
-Its signature should look like this:
    
-
     float (in vec2 target, out float colorIndex)
+Its signature must be:
    
+
    float distanceFunction(in vec2 target, out vec4 color)
 
    
 
+
    Replace distanceFunction with the name given here. Return the signed
+distance to the closest drawable at target and assign its RGBA color
+to color on every code path. Both WebGL and WebGL2 pass a vec4 to
+this output parameter.
    
 
    • 
 
  • 
 
    OptionalisInverted?: boolean
    
@@ -89,7 +94,7 @@ Its signature should look like this:
    
 
    Your code should work with both GLSL version 100 and version 300 es.
    
 
    • 
+
  • Defined in drawables/drawable-descriptor.ts:29
    • 
 
    
 
 
    shaderCombinationSteps: number[]
    
@@ -99,7 +104,7 @@ shader is used to render a given part of the scene.
    
 
    Must contain 0 as a value.
    
 
    
+
  • Defined in drawables/drawable-descriptor.ts:72
    • 
 
    
 
 
    uniformCountMacroName: string
    
@@ -107,7 +112,7 @@ shader is used to render a given part of the scene.
    
 number of drawables of this type.
    
 
    
+
  • Defined in drawables/drawable-descriptor.ts:24
    • 
 
    
 
    
 
    
diff --git a/documentation-readme.md b/documentation-readme.md
index 114a2b5..9b21061 100644
--- a/documentation-readme.md
+++ b/documentation-readme.md
@@ -31,6 +31,83 @@ See its [documentation](functions/run-animation.runAnimation.html) for more deta
 - Add a static `descriptor` property of type [DrawableDescriptor](interfaces/drawables_drawable-descriptor.DrawableDescriptor.html) to your class
 - Follow the instructions given in [Usage](#usage-1st-option)
 
+### Custom drawable example
+
+The function named by `sdf.distanceFunctionName` must have the signature
+`float distanceFunction(in vec2 target, out vec4 color)` in both GLSL 100 and GLSL 300 ES.
+It returns the signed distance (negative inside, zero on the boundary, positive outside)
+and writes the closest drawable's RGBA color to `color` on every code path.
+
+This complete example defines a custom orange circle, maps its serialized properties
+to shader uniforms, and compiles and renders it. Use it in a JavaScript module with
+`sdf-2d` and `gl-matrix` installed. Documentation CI runs this exact code with both
+WebGL 1 and WebGL 2.
+
+
+```js
+import { compile, Drawable } from 'sdf-2d';
+import { vec2 } from 'gl-matrix';
+
+class CustomCircle extends Drawable {
+  constructor(center, radius) {
+    super();
+    this.center = center;
+    this.radius = radius;
+  }
+
+  static descriptor = {
+    propertyUniformMapping: {
+      center: 'customCircleCenters',
+      radius: 'customCircleRadii',
+    },
+    uniformCountMacroName: 'CUSTOM_CIRCLE_COUNT',
+    shaderCombinationSteps: [0, 1, 4],
+    // Unused array entries are filled with this zero-radius circle and moved away.
+    empty: new CustomCircle([0, 0], 0),
+    sdf: {
+      distanceFunctionName: 'customCircleDistance',
+      shader: `
+        uniform vec2 customCircleCenters[CUSTOM_CIRCLE_COUNT];
+        uniform float customCircleRadii[CUSTOM_CIRCLE_COUNT];
+
+        float customCircleDistance(in vec2 target, out vec4 color) {
+          color = vec4(1.0, 0.25, 0.0, 1.0);
+          float minDistance = 1000.0;
+          for (int i = 0; i < CUSTOM_CIRCLE_COUNT; i++) {
+            float d = distance(target, customCircleCenters[i]) - customCircleRadii[i];
+            minDistance = min(minDistance, d);
+          }
+          return minDistance;
+        }
+      `,
+    },
+  };
+
+  minDistance(target) {
+    return vec2.distance(this.center, target) - this.radius;
+  }
+
+  getObjectToSerialize(transform2d, transform1d) {
+    return {
+      center: vec2.transformMat2d(vec2.create(), this.center, transform2d),
+      radius: this.radius * transform1d,
+    };
+  }
+}
+
+const canvas = document.createElement('canvas');
+canvas.width = 320;
+canvas.height = 240;
+document.body.appendChild(canvas);
+
+const renderer = await compile(canvas, [CustomCircle.descriptor]);
+renderer.setRuntimeSettings({ ambientLight: [1, 1, 1], motionBlur: 0 });
+renderer.addDrawable(new CustomCircle([160, 120], 50));
+renderer.renderDrawables();
+
+// Call renderer.destroy() when the renderer is no longer needed.
+```
+
 ## Useful to know
 
 ### Math
diff --git a/src/drawables/drawable-descriptor.ts b/src/drawables/drawable-descriptor.ts
index 1f98519..f188cd1 100644
--- a/src/drawables/drawable-descriptor.ts
+++ b/src/drawables/drawable-descriptor.ts
@@ -7,7 +7,8 @@ import { Drawable } from './drawable';
  * Each [[Drawable]] must have a static property of this type, called descriptor.
  *
  * For more information on how to create your own DrawableDescriptors, look at the
- * code of [[CircleFactory]] or [[InvertedTunnelFactory]].
+ * [complete custom drawable example](https://sdf-2d-docs.schmelczer.dev/index.html#custom-drawable-example),
+ * or the code of [[CircleFactory]] or [[InvertedTunnelFactory]].
  */
 export interface DrawableDescriptor {
   /**
@@ -34,10 +35,14 @@ export interface DrawableDescriptor {
     shader: string;
     /**
      * The name of the function defined in the value of `shader`.
-     * Its signature should look like this:
+     * Its signature must be:
      * ```glsl
-     *  float (in vec2 target, out float colorIndex)
+     * float distanceFunction(in vec2 target, out vec4 color)
      * ```
+     * Replace `distanceFunction` with the name given here. Return the signed
+     * distance to the closest drawable at `target` and assign its RGBA color
+     * to `color` on every code path. Both WebGL and WebGL2 pass a `vec4` to
+     * this output parameter.
      */
     distanceFunctionName: string;