Draw

View source
backend.Draw (Class)

Instance Members

The graphics batcher instance for batched rendering operations. Stored in a static field for performance, since there's only one Draw instance.

clay
draw(visuals: Array<ceramic.Visual>): Void

Renders an array of visual objects.

Name Type Description
visuals Array<ceramic.Visual> Array of Visual objects to render
clay
swap(): Void

Swaps the front and back buffers (unused in Clay backend). Buffer swapping is handled automatically by Clay framework.

clay
initBuffers(): Void

Initializes the vertex and index buffers for rendering.

This method sets up the buffer management system and prepares the first set of buffers for use. Should be called before any rendering operations begin.

clay
beginRender(): Void

Begins a rendering pass by enabling vertex attributes.

Enables the core vertex attributes used by all shaders:

  • Position (x, y, z)
  • Texture coordinates (u, v)
  • Color (r, g, b, a)

Additional attributes are enabled dynamically based on the active shader.

clay
endRender(): Void

Ends the current rendering frame.

Performs any cleanup or finalization needed after all draw operations.

clay
clear(): Void

Clears the current render target to transparent white.

This method clears the color buffer with a transparent white background. When rendering to a texture, this marks the render target as updated.

clay
clearAndApplyBackground(): Void

Clears the current render target and applies the application background color.

This method clears the color buffer with the application's configured background color (fully opaque). Used for the main screen clearing.

clay
enableBlending(): Void

Enables alpha blending for transparent rendering.

This activates the GPU's blending functionality, allowing pixels to be combined based on their alpha values. Must be enabled for transparency to work correctly.

clay
disableBlending(): Void

Disables alpha blending.

When disabled, pixels are rendered opaque regardless of alpha values. This can improve performance when rendering fully opaque content.

clay
setActiveTexture(slot: Int): Void

Sets the active texture unit slot for multi-texturing.

Modern GPUs support multiple texture units, allowing shaders to sample from multiple textures simultaneously. This method selects which texture unit subsequent texture operations will affect.

Name Type Description
slot Int The texture unit index (0-based)
clay
setPrimitiveType(primitiveType: ceramic.RenderPrimitiveType): Void

Sets the primitive type for rendering.

Determines how vertices are interpreted:

  • TRIANGLE: Every 3 vertices form a triangle (default)
  • LINE: Every 2 vertices form a line
Name Type Description
primitiveType ceramic.RenderPrimitiveType The primitive type to use for subsequent draw calls
clay
getActiveTexture(): Int

Gets the currently active texture unit slot.

Returns Description
Int The index of the active texture unit
clay
setRenderTarget(renderTarget: ceramic.RenderTexture, ?force: Bool = false): Void

Sets the active render target for subsequent drawing operations.

This method switches between rendering to a texture (off-screen) or to the main screen buffer. When switching targets, it handles:

  • MSAA buffer blitting for antialiased render targets
  • Projection and view matrix updates
  • Viewport configuration
  • Optional automatic clearing

When renderTarget is null, rendering switches back to the main screen.

Name Type Default Description
renderTarget ceramic.RenderTexture The render texture to render to, or null for main screen
force Bool false Force the render target switch even if it's the same target
clay
useShader(shader: Shader): Void

Activates a shader program for rendering.

This method:

  • Sets the shader as the active GPU program
  • Uploads projection and modelview matrices as uniforms
  • Configures vertex layout based on shader attributes
  • Determines if multi-texture batching is supported
  • Calculates maximum vertices per batch based on attribute size

The vertex size calculation includes:

  • 3 floats for position (x, y, z)
  • Custom float attributes defined by the shader
  • 1 float for texture slot (if multi-texturing is enabled)
Name Type Description
shader Shader The shader to activate
clay
setBlendFuncSeparate(srcRgb: BlendMode, dstRgb: BlendMode, srcAlpha: BlendMode, dstAlpha: BlendMode): Void

Sets separate blend functions for RGB and alpha channels.

This allows fine control over how colors are blended, with different blend modes for color (RGB) and transparency (alpha) channels.

Name Type Description
srcRgb BlendMode Blend factor for source RGB
dstRgb BlendMode Blend factor for destination RGB
srcAlpha BlendMode Blend factor for source alpha
dstAlpha BlendMode Blend factor for destination alpha
clay
beginDrawQuad(quad: ceramic.Quad): Void

Called before drawing a quad (currently unused).

Reserved for future optimizations or quad-specific setup.

