shaderpad 1.0.0-beta.38 → 1.0.0-beta.40

package/README.md

@@ -15,7 +15,6 @@ npm install shaderpad
 ```typescript
 import ShaderPad from 'shaderpad';
 
-// Your custom GLSL fragment shader code.
 const fragmentShaderSrc = `#version 300 es
 precision highp float;
 
@@ -35,43 +34,24 @@ void main() {
   vec2 dotGrid = mod(uv, 50.) - 25.;
   float dotDist = length(dotGrid);
   float dot = step(dotDist, 5.);
-
   float cursorDist = distance(uv, u_cursor * u_resolution);
   float cursor = step(cursorDist, 25. + sin(u_time * 5.) * 5.);
-
   vec3 color = mix(vec3(0., 0., 1.), vec3(1.), dot);
   color = mix(color, u_cursorColor, cursor);
-
   outColor = vec4(color, 1.);
 }
 `;
 
-// Initialize the shader.
 const shader = new ShaderPad(fragmentShaderSrc /* , options */);
-
-// Add your own custom uniforms.
 const getColor = (time: number) =>
 	[time, time + (Math.PI * 2) / 3, time + (Math.PI * 4) / 3].map(x => 1 + Math.sin(x) / 2);
 shader.initializeUniform('u_cursorColor', 'float', getColor(0));
-
-// Start the render loop.
 shader.play(time => {
 	shader.updateUniforms({ u_cursorColor: getColor(time) });
 });
-
-// Optionally pause or reset the render loop.
-// shader.pause();
-// shader.reset();
-
-// ShaderPad also attaches a throttled resize observer that you can hook into.
-// It fires when the canvas size changes visually. If you supplied a custom
-// canvas, you may use this to update its `width` and `height` attributes.
-// shader.onResize = (width, height) => {
-// 	console.log('Canvas resized:', width, height);
-// };
 ```
 
-See the [`examples/` directory](./examples/) for more.
+See the [`examples/` directory](./examples/src) for more.
 
 ## Usage
 
@@ -79,26 +59,26 @@ See the [`examples/` directory](./examples/) for more.
 
 #### `initializeUniform(name, type, value, options?)`
 
-Initialize a uniform variable. The uniform must be declared in your fragment shader.
+Initialize a uniform, which must be declared in your shader.
 
 ```typescript
-// Initialize a float uniform.
 shader.initializeUniform('u_speed', 'float', 1.5);
-
-// Initialize a vec3 uniform.
+// Vectors are passed as arrays. This is a vec3:
 shader.initializeUniform('u_color', 'float', [1.0, 0.5, 0.0]);
+// …but you can also pass an array. This is an array of floats:
+shader.initializeUniform('u_data', 'float', [1.0, 0.5, 0.0], { arrayLength: 3 });
 ```
 
 **Parameters:**
 
--   `name` (string): The name of the uniform as declared in your shader
--   `type` ('float' | 'int'): The uniform type
+-   `name` (string): Uniform name
+-   `type` ('float' | 'int'): Uniform type
 -   `value` (number | number[] | (number | number[])[]): Initial value(s)
--   `options` (optional): `{ arrayLength?: number }` - Required for uniform arrays
+-   `options` (optional): `{ arrayLength?: number }` - Required for arrays
 
 #### `updateUniforms(updates, options?)`
 
-Update one or more uniform values.
+Update uniform values.
 
 ```typescript
 shader.updateUniforms({
@@ -109,7 +89,7 @@ shader.updateUniforms({
 
 **Parameters:**
 
--   `updates` (Record<string, number | number[] | (number | number[])[]>): Object mapping uniform names to their new values
+-   `updates`: Object mapping uniform names to their new values
 -   `options` (optional): `{ startIndex?: number }` - Starting index for partial array updates
 
 #### Uniform arrays
@@ -125,12 +105,8 @@ shader.initializeUniform(
 		[0, 0],
 		[1, 1],
 		[2, 2],
-		[3, 3],
-		[4, 4],
 	],
-	{
-		arrayLength: 5,
-	}
+	{ arrayLength: 3 }
 );
 
 // Update all elements.
@@ -139,8 +115,6 @@ shader.updateUniforms({
 		[0.1, 0.2],
 		[1.1, 1.2],
 		[2.1, 2.2],
-		[3.1, 3.2],
-		[4.1, 4.2],
 	],
 });
 
@@ -178,25 +152,13 @@ shader.updateUniforms(
 
 #### `initializeTexture(name, source, options?)`
 
-Initialize a texture from an image, video, canvas element, or typed array.
+Initialize a texture from an image, video, canvas, or typed array.
 
 ```typescript
