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.

Ceramic supports two shader models:

  • Combined shader files (default): Single file with both vertex and fragment shaders
  • Separate vert/frag files: When ceramic_shader_vert_frag flag is enabled

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
fromSource(vertSource: String, fragSource: String, ?customAttributes: ceramic.ReadOnlyArray<ceramic.ShaderAttribute>): backend.Shader

Creates a shader from vertex and fragment shader source code. Available when ceramic_shader_vert_frag compilation flag is set.

Name Type Default Description
vertSource String GLSL source code for the vertex shader
fragSource String GLSL source code for the fragment shader
customAttributes ceramic.ReadOnlyArray<ceramic.ShaderAttribute> (optional) Optional array of custom vertex attributes
Returns Description
backend.Shader The compiled shader program, or null on compilation 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
setColor(shader: backend.Shader, name: String, r: Float, g: Float, b: Float, a: Float): Void

Sets a color uniform value in the shader (as vec4).

Name Type Description
shader backend.Shader The shader to modify
name String The uniform variable name
r Float Red component (0.0 to 1.0)
g Float Green component (0.0 to 1.0)
b Float Blue component (0.0 to 1.0)
a Float Alpha component (0.0 to 1.0)
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
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