Shaders

View source
backend.Shaders (Class)
Implements: spec.Shaders

Clay backend implementation of shader program management. Handles GLSL shader compilation, multi-texture batching, and cross-platform compatibility.

This class processes shader source code to:

  • Enable multi-texture batching for improved performance
  • Convert shaders between GLSL ES versions for platform compatibility
  • Manage shader uniforms and attributes
  • Handle platform-specific shader requirements
See: ceramic.Shader, ShaderImpl

Instance Members

clay
fromSource(vertSource: String, fragSource: String, ?customAttributes: ceramic.ReadOnlyArray<ceramic.ShaderAttribute>): Shader

Creates a shader program from vertex and fragment source code. Automatically detects and processes multi-texture shaders for batching optimization.

Multi-texture shaders are identified by the //ceramic:multitexture comment directive. The method will:

  • Generate texture uniforms based on GPU capabilities
  • Convert between GLSL ES versions as needed
  • Handle platform-specific shader requirements
Name Type Default Description
vertSource String Vertex shader GLSL source code
fragSource String Fragment shader GLSL source code
customAttributes ceramic.ReadOnlyArray<ceramic.ShaderAttribute> (optional) Optional custom vertex attributes beyond the standard ones
Returns Description
Shader Compiled shader program ready for use
clay
destroy(shader: Shader): Void

Destroys a shader program and releases GPU resources.

Name Type Description
shader Shader The shader to destroy
clay
clone(shader: Shader): Shader

Creates a deep copy of a shader program.

Name Type Description
shader Shader The shader to clone
Returns Description
Shader A new shader instance with the same properties
clay
setInt(shader: Shader, name: String, value: Int): Void

Sets an integer uniform value in the shader.

Name Type Description
shader Shader Target shader program
name String Uniform variable name
value Int Integer value to set
clay
setFloat(shader: Shader, name: String, value: Float): Void

Sets a float uniform value in the shader.

Name Type Description
shader Shader Target shader program
name String Uniform variable name
value Float Float value to set
clay
setColor(shader: Shader, name: String, r: Float, g: Float, b: Float, a: Float): Void

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

Name Type Description
shader Shader Target shader program
name String Uniform variable name
r Float Red component (0-1)
g Float Green component (0-1)
b Float Blue component (0-1)
a Float Alpha component (0-1)
clay
setVec2(shader: Shader, name: String, x: Float, y: Float): Void

Sets a 2D vector uniform value in the shader.

Name Type Description
shader Shader Target shader program
name String Uniform variable name
x Float X component
y Float Y component
clay
setVec3(shader: Shader, name: String, x: Float, y: Float, z: Float): Void

Sets a 3D vector uniform value in the shader.