Name Type Description
quad ceramic.Quad The quad about to be drawn
clay
endDrawQuad(): Void

Called after drawing a quad (currently unused).

Reserved for future optimizations or quad-specific cleanup.

clay
beginDrawMesh(mesh: ceramic.Mesh): Void

Called before drawing a mesh (currently unused).

Name Type
mesh ceramic.Mesh
clay
endDrawMesh(): Void

Called after drawing a mesh (currently unused).

clay
enableScissor(x: Float, y: Float, width: Float, height: Float): Void

Enables scissor testing to clip rendering to a rectangular area.

Scissor testing restricts rendering to pixels within the specified rectangle. Any pixels outside this area are discarded by the GPU.

The coordinates are transformed by the current modelview matrix and adjusted for screen density.

Name Type Description
x Float Left edge of the scissor rectangle in logical coordinates
y Float Top edge of the scissor rectangle in logical coordinates
width Float Width of the scissor rectangle in logical pixels
height Float Height of the scissor rectangle in logical pixels
clay
disableScissor(): Void

Disables scissor testing.

After calling this, rendering is no longer clipped to a rectangular area.

clay
drawWithStencilTest(): Void

Enables stencil testing for masked rendering.

This configures the stencil test to only render pixels where the stencil buffer equals 1. Used after drawing to the stencil buffer to render content only within the stenciled area.

clay
drawWithoutStencilTest(): Void

Disables stencil testing for normal rendering.

Resets stencil configuration to default values where all pixels pass the stencil test and the stencil buffer can be written to.

clay
beginDrawingInStencilBuffer(): Void

Begins drawing to the stencil buffer for masking operations.

This sets up the GPU to write to the stencil buffer instead of the color buffer. Pixels drawn will mark areas in the stencil buffer with a value of 1, creating a mask for subsequent rendering.

clay
endDrawingInStencilBuffer(): Void

Ends drawing to the stencil buffer.

Returns to normal color buffer rendering.

clay
bindTexture(backendItem: Texture): Void

Binds a texture to the current texture unit.

Makes the texture available for sampling in shaders. The texture will be bound to the currently active texture unit.

Name Type Description
backendItem Texture The texture to bind
clay
bindNoTexture(): Void

Binds no texture (or a default white texture depending on the graphics backend).

Used when rendering untextured geometry or solid colors.

clay
textureBackendItemMatchesId(backendItem: Texture, textureId: TextureId): Bool

Checks if a backend texture matches a texture ID.

Name Type Description
backendItem Texture The backend texture to check
textureId TextureId The texture ID to compare against
Returns Description
Bool True if the texture matches the ID
clay
getTextureId(backendItem: Texture): TextureId

Gets the texture ID from a backend texture.

Name Type Description
backendItem Texture The backend texture
Returns Description
TextureId The texture ID
clay
getTextureWidth(backendItem: Texture): Int

Gets the width of a backend texture.

Name Type Description
backendItem Texture The backend texture
Returns Description
Int The texture width in pixels
clay
getTextureHeight(backendItem: Texture): Int

Gets the height of a backend texture.

Name Type Description
backendItem Texture The backend texture
Returns Description
Int The texture height in pixels
clay
getTextureWidthActual(backendItem: Texture): Int

Gets the actual width of a backend texture (may differ from logical width).

Name Type Description
backendItem Texture The backend texture
Returns Description
Int The actual texture width in pixels
clay
getTextureHeightActual(backendItem: Texture): Int

Gets the actual height of a backend texture (may differ from logical height).

Name Type Description
backendItem Texture The backend texture
Returns Description
Int The actual texture height in pixels
clay
getNumPos(): Int

Gets the number of vertices currently in the buffer.

Returns Description
Int Current vertex count

Adds a vertex position to the current batch.

Name Type Description
x ceramic.Float32 X coordinate in screen space
y ceramic.Float32 Y coordinate in screen space
z ceramic.Float32 Z coordinate for depth ordering
clay
putPosAndTextureSlot(x: ceramic.Float32, y: ceramic.Float32, z: ceramic.Float32, textureSlot: ceramic.Float32): Void

Adds a vertex position with texture slot for multi-texture batching.

Name Type Description
x ceramic.Float32 X coordinate in screen space
y ceramic.Float32 Y coordinate in screen space
z ceramic.Float32 Z coordinate for depth ordering
textureSlot ceramic.Float32 Texture slot index
clay
beginFloatAttributes(): Void

