Shaders

View source
spec.Shaders (Interface) → backend.Shaders

Backend interface for GPU shader program management.

This interface handles loading, compiling, and managing shader programs that run on the GPU. Shaders control how vertices are transformed and how pixels are colored during rendering.

Shaders can have uniform parameters (shared across all vertices/pixels) and custom vertex attributes (per-vertex data). The interface provides methods to set various types of uniform values.

Instance Members

destroy(shader: backend.Shader): Void

Destroys a shader program and frees its GPU resources. After calling this, the shader should not be used.

Name Type Description
shader backend.Shader The shader to destroy
load(path: String, baseAttributes: ceramic.ReadOnlyArray<ceramic.ShaderAttribute>, customAttributes: ceramic.ReadOnlyArray<ceramic.ShaderAttribute>, textureIdAttribute: ceramic.ShaderAttribute, done: Function): Void

Loads a shader from a file (can be precompiled or be compiled on the fly). The file format depends on the backend.

Name Type Description
path String Path to the shader file (relative to assets)
baseAttributes ceramic.ReadOnlyArray<ceramic.ShaderAttribute> Base vertex attributes (position, texCoord, color)
customAttributes ceramic.ReadOnlyArray<ceramic.ShaderAttribute> Custom vertex attributes beyond base ones (can be null)
textureIdAttribute ceramic.ShaderAttribute Texture slot attribute for multi-texture batching (can be null)
done Function Callback invoked with the compiled shader or null on failure

Creates a copy of a shader with its own uniform values. The GPU program is shared, but uniform values can be set independently.

Name Type Description
shader backend.Shader The shader to clone
Returns Description
backend.Shader A new shader instance sharing the same GPU program
setInt(shader: backend.Shader, name: String, value: Int): Void

Sets an integer uniform value in the shader.

Name Type Description
shader backend.Shader The shader to modify
name String The uniform variable name
value Int The integer value to set
setFloat(shader: backend.Shader, name: String, value: Float): Void

Sets a float uniform value in the shader.

Name Type Description
shader backend.Shader The shader to modify
name String The uniform variable name
value Float The float value to set
setVec2(shader: backend.Shader, name: String, x: Float, y: Float): Void

Sets a 2D vector uniform value in the shader.

Name Type Description
shader backend.Shader The shader to modify
name String The uniform variable name
x Float X component
y Float Y component
setVec3(shader: backend.Shader, name: String, x: Float, y: Float, z: Float): Void

Sets a 3D vector uniform value in the shader.

Name Type Description
shader backend.Shader The shader to modify
name String The uniform variable name
x Float X component
y Float Y component
z Float Z component
setVec4(shader: backend.Shader, name: String, x: Float, y: Float, z: Float, w: Float): Void

Sets a 4D vector uniform value in the shader.

Name Type Description
shader backend.Shader The shader to modify
name String The uniform variable name
x Float X component
y Float Y component
z Float Z component
w Float W component
setFloatArray(shader: backend.Shader, name: String, array: Array<Float>): Void

Sets an array of float uniform values in the shader. Used for uniform float arrays in GLSL.

Name Type Description
shader backend.Shader The shader to modify
name String The uniform array variable name
array Array<Float> The array of float values
setTexture(shader: backend.Shader, name: String, slot: Int, texture: backend.Texture): Void

Binds a texture to a shader sampler uniform.

Name Type Description
shader backend.Shader The shader to modify
name String The sampler uniform variable name
slot Int The texture unit slot (0-15 typically)
texture backend.Texture The texture to bind
setMat2(shader: backend.Shader, name: String, m00: Float, m10: Float, m01: Float, m11: Float): Void

Sets a 2x2 matrix uniform value in the shader (column-major order).

Name Type Description
shader backend.Shader The shader to modify
name String The uniform variable name
m00 Float Column 0, row 0
m10 Float Column 0, row 1
m01 Float Column 1, row 0
m11 Float Column 1, row 1
setMat3(shader: backend.Shader, name: String, m00: Float, m10: Float, m20: Float, m01: Float, m11: Float, m21: Float, m02: Float, m12: Float, m22: Float): Void

Sets a 3x3 matrix uniform value in the shader (column-major order).

Name Type Description
shader backend.Shader The shader to modify
name String The uniform variable name
m00 Float Column 0, row 0
m10 Float Column 0, row 1
m20 Float Column 0, row 2
m01 Float Column 1, row 0
m11 Float Column 1, row 1
m21 Float Column 1, row 2
m02 Float Column 2, row 0
m12 Float Column 2, row 1
m22 Float Column 2, row 2
setMat4(shader: backend.Shader, name: String, m00: Float, m10: Float, m20: Float, m30: Float, m01: Float, m11: Float, m21: Float, m31: Float, m02: Float, m12: Float, m22: Float, m32: Float, m03: Float, m13: Float, m23: Float, m33: Float): Void

Sets a 4x4 matrix uniform value in the shader (column-major order).

Name Type Description
shader backend.Shader The shader to modify
name String The uniform variable name
m00 Float Column 0, row 0
m10 Float Column 0, row 1
m20 Float Column 0, row 2
m30 Float Column 0, row 3
m01 Float Column 1, row 0
m11 Float Column 1, row 1
m21 Float Column 1, row 2
m31 Float Column 1, row 3
m02 Float Column 2, row 0
m12 Float Column 2, row 1
m22 Float Column 2, row 2
m32 Float Column 2, row 3
m03 Float Column 3, row 0
m13 Float Column 3, row 1
m23 Float Column 3, row 2
m33 Float Column 3, row 3
customFloatAttributesSize(shader: backend.Shader): Int

Gets the total size of custom float attributes per vertex. This is the sum of all custom attribute sizes defined for the shader.

Name Type Description
shader backend.Shader The shader to query
Returns Description
Int The number of floats per vertex for custom attributes
maxIfStatementsByFragmentShader(): Int

Gets the maximum number of if statements supported in fragment shaders. This varies by GPU and affects shader complexity limits.

Returns Description
Int The maximum if statement count, or -1 if unlimited
canBatchWithMultipleTextures(shader: backend.Shader): Bool

Checks if the shader supports batching with multiple textures. When true, the shader can render geometry using different textures in a single draw call by using texture arrays or multi-texturing.

Name Type Description
shader backend.Shader The shader to check
Returns Description
Bool True if multi-texture batching is supported
supportsHotReloadPath(): Bool

Checks if the backend supports hot-reloading of shader files. When true, shaders can include a ?hot=timestamp query parameter to bypass caching and force reloading during development.

Returns Description
Bool True if hot-reload paths are supported, false otherwise