Skip to content

Uniform values and sources ​

What a uniform can hold, how it gets to the GPU, and when it is resolved.

Values ​

UniformValue — the concrete data uploaded to GLSL.

TypeGLSLExample
numberfloatuScale: 1.5
booleanbooluEnabled: true
[number, number]vec2uPointer: [0, 0]
[number, number, number]vec3uColor: [1, 0, 0]
[number × 4]vec4uRect: [0, 0, 1, 1]
[number × 9] / Float32Array(9)mat3uNormalMatrix: […]
[number × 16] / Float32Array(16)mat4uModelView: […]
TextureParamssampler2D{ data, width, height } or { src }
WebGLTexturesampler2Da texture you created yourself

Arrays and Float32Arrays are matched by length: 2, 3 and 4 for the vector rows, 9 and 16 for the matrices. Any other length is ignored — there is no uniform-block upload. Numbers upload as floats and booleans as integers, so a GLSL int uniform takes true / false.

Texture parameters are documented in Sample images, videos and data and the API. createFloatDataTexture returns DataTextureParams, which is one form of TextureParams.

Sources ​

UniformSource — what you may put in the uniforms object. Each entry is resolved to a UniformValue before the pass renders.

FormResolvedNotes
UniformValueimmediatelyre-rendered on assignment
PromiseLike<UniformValue>when it settlesnot uploaded until then
(context) => UniformValuebefore every rendersynchronous — may not return a promise
ts
uniforms: {
  uColor: [1, 0, 0],                              // value
  uPicture: loadTexture("photo.jpg"),             // promise
  uTime: ({ time }) => time / 1000,               // function
}

Assigning to uniforms.uX later replaces the source with a value. Updating in place (uniforms.uX[0] = 1) is not observed — assign a new value instead. Reading uniforms.uX returns what you last assigned: a concrete value for value entries, but the function or promise itself for the other two forms.

Context ​

The object passed to function sources (UniformContext):

FieldTypeMeaning
timenumberms since the clock started, excluding pauses
deltaTimenumberms since the previous frame
elapsedTimenumberms since the clock started, including pauses
canvasResolution[number, number]drawing-buffer size in device pixels
passResolution[number, number]size of the render target this pass draws into
dprnumberdevice pixel ratio used to size the drawing buffer

Effect passes receive EffectUniformContext — the fields above plus:

FieldTypeMeaning
inputPassRenderPassthe pass rendered before this effect started
previousPassRenderPassthe pass rendered immediately before this sub-pass
ts
uniforms: {
  uTexture: ({ inputPass }) => inputPass.target!.texture,
  uPrevious: ({ previousPass }) => previousPass.target!.texture,
  uTexelSize: ({ passResolution }) => [1 / passResolution[0], 1 / passResolution[1]],
}

Resolution order ​

For each render() of a pass, in this order:

  1. Function sources are called with the current context.
  2. Promise sources that have settled contribute their value.
  3. Concrete values are staged.
  4. Everything is uploaded and the draw runs.

A promise that has not settled yet contributes nothing: the uniform is not uploaded at all, so a sampler draws black until the promise resolves. Late resolution notifies onUpdated, which schedules another render in auto / continuous mode.

In rawRenderPass (the lowest level) only concrete UniformValues are accepted — the managed renderPass is what adds functions and promises.

Observing changes ​

HookFires when
pass.onUpdated(cb)a uniform source of that pass changes (name, value, oldValue)
glCanvas.onUpdated(cb)a uniform source of the main pass changes
glCanvas.onBeforeRender(cb)before the whole chain renders
glCanvas.onAfterRender(cb)after the whole chain has rendered
pass.onResize(cb) / onInit / onDisposelifecycle of that pass

See also ​

Released under the MIT License.