Begins adding float attributes for a vertex.

clay
putFloatAttribute(index: Int, value: Float): Void

Adds a custom float attribute value for the current vertex.

Name Type Description
index Int Attribute index
value Float Attribute value
clay
endFloatAttributes(): Void

Ends adding float attributes for the current vertex.

clay
putIndice(i: Int): Void

Adds an index to the index buffer.

Name Type Description
i Int Vertex index
clay
putUVs(uvX: Float, uvY: Float): Void

Adds texture coordinates for the current vertex.

Name Type Description
uvX Float Horizontal texture coordinate (0.0 to 1.0)
uvY Float Vertical texture coordinate (0.0 to 1.0)
clay
putColor(r: Float, g: Float, b: Float, a: Float): Void

Adds a vertex color to the current batch.

Name Type Description
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)
clay
putTransformedQuad(w: Float, h: Float, matA: Float, matB: Float, matC: Float, matD: Float, matTX: Float, matTY: Float, z: Float, textureSlot: Float, r: Float, g: Float, b: Float, a: Float, u0: Float, v0: Float, u1: Float, v1: Float, u2: Float, v2: Float, u3: Float, v3: Float, flipOrder: Bool, wireframe: Bool, attrs: Array<Float>, attrsLen: Int, attrCount: Int): Void

Batched emission of a complete quad: 6 indices, 4 transformed positions, 4 identical colors and 4 uv pairs, written directly into the batcher buffers (through vectorized kernels on native targets, tight typed-array loops on js) instead of per-scalar put* calls.

The caller must have checked buffer capacity first (shouldFlush) and resolved the final color and uv values, like it does on the scalar path.

Name Type Description
w Float Quad width
h Float Quad height
matA Float Matrix a component
matB Float Matrix b component
matC Float Matrix c component
matD Float Matrix d component
matTX Float Matrix tx component
matTY Float Matrix ty component
z Float Z coordinate for depth ordering
textureSlot Float Texture slot index, or -1 when not batching multiple textures
r Float Red component (final, premultiplied if needed)
g Float Green component (final, premultiplied if needed)
b Float Blue component (final, premultiplied if needed)
a Float Alpha component (final)
u0 Float First vertex u, in emission order
v0 Float First vertex v, in emission order
u1 Float Second vertex u
v1 Float Second vertex v
u2 Float Third vertex u
v2 Float Third vertex v
u3 Float Fourth vertex u
v3 Float Fourth vertex v
flipOrder Bool True to emit corners in br, bl, tl, tr order, false for tl, tr, br, bl
wireframe Bool True to emit the 12 line indices of a wireframe quad instead of 6 triangle indices
attrs Array<Float> Custom float attribute values shared by the 4 corners (may be null)
attrsLen Int Number of usable values in attrs
attrCount Int Number of custom float attributes expected by the shader (zero-padded if more than attrsLen)
clay
putTransformedMeshPart(vertices32: ceramic.Float32Array, vertices: Array<Float>, indices: Array<Int>, start: Int, end: Int, hasUvs: Bool, uvs: Array<Float>, uvFactorX: Float, uvFactorY: Float, singleColor: Bool, indicesColor: Bool, floatColors: ceramic.Float32Array, colors: Array<ceramic.AlphaColor>, r: Float, g: Float, b: Float, a: Float, globalAlpha: Float, premultiply: Bool, zeroAlpha: Bool, meshAttrCount: Int, shaderAttrCount: Int, matA: Float, matB: Float, matC: Float, matD: Float, matTX: Float, matTY: Float, z: Float, textureSlot: Float): Void

Batched emission of a run of indexed mesh vertices: sequential indices, transformed positions gathered through the index array, colors (single, sequential per-index or gathered per-vertex) and scaled uvs, written directly into the batcher buffers through vectorized kernels instead of per-scalar put* calls.

The caller must have checked buffer capacity for the whole run first, and must not use this method when the mesh has custom float attributes (that path stays scalar).

