# ShaderPad

ShaderPad is a lightweight WebGL2 library for fragment shaders, live textures, history buffers, fullscreen canvas workflows, and optional MediaPipe-powered plugins for face, pose, hands, and segmentation.

Use this file as the small discovery layer. If you want the full docs corpus in one fetch, use [llms-full.txt](https://misery.co/shaderpad/llms-full.txt). If you want a structured machine-readable page catalog with titles, descriptions, and source URLs, use [llms-index.json](https://misery.co/shaderpad/llms-index.json). If you want local example source mirrors without leaving the docs site, use [examples/source](https://misery.co/shaderpad/examples/source/). The markdown documentation index below links to raw `.md` mirrors of the docs pages.

Hard rules:

- ShaderPad targets WebGL2.
- Standard fragment shaders should include `#version 300 es`, `precision highp float;`, `in vec2 v_uv;`, and `out vec4 outColor;`.
- Use the smallest working pattern first: one fragment shader, one `ShaderPad`, one visible canvas.
- For browser demos, default to `createFullscreenCanvas()` plus `autosize()`.
- Initialize uniforms before calling `updateUniforms()`.
- Initialize textures before calling `updateTextures()`.
- For live DOM-backed textures like video or webcam, call `updateTextures()` every frame.
- Use `play()` for normal animation, `step()` for manual advancement, and `draw()` only for render-only passes. `draw()` does not advance time, frame count, or history.
- If using `helpers()`, do not manually declare `u_resolution`; the plugin injects it.
- For region-only MediaPipe effects, prefer helper calls like `inFace()`, `faceAt()`, `poseAt()`, `segmentAt()`, and `handLandmark()` instead of decoding raw plugin textures unless you truly need custom decoding.
- MediaPipe plugins (`face`, `pose`, `hands`, `segmenter`) require `@mediapipe/tasks-vision`.
- For MediaPipe plugins, the configured `textureName` must match the actual initialized live texture name.
- Prefer one WebGL context whenever possible. Multi-pass pipelines should usually share one canvas/context, and the last draw in `requestAnimationFrame` is what appears on screen.
- Downsample expensive intermediate passes before adding more passes or more detector work.
- Use the smallest format and filtering that works: `R8` plus `NEAREST` for masks or grayscale, `RGBA16F` plus `HALF_FLOAT` for float accumulation, and integer textures plus `NEAREST` for data maps.
- If plugin history is enabled, helper overloads accept `framesAgo`; consider `skipHistoryWrite` before increasing history depth.
- Detector batching across passes works when plugin type, `textureName`, detector options, and the underlying source object all match.

Start with these pages:

- `/shaderpad/docs/getting-started/ai-agent-guide/` - best single-page overview for AI agents; includes decision tables, performance rules, and concrete recipes
- `/shaderpad/docs/getting-started/quickstart/` - smallest working example
- `/shaderpad/docs/api/shaderpad/` - constructor and options
- `/shaderpad/docs/api/methods/` - methods and behavior
- `/shaderpad/docs/core-concepts/built-in-inputs/` - built-in varying and uniforms
- `/shaderpad/docs/core-concepts/history/` - history buffers, plugin history, and `historyZ()`
- `/shaderpad/docs/guides/chaining-shaders/` - multi-pass workflows
- `/shaderpad/docs/guides/performance/` - bandwidth, context sharing, texture formats, and detector batching
- `/shaderpad/docs/plugins/helpers/` - GLSL helpers, `fitCover()`, and the `u_resolution` caveat

Plugin docs:

- `/shaderpad/docs/plugins/autosize/`
- `/shaderpad/docs/plugins/save/`
- `/shaderpad/docs/plugins/face/`
- `/shaderpad/docs/plugins/pose/`
- `/shaderpad/docs/plugins/hands/`
- `/shaderpad/docs/plugins/segmenter/`

Concrete local example starting points:

- [Basic](https://misery.co/shaderpad/examples/source/basic.ts) - Interactive dot grid with cursor tracking and animated custom uniforms.
- [Webcam](https://misery.co/shaderpad/examples/source/webcam.ts) - Webcam compositing with a picture-frame overlay.
- [Cursor feedback](https://misery.co/shaderpad/examples/source/cursor-feedback.ts) - A shader that feeds back on itself through a 5x5 tiled history buffer.
- [Webcam trails](https://misery.co/shaderpad/examples/source/webcam-trails.ts) - Webcam echo trails built from texture history.
- [MediaPipe chaining](https://misery.co/shaderpad/examples/source/mediapipe-chaining.ts) - Two-pass webcam compositing with shared face detection.
- [Camo](https://misery.co/shaderpad/examples/source/camo.ts) - Face- or body-centered camouflage with a live mode toggle.
- [Finger pens](https://misery.co/shaderpad/examples/source/finger-pens.ts) - Interactive ink strokes demo controlled by your fingertips.
- [Single-channel textures](https://misery.co/shaderpad/examples/source/single-channel-textures.ts) - An R8 webcam pass chained into history to show single-channel textures in action.

Markdown documentation index:

### Getting Started
- [Overview](https://misery.co/shaderpad/index.md) - ShaderPad is a lightweight WebGL2 library for fragment shaders, textures, history buffers, and creative camera effects.
- [AI agent guide](https://misery.co/shaderpad/docs/getting-started/ai-agent-guide.md) - A single-page guide for AI agents and coding assistants writing correct ShaderPad programs.
- [Installation](https://misery.co/shaderpad/docs/getting-started/installation.md) - Install ShaderPad and understand when you also need MediaPipe.
- [Learning shaders](https://misery.co/shaderpad/docs/getting-started/learning-shaders.md) - A few practical ways to build intuition for shaders and find good teachers.
- [Quickstart](https://misery.co/shaderpad/docs/getting-started/quickstart.md) - Render your first animated shader with ShaderPad.

### Core Concepts
- [Built-in inputs](https://misery.co/shaderpad/docs/core-concepts/built-in-inputs.md) - Learn the built-in varying and uniforms that ShaderPad updates for you.
- [Canvas and input](https://misery.co/shaderpad/docs/core-concepts/canvas-and-input.md) - Choose canvas ownership, cursor targeting, and responsive sizing behavior.
- [Format and precision](https://misery.co/shaderpad/docs/core-concepts/format-and-precision.md) - Choose ShaderPad texture formats, data types, filters, and history precision deliberately.
- [History](https://misery.co/shaderpad/docs/core-concepts/history.md) - Use output history and texture history for feedback, delay, and temporal effects.
- [Shader lifecycle](https://misery.co/shaderpad/docs/core-concepts/shader-lifecycle.md) - Understand construction, rendering, stepping, pausing, and cleanup.
- [Textures](https://misery.co/shaderpad/docs/core-concepts/textures.md) - Work with images, videos, canvases, typed arrays, and ShaderPad outputs.
- [Uniforms](https://misery.co/shaderpad/docs/core-concepts/uniforms.md) - Initialize and update custom uniforms, including uniform arrays.

### Guides
- [Chaining shaders](https://misery.co/shaderpad/docs/guides/chaining-shaders.md) - Build offscreen, multi-pass, and ShaderPad-as-texture workflows.
- [Performance](https://misery.co/shaderpad/docs/guides/performance.md) - ShaderPad-specific ways to reduce bandwidth, copies, and unnecessary work.
- [Saving images](https://misery.co/shaderpad/docs/guides/saving-images.md) - Export ShaderPad output to PNG with the save plugin.
- [Webcam input](https://misery.co/shaderpad/docs/guides/webcam-input.md) - Use webcam video as a live texture in ShaderPad.

### Plugins
- [autosize](https://misery.co/shaderpad/docs/plugins/autosize.md) - Resize the canvas automatically and keep render resolution in sync.
- [face](https://misery.co/shaderpad/docs/plugins/face.md) - Face landmarks, masks, and helper functions for ShaderPad.
- [hands](https://misery.co/shaderpad/docs/plugins/hands.md) - Hand landmarks and handedness helpers for ShaderPad.
- [helpers](https://misery.co/shaderpad/docs/plugins/helpers.md) - GLSL helpers for aspect fitting and history sampling.
- [pose](https://misery.co/shaderpad/docs/plugins/pose.md) - Pose landmarks and segmentation helpers for ShaderPad.
- [save](https://misery.co/shaderpad/docs/plugins/save.md) - Add PNG export support to a ShaderPad instance.
- [segmenter](https://misery.co/shaderpad/docs/plugins/segmenter.md) - Segmentation masks and category/confidence sampling for ShaderPad.

### API Reference
- [Events](https://misery.co/shaderpad/docs/api/events.md) - Lifecycle and plugin events emitted by ShaderPad.
- [Methods](https://misery.co/shaderpad/docs/api/methods.md) - Public methods on ShaderPad instances.
- [Properties](https://misery.co/shaderpad/docs/api/properties.md) - Public instance and class properties exposed by ShaderPad.
- [ShaderPad](https://misery.co/shaderpad/docs/api/shaderpad.md) - Constructor overview and API entry point for ShaderPad.
- [Uniforms](https://misery.co/shaderpad/docs/api/uniforms.md) - Complete reference for ShaderPad's built-in uniforms.
- [Utilities](https://misery.co/shaderpad/docs/api/utilities.md) - Utility exports from ShaderPad.

### Reference
- [Repository README](https://misery.co/shaderpad/README.md) - Long-form repository overview, API walkthrough, and example-driven reference.

Additional repository reference:

- [Repository README](https://misery.co/shaderpad/README.md) - raw markdown mirror of the repo README
- [GitHub README](https://github.com/miseryco/shaderpad/blob/main/README.md) - canonical repository copy