ShaderPad

API Reference

Methods

Core Render Methods

  • play(onBeforeStep?)
  • step(options?)
  • draw(options?)
  • pause()
  • resetFrame()
  • reset()
  • destroy()

Uniform Methods

  • initializeUniform(name, type, value, options?)
  • updateUniforms(updates, options?)

Texture Methods

  • initializeTexture(name, source, options?)
  • updateTextures(updates, options?)

Event Methods

  • on(name, callback)
  • off(name, callback)

Method Details

play(onBeforeStep?)

play(onBeforeStep?: (time: number, frame: number) => StepOptions | void): void

play() starts the animation loop and updates u_time, u_frame, and output history on each frame.

play() Parameters

ParameterTypeDefaultNotes
onBeforeStep(time: number, frame: number) => StepOptions | voidundefinedCalled on every animation frame before _step() runs. time is measured in seconds from the current start time, and frame is the current frame index before it is incremented. Returning a StepOptions object affects that frame only.
shader.play((time, frame) => {
  shader.updateUniforms({ u_speed: Math.sin(time) })

  if (frame < 5) {
    return { skipHistoryWrite: true }
  }
})

This overlaps with the beforeStep event, but they are not identical:

  • Use onBeforeStep when the logic belongs to this specific play() call.
  • Use beforeStep when you want a reusable listener that also fires for manual step() calls.
  • Only onBeforeStep can return StepOptions to affect the current frame.

step(options?)

step(options?: StepOptions): void

step() advances exactly one frame, updates u_time and u_frame, renders, and writes to history unless disabled.

draw(options?)

draw(options?: StepOptions): void

draw() renders immediately without advancing time, frame, or history. It accepts the same options shape, but only skipClear affects draw() directly.

Render Step Options Reference

step(options?), draw(options?), and the return value from play(onBeforeStep) all accept the same object shape:

OptionTypeDefaultApplies toNotes
skipClearbooleanfalsestep(), draw(), play() callback returnRebinds the intermediate render target without clearing it first. Useful for accumulation, trails, and some multi-pass patterns.
skipHistoryWritebooleanfalsestep(), draw(), play() callback returnPrevents output-history writes for that frame. draw() accepts the field for API consistency, but it has no effect there because draw() never advances history.

initializeUniform(name, type, value, options?)

initializeUniform(
  name: string,
  type: 'float' | 'int' | 'uint',
  value: number | number[] | (number | number[])[],
  options?: { arrayLength?: number },
): void

Registers a shader uniform once, then seeds it with an initial value.

initializeUniform() Options

OptionTypeDefaultNotes
arrayLengthnumberundefinedDeclares that the uniform is a fixed-length array. When set, initialization must include exactly that many elements, and ShaderPad will look up name[0] if needed.

updateUniforms(updates, options?)

updateUniforms(
  updates: Record<string, number | number[] | (number | number[])[]>,
  options?: { startIndex?: number },
): void

Updates one or more initialized uniforms.

updateUniforms() Options

OptionTypeDefaultNotes
startIndexnumberundefinedOnly relevant for uniform arrays. Starts the write at name[startIndex] instead of name[0]. Passing an invalid index throws.

initializeTexture(name, source, options?)

initializeTexture(
  name: string,
  source: TextureSource,
  options?: TextureOptions & { history?: number },
): void

initializeTexture() registers a named texture input. The same options also control per-texture history when history is set on that texture.

If source is another ShaderPad instance and you omit texture options, the destination texture inherits the source instance's internal render-texture settings.

Texture Options Reference

OptionTypeDefaultNotes
historynumber0Number of previous frames to retain for this texture. Publicly, history: N means current frame plus N previous frames; ShaderPad allocates N + 1 internal layers to make framesAgo access work naturally.
preserveYbooleanOmitted, which behaves like false for DOM-backed sourcesDOM-backed sources are vertically flipped by default to match WebGL coordinates. Set preserveY: true to keep their original orientation. Typed-array sources are never flipped.
internalFormatGLInternalFormatStringDerived from type, otherwise 'RGBA8'GPU storage format for this texture. Float color formats require EXT_color_buffer_float when used as renderable textures.
formatGLFormatStringDerived from internalFormatDefaults to 'RGBA' for normalized and float color formats, and 'RGBA_INTEGER' for integer color formats.
typeGLTypeStringDerived from internalFormat, otherwise 'UNSIGNED_BYTE'Source texel data type.
minFilterGLFilterString'LINEAR'Minification filter for the texture or texture history.
magFilterGLFilterString'LINEAR'Magnification filter for the texture or texture history.
wrapSGLWrapString'CLAMP_TO_EDGE'Horizontal wrap mode.
wrapTGLWrapString'CLAMP_TO_EDGE'Vertical wrap mode.

updateTextures(updates, options?)

updateTextures(
  updates: Record<string, UpdateTextureSource>,
  options?: { skipHistoryWrite?: boolean },
): void

Updates one or more previously initialized textures.

updateTextures() Options

OptionTypeDefaultNotes
skipHistoryWritebooleanfalseOnly relevant for textures that were initialized with per-texture history. When true, the texture data is updated without advancing that texture's history layers.
Previous
Uniforms
Next
Events