Name Type Description
shader Shader Target shader program
name String Uniform variable name
x Float X component
y Float Y component
z Float Z component
clay
setVec4(shader: 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 Shader Target shader program
name String Uniform variable name
x Float X component
y Float Y component
z Float Z component
w Float W component
clay
setFloatArray(shader: Shader, name: String, array: Array<Float>): Void

Sets a float array uniform value in the shader.

Name Type Description
shader Shader Target shader program
name String Uniform variable name
array Array<Float> Array of float values
clay
setTexture(shader: Shader, name: String, slot: Int, texture: Texture): Void

Sets a texture uniform value in the shader.

Name Type Description
shader Shader Target shader program
name String Uniform variable name
slot Int Texture unit slot (0-based)
texture Texture Texture to bind
clay
setMat4FromTransform(shader: Shader, name: String, transform: ceramic.Transform): Void

Sets a 4x4 matrix uniform from a 2D transform. Converts the 2D transform to a 4x4 matrix suitable for GPU usage.

Name Type Description
shader Shader Target shader program
name String Uniform variable name
transform ceramic.Transform 2D transformation to convert
clay
customFloatAttributesSize(shader: ShaderImpl): Int

Calculates the total size of custom float attributes for a shader. Used for vertex buffer layout calculations.

Name Type Description
shader ShaderImpl The shader to analyze
Returns Description
Int Total number of floats needed for custom attributes
clay
maxIfStatementsByFragmentShader(): Int

Returns the maximum number of if-statements supported by fragment shaders. Caches the result after first computation.

Returns Description
Int Maximum if-statements supported
clay
canBatchWithMultipleTextures(shader: Shader): Bool

Checks if a shader supports multi-texture batching. Multi-texture shaders can render multiple textures in a single draw call.

Name Type Description
shader Shader The shader to check
Returns Description
Bool True if the shader supports multi-texture batching
clay
supportsHotReloadPath(): Bool

Indicates whether hot-reloading of shader files is supported. Clay backend supports watching shader files for changes.

Returns Description
Bool Always returns true for Clay backend
clay
new(): Void

Private Members

clay
SHADER_ATTRIBUTES: ceramic.ReadOnlyArray<String>

Standard shader vertex attributes: position, texture coordinates, color

clay
SHADER_ATTRIBUTES_MULTITEXTURE: ceramic.ReadOnlyArray<String>

Extended attributes for multi-texture batching, includes texture ID per vertex

clay
removeExtensions(source: String): String

Removes OpenGL ES extension directives from shader source. Used when targeting platforms that don't support or need these extensions.

Name Type Description
source String Shader source code
Returns Description
String Source code with extension directives removed
clay
convertToGLES3(source: String, isFrag: Bool): String

Converts GLSL ES 1.0 shader source to GLSL ES 3.0 syntax. Handles keyword changes and output variable declarations.

Key conversions:

  • attribute → in (vertex shaders)
  • varying → out (vertex) or in (fragment)
  • texture2D → texture
  • gl_FragColor → custom fragColor output
Name Type Description
source String Original shader source code
isFrag Bool True for fragment shaders, false for vertex shaders
Returns Description
String Converted GLSL ES 3.0 compatible source
clay
processMultiTextureVertTemplate(vertSource: String, maxTextures: Int, maxIfs: Int): String

Processes vertex shader template for multi-texture support. Replaces ceramic-specific comment directives with actual GLSL code.

Directives:

  • //ceramic:multitexture/vertextextureid → texture ID attribute declaration
  • //ceramic:multitexture/textureid → texture ID varying declaration
  • //ceramic:multitexture/assigntextureid → texture ID assignment
Name Type Description
vertSource String Vertex shader template source
maxTextures Int Maximum textures supported by GPU
maxIfs Int Maximum if-statements supported by fragment shader
Returns Description
String Processed vertex shader source
clay
processMultiTextureFragTemplate(fragSource: String, maxTextures: Int, maxIfs: Int): String

Processes fragment shader template for multi-texture support. Generates texture sampling code with conditional logic based on texture ID.

Directives:

  • //ceramic:multitexture → marks shader for processing
  • //ceramic:multitexture/texture → generates texture uniform declarations
  • //ceramic:multitexture/textureid → texture ID varying declaration
  • //ceramic:multitexture/if → starts conditional texture sampling block
  • //ceramic:multitexture/endif → ends conditional block
Name Type Description
fragSource String Fragment shader template source
maxTextures Int Maximum textures supported by GPU
maxIfs Int Maximum if-statements supported by fragment shader
Returns Description
String Processed fragment shader with multi-texture support
clay
computeMaxIfStatementsByFragmentShaderIfNeeded(?maxIfs: Int = 32): Void

Determines the maximum number of if-statements supported by the GPU's fragment shader. Tests by compiling shaders with varying numbers of conditionals.

Name Type Default Description
maxIfs Int 32 Starting maximum to test (halves on failure)
clay
generateIfStatements(maxIfs: Int): String

Generates a series of if-else statements for shader compilation testing. Used to determine GPU conditional complexity limits.

Name Type Description
maxIfs Int Number of if-statements to generate
Returns Description
String GLSL code with chained if-else statements