Name Type Description
vertices32 ceramic.Float32Array 32-bit float vertex source, or null to use vertices
vertices Array<Float> 64-bit float vertex source (used when vertices32 is null)
indices Array<Int> Mesh index array
start Int First index of the run (inclusive)
end Int Last index of the run (exclusive)
hasUvs Bool True to gather and scale uvs, false to write zeroed uvs
uvs Array<Float> Uv source array (ignored when hasUvs is false)
uvFactorX Float Horizontal uv scale factor
uvFactorY Float Vertical uv scale factor
singleColor Bool True when the whole run uses one color (r, g, b, a below)
indicesColor Bool True when colors are mapped per index (sequential), false for per vertex (gathered)
floatColors ceramic.Float32Array Per-color float source, or null to use colors
colors Array<ceramic.AlphaColor> Per-color packed source (used when floatColors is null and singleColor is false)
r Float Resolved single color red (when singleColor is true)
g Float Resolved single color green
b Float Resolved single color blue
a Float Resolved single color alpha
globalAlpha Float Mesh computed alpha, multiplied with each source alpha
premultiply Bool True to multiply rgb by the computed alpha
zeroAlpha Bool True to force the stored alpha to 0 (additive blending over standard batch)
meshAttrCount Int Number of custom float attributes interleaved in the vertex source
shaderAttrCount Int Number of custom float attributes expected by the shader (zero-padded)
matA Float Matrix a component
matB Float Matrix b component
matC Float Matrix c component
matD Float Matrix d component
matTX Float Matrix tx component
matTY Float Matrix ty component
z Float Z coordinate for depth ordering
textureSlot Float Texture slot index, or -1 when not batching multiple textures
clay
hasAnythingToFlush(): Bool

Checks if there is any geometry in the buffer to flush.

Returns Description
Bool True if there are vertices waiting to be submitted
clay
shouldFlush(numVerticesAfter: Int, numIndicesAfter: Int, customFloatAttributesSize: Int): Bool

Checks if the current batch should be flushed before adding more vertices.

Returns true if adding the specified number of vertices or indices would exceed buffer capacity, indicating that the current batch should be sent to the GPU before continuing.

Name Type Description
numVerticesAfter Int Number of vertices to be added
numIndicesAfter Int Number of indices to be added
customFloatAttributesSize Int Size of custom attributes
Returns Description
Bool True if flush is needed, false otherwise
clay
remainingVertices(): Int

Gets the remaining vertex capacity in the buffer.

Returns Description
Int Number of vertices that can still be added
clay
remainingIndices(): Int

Gets the remaining index capacity in the buffer.

Returns Description
Int Number of indices that can still be added
clay
flush(): Void

Flushes the current batch of vertices to the GPU.

This is the core rendering method that submits all accumulated geometry to the GPU for rendering.

clay
new(): Void

Creates a new Draw backend instance. Initializes the Ceramic renderer for handling visual rendering.

Private Members

clay
renderer: ceramic.Renderer

The Ceramic renderer instance used for high-level rendering operations.

clay
begin(): Void

Begins a rendering frame (currently unused). Reserved for future use or platform-specific initialization.

clay
end(): Void

Ends a rendering frame (currently unused). Reserved for future use or platform-specific cleanup.

clay
updateProjectionMatrix(width: Float, height: Float): Void

Updates the projection matrix for orthographic rendering.

Creates an orthographic projection matrix that maps logical coordinates to normalized device coordinates (-1 to 1).

The projection uses:

  • Origin at top-left (0,0)
  • X increases rightward
  • Y increases downward
  • Z range from -1000 to 1000 for layering
Name Type Description
width Float Viewport width in logical pixels
height Float Viewport height in logical pixels
clay
updateViewMatrix(density: Float, width: Float, height: Float, ?transform: ceramic.Transform, ?flipY: Float = 1): Void

Updates the view matrix for camera transformations.

The view matrix handles:

  • Camera position and rotation (via transform parameter)
  • Screen density scaling for high-DPI displays
  • Y-axis flipping for render-to-texture (textures have inverted Y)

The matrix is inverted at the end (if needed) because the view matrix represents the inverse of the camera transform.

Name Type Default Description
density Float Screen density multiplier (e.g., 2 for retina)
width Float Viewport width in logical pixels
height Float Viewport height in logical pixels
transform ceramic.Transform (optional) Optional camera transform
flipY Float 1 -1 to flip Y axis (for render targets), 1 for normal
clay
matrixIdentity(m: ceramic.Float32Array): Void

Sets a matrix to identity.

Name Type Description
m ceramic.Float32Array The matrix to set
clay
setMatrixToTransform(m: ceramic.Float32Array, transform: ceramic.Transform): Void

Sets a matrix from a 2D transform.

Name Type Description
m ceramic.Float32Array The matrix to set
transform ceramic.Transform The 2D transform to convert

Metadata

Name Parameters
:allow backend.Backend
:access backend.Backend