-// Initialize a texture from an image.
-const img = new Image();
-img.src = 'texture.png';
-img.onload = () => {
-	shader.initializeTexture('u_texture', img);
-};
-
-// Initialize a texture from a typed array (Float32Array, Uint8Array, etc.).
-const data = new Float32Array(width * height * 4); // RGBA data
+shader.initializeTexture('u_texture', img);
 shader.initializeTexture(
 	'u_custom',
-	{
-		data,
-		width,
-		height,
-	},
+	{ data: new Float32Array(width * height * 4), width, height },
 	{
 		internalFormat: gl.RGBA32F,
 		type: gl.FLOAT,
@@ -204,19 +166,15 @@ shader.initializeTexture(
 		magFilter: gl.NEAREST,
 	}
 );
-
-// Initialize a texture with history (stores previous frames).
 shader.initializeTexture('u_webcam', videoElement, { history: 30 });
-
-// Preserve Y orientation for DOM sources (don't flip vertically).
 shader.initializeTexture('u_canvas', canvasElement, { preserveY: true });
 ```
 
 **Parameters:**
 
 -   `name` (string): The name of the texture uniform as declared in your shader
--   `source` (HTMLImageElement | HTMLVideoElement | HTMLCanvasElement | CustomTexture): The texture source
 -   `options` (optional): Texture options (see below)
+-   `source`: Image, video, canvas, or `{ data, width, height }`
 
 **Texture Options:**
 
@@ -232,52 +190,85 @@ shader.initializeTexture('u_canvas', canvasElement, { preserveY: true });
 
 **Note:** For typed array sources (`CustomTexture`), you must provide data in bottom-up orientation (WebGL convention). The `preserveY` option is ignored for typed arrays.
 
-#### `updateTextures(updates)`
-
-Update one or more textures. Useful for updating video textures each frame.
+#### `updateTextures(updates, options?)`
 
 ```typescript
+shader.updateTextures({ u_webcam: videoElement, u_overlay: overlayCanvas });
 shader.updateTextures({
-	u_webcam: videoElement,
-	u_overlay: overlayCanvas,
-	u_custom: {
-		data: typedArray,
-		width,
-		height,
-	},
-});
-
-// Typed arrays can be partially updated.
-shader.updateTextures({
-	u_custom: {
-		data: partialData,
-		width: regionWidth,
-		height: regionHeight,
-		isPartial: true,
-		x: offsetX,
-		y: offsetY,
-	},
+	u_custom: { data: partialData, width, height, isPartial: true, x: offsetX, y: offsetY },
 });
+shader.updateTextures({ u_camera: videoElement }, { skipHistoryWrite: true });
 ```
 
 **Parameters:**
 
--   `updates` (Record<string, TextureSource | PartialCustomTexture>): Object mapping texture names to their new sources
+-   `updates`: Object mapping texture names to updated sources
+-   `options?` (optional): `{ skipHistoryWrite?: boolean }`
 
 ### Lifecycle methods
 
-#### `play(callback?)`
+#### `play(onStepComplete?, setStepOptions?)`
 
-Start the render loop. The callback is invoked each frame with the current time and frame number.
+Start the render loop.
 
 ```typescript
 shader.play();
-// Can optionally take a callback to invoke each frame.
+
+// With per-frame callbacks.
 shader.play((time, frame) => {
 	shader.updateTextures({ u_webcam: videoElement });
 });
+
+shader.play(null, (time, frame) => {
+	// Only save every 10th frame to history.
+	return { skipHistoryWrite: frame % 10 === 0 };
+});
+```
+
+**Parameters:**
+
+-   `onStepComplete?`: `(time: number, frame: number) => void` - Called after each frame
+-   `setStepOptions?`: `(time: number, frame: number) => StepOptions | void` - Called before each frame
+
+#### `step(time, options?)`
+
+Manually advance one frame. Updates `u_time` and `u_frame`, then renders.
+
+```typescript
+shader.step(5.0); // Render at 5 seconds.
+```
+
+**Parameters:**
+
+-   `time` (number): The current time in seconds
+-   `options?` (optional): `StepOptions` - Options to control rendering behavior (see below)
+
+#### `draw(options?)`
+
+Render without updating uniforms or frame counter.
+
+```typescript
+shader.draw({ skipClear: true });
+```
+
+**Parameters:**
+
+-   `options?` (optional): `StepOptions` - Options to control rendering behavior (see below)
+
+#### `StepOptions`
+
+```typescript
+interface StepOptions {
+	skipClear?: boolean; // Skip clearing canvas before rendering
+	skipHistoryWrite?: boolean; // Skip writing to history buffers
+}
 ```
 
+**Options:**
+
+-   `skipClear?: boolean` - If `true`, the canvas is not cleared before rendering. Useful for accumulating effects or multi-pass rendering.
+-   `skipHistoryWrite?: boolean` - If `true`, history buffers are not updated. Useful when you want to render without affecting the history state.
+
 #### `pause()`, `reset()`, `destroy()`
 
 ```typescript
@@ -310,7 +301,7 @@ shader.onResize = (width, height) => {
 
 ### history
 
-The `history` option enables framebuffer history, allowing you to access previous frames in your shader. Pass a number to specify how many frames to keep.
+Enable framebuffer history to access previous frames.
 
 ```typescript
 // Store the last 10 frames of shader output.
@@ -353,380 +344,149 @@ vec4 historyColor = texture(u_webcam, vec3(v_uv, zIndex));
 
 ### debug
 
-The `debug` option controls whether debug logging is enabled. When enabled, ShaderPad will log warnings when uniforms or textures are not found in the shader. Defaults to `true` in development (when `process.env.NODE_ENV !== 'production'`) and `false` in production builds.
+Enable debug logging. Defaults to `true` in development, `false` in production.
 
 ```typescript
-const shader = new ShaderPad(fragmentShaderSrc, { debug: true }); // Explicitly enable debug logging.
+const shader = new ShaderPad(fragmentShaderSrc, { debug: true });
 ```
 
 ### plugins
 
-ShaderPad supports plugins to add additional functionality. Plugins are imported from separate paths to keep bundle sizes small.
+Plugins add additional functionality. Imported from separate paths to keep bundle sizes small.
 
 #### helpers
 
-The `helpers` plugin provides convenience functions and constants. See [helpers.glsl](./src/plugins/helpers.glsl) for the implementation.
+Convenience functions and constants. See [helpers.glsl](./src/plugins/helpers.glsl).
 
 ```typescript
-import ShaderPad from 'shaderpad';
 import helpers from 'shaderpad/plugins/helpers';
-
-const shader = new ShaderPad(fragmentShaderSrc, {
-	plugins: [helpers()],
-});
+const shader = new ShaderPad(fragmentShaderSrc, { plugins: [helpers()] });
 ```
 
-**Note:** The `helpers` plugin automatically injects the `u_resolution` uniform into your shader. Do not declare it yourself.
+**Note:** Automatically injects `u_resolution`. Don't declare it yourself.
 
 #### save
 
-The `save` plugin adds a `.save()` method to the shader that saves the current frame to a PNG file. It works on desktop and mobile.
+Adds `.save()` method to save the current frame as PNG.
 
 ```typescript
-import ShaderPad from 'shaderpad';
 import save, { WithSave } from 'shaderpad/plugins/save';
-
 const shader = new ShaderPad(fragmentShaderSrc, { plugins: [save()] }) as WithSave<ShaderPad>;
 shader.save('filename', 'Optional mobile share text');
 ```
 
 #### face
 
-The `face` plugin uses [MediaPipe](https://ai.google.dev/edge/mediapipe/solutions/vision/face_landmarker) to detect faces in video or image textures.
+Uses [MediaPipe Face Landmarker](https://ai.google.dev/edge/mediapipe/solutions/vision/face_landmarker) to detect faces.
 
 ```typescript
-import ShaderPad from 'shaderpad';
 import face from 'shaderpad/plugins/face';
-
 const shader = new ShaderPad(fragmentShaderSrc, {
-	plugins: [
-		face({
-			textureName: 'u_webcam',
-			options: { maxFaces: 3 },
-		}),
-	],
+	plugins: [face({ textureName: 'u_webcam', options: { maxFaces: 3 } })],
 });
 ```
 
-**Options:**
-
--   `onReady?: () => void` - Callback invoked when initialization is complete and the detection model is loaded
--   `onResults?: (results: FaceLandmarkerResult) => void` - Callback invoked with detection results each frame
-
-**Uniforms:**
-
-| Uniform              | Type      | Description                                                                 |
-| -------------------- | --------- | --------------------------------------------------------------------------- |
-| `u_maxFaces`         | int       | Maximum number of faces to detect                                           |
-| `u_nFaces`           | int       | Current number of detected faces                                            |
-| `u_faceLandmarksTex` | sampler2D | Raw landmark data texture (use `faceLandmark()` to access)                  |
-| `u_faceMask`         | sampler2D | Face mask texture (R: region type, G: confidence, B: normalized face index) |
-
-**Helper functions:**
-
-All region functions return `vec2(confidence, faceIndex)`. faceIndex is 0-indexed (-1 = no face).
-
--   `faceLandmark(int faceIndex, int landmarkIndex) -> vec4` - Returns landmark data as `vec4(x, y, z, visibility)`. Use `vec2(faceLandmark(...))` to get just the screen position.
--   `leftEyebrowAt(vec2 pos) -> vec2` - Returns `vec2(1.0, faceIndex)` if position is in left eyebrow, `vec2(0.0, -1.0)` otherwise.
--   `rightEyebrowAt(vec2 pos) -> vec2` - Returns `vec2(1.0, faceIndex)` if position is in right eyebrow, `vec2(0.0, -1.0)` otherwise.
--   `leftEyeAt(vec2 pos) -> vec2` - Returns `vec2(1.0, faceIndex)` if position is in left eye, `vec2(0.0, -1.0)` otherwise.
--   `rightEyeAt(vec2 pos) -> vec2` - Returns `vec2(1.0, faceIndex)` if position is in right eye, `vec2(0.0, -1.0)` otherwise.
--   `lipsAt(vec2 pos) -> vec2` - Returns `vec2(1.0, faceIndex)` if position is in lips, `vec2(0.0, -1.0)` otherwise.
--   `outerMouthAt(vec2 pos) -> vec2` - Returns `vec2(1.0, faceIndex)` if position is in outer mouth (lips + inner mouth), `vec2(0.0, -1.0)` otherwise.
--   `innerMouthAt(vec2 pos) -> vec2` - Returns `vec2(1.0, faceIndex)` if position is in inner mouth region, `vec2(0.0, -1.0)` otherwise.
--   `faceOvalAt(vec2 pos) -> vec2` - Returns `vec2(1.0, faceIndex)` if position is in face oval contour, `vec2(0.0, -1.0)` otherwise.
--   `faceAt(vec2 pos) -> vec2` - Returns `vec2(1.0, faceIndex)` if position is in face mesh or oval contour, `vec2(0.0, -1.0)` otherwise.
--   `eyeAt(vec2 pos) -> vec2` - Returns `vec2(1.0, faceIndex)` if position is in either eye, `vec2(0.0, -1.0)` otherwise.
--   `eyebrowAt(vec2 pos) -> vec2` - Returns `vec2(1.0, faceIndex)` if position is in either eyebrow, `vec2(0.0, -1.0)` otherwise.
-
-**Convenience functions** (return `1.0` if true, `0.0` if false):
+**Options:** `onReady?: () => void`, `onResults?: (results: FaceLandmarkerResult) => void`
 
--   `inFace(vec2 pos) -> float` - Returns `1.0` if position is in face mesh, `0.0` otherwise.
--   `inEye(vec2 pos) -> float` - Returns `1.0` if position is in either eye, `0.0` otherwise.
--   `inEyebrow(vec2 pos) -> float` - Returns `1.0` if position is in either eyebrow, `0.0` otherwise.
--   `inOuterMouth(vec2 pos) -> float` - Returns `1.0` if position is in outer mouth (lips + inner mouth), `0.0` otherwise.
--   `inInnerMouth(vec2 pos) -> float` - Returns `1.0` if position is in inner mouth, `0.0` otherwise.
--   `inLips(vec2 pos) -> float` - Returns `1.0` if position is in lips, `0.0` otherwise.
+**Uniforms:** `u_maxFaces` (int), `u_nFaces` (int), `u_faceLandmarksTex` (sampler2D), `u_faceMask` (sampler2D)
 
-**Landmark Constants:**
+**Helper functions:** All region functions return `vec2(confidence, faceIndex)`. faceIndex is 0-indexed (-1 = no face).
 
--   `FACE_LANDMARK_L_EYE_CENTER` - Left eye center landmark index
--   `FACE_LANDMARK_R_EYE_CENTER` - Right eye center landmark index
--   `FACE_LANDMARK_NOSE_TIP` - Nose tip landmark index
--   `FACE_LANDMARK_FACE_CENTER` - Face center landmark index (custom, calculated from all landmarks)
--   `FACE_LANDMARK_MOUTH_CENTER` - Mouth center landmark index (custom, calculated from inner mouth landmarks)
+-   `faceLandmark(int faceIndex, int landmarkIndex) -> vec4` - Returns `vec4(x, y, z, visibility)`
+-   `leftEyebrowAt(vec2 pos) -> vec2`, `rightEyebrowAt(vec2 pos) -> vec2`
+-   `leftEyeAt(vec2 pos) -> vec2`, `rightEyeAt(vec2 pos) -> vec2`
+-   `lipsAt(vec2 pos) -> vec2`, `outerMouthAt(vec2 pos) -> vec2`, `innerMouthAt(vec2 pos) -> vec2`
+-   `faceOvalAt(vec2 pos) -> vec2`, `faceAt(vec2 pos) -> vec2`
+-   `eyeAt(vec2 pos) -> vec2`, `eyebrowAt(vec2 pos) -> vec2`
 
-**Example usage:**
+**Convenience functions:** `inFace(vec2 pos) -> float`, `inEye(vec2 pos) -> float`, `inEyebrow(vec2 pos) -> float`, `inOuterMouth(vec2 pos) -> float`, `inInnerMouth(vec2 pos) -> float`, `inLips(vec2 pos) -> float`
 
-```glsl
-// Get a specific landmark position.
-vec2 nosePos = vec2(faceLandmark(0, FACE_LANDMARK_NOSE_TIP));
-
-// Use in* convenience functions for simple boolean checks.
-float eyeMask = inEye(v_uv);
-
-// Use faceLandmark or *At functions when you need to check a specific face index.
-vec2 leftEye = leftEyeAt(v_uv);
-for (int i = 0; i < u_nFaces; ++i) {
-    vec4 leftEyeCenter = faceLandmark(i, FACE_LANDMARK_L_EYE_CENTER);
-    vec4 rightEyeCenter = faceLandmark(i, FACE_LANDMARK_R_EYE_CENTER);
-	if (leftEye.x > 0.0 && int(leftEye.y) == i) {
-		// Position is inside the left eye of face i.
-	}
-    // ...
-}
-```
+**Constants:** `FACE_LANDMARK_L_EYE_CENTER`, `FACE_LANDMARK_R_EYE_CENTER`, `FACE_LANDMARK_NOSE_TIP`, `FACE_LANDMARK_FACE_CENTER`, `FACE_LANDMARK_MOUTH_CENTER`
 
-[Landmark indices are documented here.](https://ai.google.dev/edge/mediapipe/solutions/vision/face_landmarker#face_landmarker_model) This library adds two custom landmarks: `FACE_CENTER` and `MOUTH_CENTER`. This brings the total landmark count to 480.
-
-**Note:** The face plugin requires `@mediapipe/tasks-vision` as a peer dependency.
+**Note:** Requires `@mediapipe/tasks-vision` as a peer dependency. Adds two custom landmarks (`FACE_CENTER`, `MOUTH_CENTER`), bringing total to 480.
 
 #### pose
 
-The `pose` plugin uses [MediaPipe Pose Landmarker](https://ai.google.dev/edge/mediapipe/solutions/vision/pose_landmarker) to expose a flat array of 2D landmarks. Each pose contributes 39 landmarks (33 standard + 6 custom), enumerated below.
+Uses [MediaPipe Pose Landmarker](https://ai.google.dev/edge/mediapipe/solutions/vision/pose_landmarker). Each pose contributes 39 landmarks (33 standard + 6 custom).
 
 ```typescript
-import ShaderPad from 'shaderpad';
 import pose from 'shaderpad/plugins/pose';
-
 const shader = new ShaderPad(fragmentShaderSrc, {
 	plugins: [pose({ textureName: 'u_video', options: { maxPoses: 3 } })],
 });
 ```
 
-**Options:**
-
--   `onReady?: () => void` - Callback invoked when initialization is complete and the detection model is loaded
--   `onResults?: (results: PoseLandmarkerResult) => void` - Callback invoked with detection results each frame
+**Options:** `onReady?: () => void`, `onResults?: (results: PoseLandmarkerResult) => void`
 
-**Uniforms:**
-
-| Uniform              | Type      | Description                                                                   |
-| -------------------- | --------- | ----------------------------------------------------------------------------- |
-| `u_maxPoses`         | int       | Maximum number of poses to track                                              |
-| `u_nPoses`           | int       | Current number of detected poses                                              |
-| `u_poseLandmarksTex` | sampler2D | Raw landmark data texture (RGBA: x, y, z, visibility)                         |
-| `u_poseMask`         | sampler2D | Pose mask texture (R: body detected, G: confidence, B: normalized pose index) |
+**Uniforms:** `u_maxPoses` (int), `u_nPoses` (int), `u_poseLandmarksTex` (sampler2D), `u_poseMask` (sampler2D)
 
 **Helper functions:**
 
--   `poseLandmark(int poseIndex, int landmarkIndex) -> vec4` - Returns landmark data as `vec4(x, y, z, visibility)`. Use `vec2(poseLandmark(...))` to get just the screen position.
--   `poseAt(vec2 pos) -> vec2` - Returns `vec2(confidence, poseIndex)`. poseIndex is 0-indexed (-1 = no pose), confidence is the segmentation confidence.
--   `inPose(vec2 pos) -> float` - Returns `1.0` if position is in any pose, `0.0` otherwise.
-
-**Constants:**
-
--   `POSE_LANDMARK_LEFT_EYE` - Left eye landmark index (2)
--   `POSE_LANDMARK_RIGHT_EYE` - Right eye landmark index (5)
--   `POSE_LANDMARK_LEFT_SHOULDER` - Left shoulder landmark index (11)
--   `POSE_LANDMARK_RIGHT_SHOULDER` - Right shoulder landmark index (12)
--   `POSE_LANDMARK_LEFT_ELBOW` - Left elbow landmark index (13)
--   `POSE_LANDMARK_RIGHT_ELBOW` - Right elbow landmark index (14)
--   `POSE_LANDMARK_LEFT_HIP` - Left hip landmark index (23)
--   `POSE_LANDMARK_RIGHT_HIP` - Right hip landmark index (24)
--   `POSE_LANDMARK_LEFT_KNEE` - Left knee landmark index (25)
--   `POSE_LANDMARK_RIGHT_KNEE` - Right knee landmark index (26)
--   `POSE_LANDMARK_BODY_CENTER` - Body center landmark index (33, custom, calculated from all landmarks)
--   `POSE_LANDMARK_LEFT_HAND_CENTER` - Left hand center landmark index (34, custom, calculated from pinky, thumb, wrist, index)
--   `POSE_LANDMARK_RIGHT_HAND_CENTER` - Right hand center landmark index (35, custom, calculated from pinky, thumb, wrist, index)
--   `POSE_LANDMARK_LEFT_FOOT_CENTER` - Left foot center landmark index (36, custom, calculated from ankle, heel, foot index)
--   `POSE_LANDMARK_RIGHT_FOOT_CENTER` - Right foot center landmark index (37, custom, calculated from ankle, heel, foot index)
--   `POSE_LANDMARK_TORSO_CENTER` - Torso center landmark index (38, custom, calculated from shoulders and hips)
-
-**Note:** For connecting pose landmarks (e.g., drawing skeleton lines), `PoseLandmarker.POSE_CONNECTIONS` from `@mediapipe/tasks-vision` provides an array of `{ start, end }` pairs that define which landmarks should be connected.
-
-Use `poseLandmark(int poseIndex, int landmarkIndex)` in GLSL to retrieve a specific point. Landmark indices are:
-
-| Index | Landmark          | Index | Landmark                   |
-| ----- | ----------------- | ----- | -------------------------- |
-| 0     | nose              | 20    | right index                |
-| 1     | left eye (inner)  | 21    | left thumb                 |
-| 2     | left eye          | 22    | right thumb                |
-| 3     | left eye (outer)  | 23    | left hip                   |
-| 4     | right eye (inner) | 24    | right hip                  |
-| 5     | right eye         | 25    | left knee                  |
-| 6     | right eye (outer) | 26    | right knee                 |
-| 7     | left ear          | 27    | left ankle                 |
-| 8     | right ear         | 28    | right ankle                |
-| 9     | mouth (left)      | 29    | left heel                  |
-| 10    | mouth (right)     | 30    | right heel                 |
-| 11    | left shoulder     | 31    | left foot index            |
-| 12    | right shoulder    | 32    | right foot index           |
-| 13    | left elbow        | 33    | body center (custom)       |
-| 14    | right elbow       | 34    | left hand center (custom)  |
-| 15    | left wrist        | 35    | right hand center (custom) |
-| 16    | right wrist       | 36    | left foot center (custom)  |
-| 17    | left pinky        | 37    | right foot center (custom) |
-| 18    | right pinky       | 38    | torso center (custom)      |
-| 19    | left index        |       |                            |
-
-[Source](https://ai.google.dev/edge/mediapipe/solutions/vision/pose_landmarker#pose_landmarker_model)
-
-[Landmark indices are documented here.](https://ai.google.dev/edge/mediapipe/solutions/vision/pose_landmarker#pose_landmarker_model) This library adds six custom landmarks: `BODY_CENTER`, `LEFT_HAND_CENTER`, `RIGHT_HAND_CENTER`, `LEFT_FOOT_CENTER`, `RIGHT_FOOT_CENTER`, and `TORSO_CENTER`. This brings the total landmark count to 39.
-
-A minimal fragment shader loop looks like:
+-   `poseLandmark(int poseIndex, int landmarkIndex) -> vec4` - Returns `vec4(x, y, z, visibility)`
+-   `poseAt(vec2 pos) -> vec2` - Returns `vec2(confidence, poseIndex)`
+-   `inPose(vec2 pos) -> float`
 
-```glsl
-for (int i = 0; i < u_maxPoses; ++i) {
-	if (i >= u_nPoses) break;
-	vec2 leftHip = vec2(poseLandmark(i, POSE_LANDMARK_LEFT_HIP));
-	vec2 rightHip = vec2(poseLandmark(i, POSE_LANDMARK_RIGHT_HIP));
-	// …
-}
-```
+**Constants:** `POSE_LANDMARK_LEFT_EYE`, `POSE_LANDMARK_RIGHT_EYE`, `POSE_LANDMARK_LEFT_SHOULDER`, `POSE_LANDMARK_RIGHT_SHOULDER`, `POSE_LANDMARK_LEFT_ELBOW`, `POSE_LANDMARK_RIGHT_ELBOW`, `POSE_LANDMARK_LEFT_HIP`, `POSE_LANDMARK_RIGHT_HIP`, `POSE_LANDMARK_LEFT_KNEE`, `POSE_LANDMARK_RIGHT_KNEE`, `POSE_LANDMARK_BODY_CENTER`, `POSE_LANDMARK_LEFT_HAND_CENTER`, `POSE_LANDMARK_RIGHT_HAND_CENTER`, `POSE_LANDMARK_LEFT_FOOT_CENTER`, `POSE_LANDMARK_RIGHT_FOOT_CENTER`, `POSE_LANDMARK_TORSO_CENTER`
+
+**Note:** Requires `@mediapipe/tasks-vision`. Use `PoseLandmarker.POSE_CONNECTIONS` for skeleton connections. [Landmark indices](https://ai.google.dev/edge/mediapipe/solutions/vision/pose_landmarker#pose_landmarker_model)
 
 #### hands
 
-The `hands` plugin uses [MediaPipe Hand Landmarker](https://ai.google.dev/edge/mediapipe/solutions/vision/hand_landmarker) to expose a flat array of 2D landmarks. Each hand contributes 22 landmarks, enumerated below.
+Uses [MediaPipe Hand Landmarker](https://ai.google.dev/edge/mediapipe/solutions/vision/hand_landmarker). Each hand contributes 22 landmarks.
 
 ```typescript
-import ShaderPad from 'shaderpad';
 import hands from 'shaderpad/plugins/hands';
-
 const shader = new ShaderPad(fragmentShaderSrc, {
 	plugins: [hands({ textureName: 'u_video', options: { maxHands: 2 } })],
 });
 ```
 
-**Options:**
-
--   `onReady?: () => void` - Callback invoked when initialization is complete and the detection model is loaded
--   `onResults?: (results: HandLandmarkerResult) => void` - Callback invoked with detection results each frame
+**Options:** `onReady?: () => void`, `onResults?: (results: HandLandmarkerResult) => void`
 
-**Uniforms:**
-
-| Uniform              | Type      | Description                                           |
-| -------------------- | --------- | ----------------------------------------------------- |
-| `u_maxHands`         | int       | Maximum number of hands to track                      |
-| `u_nHands`           | int       | Current number of detected hands                      |
-| `u_handLandmarksTex` | sampler2D | Raw landmark data texture (RGBA: x, y, z, handedness) |
+**Uniforms:** `u_maxHands` (int), `u_nHands` (int), `u_handLandmarksTex` (sampler2D)
 
 **Helper functions:**
 
--   `handLandmark(int handIndex, int landmarkIndex) -> vec4` - Returns landmark data as `vec4(x, y, z, handedness)`. Use `vec2(handLandmark(...))` to get just the screen position. Handedness: 0.0 = left hand, 1.0 = right hand.
--   `isRightHand(int handIndex) -> float` - Returns 1.0 if the hand is a right hand, 0.0 if left.
--   `isLeftHand(int handIndex) -> float` - Returns 1.0 if the hand is a left hand, 0.0 if right.
-
-**Landmark Indices:**
-
-| Index | Landmark          | Index | Landmark          |
-| ----- | ----------------- | ----- | ----------------- |
-| 0     | WRIST             | 11    | MIDDLE_FINGER_DIP |
-| 1     | THUMB_CMC         | 12    | MIDDLE_FINGER_TIP |
-| 2     | THUMB_MCP         | 13    | RING_FINGER_MCP   |
-| 3     | THUMB_IP          | 14    | RING_FINGER_PIP   |
-| 4     | THUMB_TIP         | 15    | RING_FINGER_DIP   |
-| 5     | INDEX_FINGER_MCP  | 16    | RING_FINGER_TIP   |
-| 6     | INDEX_FINGER_PIP  | 17    | PINKY_MCP         |
-| 7     | INDEX_FINGER_DIP  | 18    | PINKY_PIP         |
-| 8     | INDEX_FINGER_TIP  | 19    | PINKY_DIP         |
-| 9     | MIDDLE_FINGER_MCP | 20    | PINKY_TIP         |
-| 10    | MIDDLE_FINGER_PIP | 21    | HAND_CENTER       |
+-   `handLandmark(int handIndex, int landmarkIndex) -> vec4` - Returns `vec4(x, y, z, handedness)`. Handedness: 0.0 = left, 1.0 = right.
+-   `isRightHand(int handIndex) -> float`, `isLeftHand(int handIndex) -> float`
 
-[Source](https://ai.google.dev/edge/mediapipe/solutions/vision/hand_landmarker#models)
-
-A minimal fragment shader loop looks like:
-
-```glsl
-#define WRIST 0
-#define THUMB_TIP 4
-#define INDEX_TIP 8
-#define HAND_CENTER 21
-
-for (int i = 0; i < u_maxHands; ++i) {
-	if (i >= u_nHands) break;
-	vec2 wrist = vec2(handLandmark(i, WRIST));
-	vec2 thumbTip = vec2(handLandmark(i, THUMB_TIP));
-	vec2 indexTip = vec2(handLandmark(i, INDEX_TIP));
-	vec2 handCenter = vec2(handLandmark(i, HAND_CENTER));
-
-	// Use handedness for coloring (0.0 = left/black, 1.0 = right/white).
-	vec3 handColor = vec3(isRightHand(i));
-	// …
-}
-```
-
-**Note:** The hands plugin requires `@mediapipe/tasks-vision` as a peer dependency.
+**Note:** Requires `@mediapipe/tasks-vision`. [Landmark indices](https://ai.google.dev/edge/mediapipe/solutions/vision/hand_landmarker#models)
 
 #### segmenter
 
-The `segmenter` plugin uses [MediaPipe Image Segmenter](https://ai.google.dev/edge/mediapipe/solutions/vision/image_segmenter) to segment objects in video or image textures. It supports models with multiple categories (e.g., background, hair, chair, dog…). By default, it uses the [hair segmentation model](https://ai.google.dev/edge/mediapipe/solutions/vision/image_segmenter#hair-model).
+Uses [MediaPipe Image Segmenter](https://ai.google.dev/edge/mediapipe/solutions/vision/image_segmenter). Supports multi-category models. Defaults to [hair segmentation model](https://ai.google.dev/edge/mediapipe/solutions/vision/image_segmenter#hair-model).
 
 ```typescript
-import ShaderPad from 'shaderpad';
 import segmenter from 'shaderpad/plugins/segmenter';
-
 const shader = new ShaderPad(fragmentShaderSrc, {
-	plugins: [
-		segmenter({
-			textureName: 'u_webcam',
-			options: {
-				modelPath:
-					'https://storage.googleapis.com/mediapipe-models/image_segmenter/selfie_multiclass_256x256/float32/latest/selfie_multiclass_256x256.tflite',
-				outputCategoryMask: true,
-				onReady: () => {
-					console.log('Selfie multiclass model: loading complete');
-				},
-			},
-		}),
-	],
+	plugins: [segmenter({ textureName: 'u_webcam', options: { outputCategoryMask: true } })],
 });
 ```
 
-**Options:**
-
--   `onReady?: () => void` - Callback invoked when initialization is complete and the detection model is loaded
--   `onResults?: (results: ImageSegmenterResult) => void` - Callback invoked with segmentation results each frame
+**Options:** `onReady?: () => void`, `onResults?: (results: ImageSegmenterResult) => void`
 
-**Uniforms:**
-
-| Uniform           | Type      | Description                                                             |
-| ----------------- | --------- | ----------------------------------------------------------------------- |
-| `u_segmentMask`   | sampler2D | Segment mask texture (R: normalized category, G: confidence, B: unused) |
-| `u_numCategories` | int       | Number of segmentation categories (including background)                |
+**Uniforms:** `u_segmentMask` (sampler2D), `u_numCategories` (int)
 
 **Helper functions:**
 
--   `segmentAt(vec2 pos) -> vec2` - Returns `vec2(confidence, categoryIndex)`. categoryIndex is 0-indexed (-1 = background). confidence is the segmentation confidence (0-1).
-
-**Example usage:**
+-   `segmentAt(vec2 pos) -> vec2` - Returns `vec2(confidence, categoryIndex)`. categoryIndex is 0-indexed (-1 = background).
 
-```glsl
-vec2 segment = segmentAt(v_uv);
-float confidence = segment.x;  // Segmentation confidence
-float category = segment.y;    // Category index (0-indexed, -1 = background)
-
-if (category >= 0.0) {
-	// Apply effect based on confidence.
-	color = mix(color, vec3(1.0, 0.0, 1.0), confidence);
-}
-```
-
-**Note:** The segmenter plugin requires `@mediapipe/tasks-vision` as a peer dependency.
+**Note:** Requires `@mediapipe/tasks-vision` as a peer dependency.
 
 ## Contributing
 
 ### Running an example
 
 ```bash
-# Clone the repository.
 git clone https://github.com/rileyjshaw/shaderpad.git
-cd shaderpad
-
-# Install dependencies and start the development server.
-cd examples
+cd shaderpad/examples
 npm install
 npm run dev
 ```
 
-This will launch a local server. Open the provided URL (usually `http://localhost:5173`) in your browser to view and interact with the examples. Use the select box to view different examples.
-
 ### Adding an example
 
--   Add a new `.ts` file in `examples/src/`.
--   Follow the structure of an existing example as a template. The example must export an `init` function and a `destroy` function.
--   Add the example to the `demos` array in `examples/src/main.ts`.
--   If your example needs images or other assets, place them in `examples/public/` and reference them with a relative path.
+Add a `.ts` file in `examples/src/` that exports `init` and `destroy` functions. Add it to the `demos` array in `examples/src/main.ts`.
 
 ## License