Renderer

The core 2D rendering engine for Ceramic, responsible for efficiently drawing all visuals to the screen.

This implementation-independent renderer works with backend draw implementations to:

• Batch draw calls for optimal GPU performance
• Manage render state (textures, shaders, blend modes)
• Handle render-to-texture operations
• Implement stencil-based clipping
• Support multi-texture batching when available

The renderer uses several optimization strategies:

• State batching: Groups visuals with the same rendering state
• Texture atlasing: Batches multiple textures in a single draw call
• Vertex buffering: Minimizes GPU state changes
• Z-ordering: Maintains proper visual layering

Rendering pipeline:

1. Sort visuals by depth and rendering state
2. Group visuals into batches with matching states
3. Submit batches to GPU with minimal state changes
4. Handle special cases (stencil clipping, render targets)

// The renderer is typically managed by the App
var renderer = app.renderer;
renderer.render(true, app.visuals);

Instance Members #

Renders a list of visuals to the screen or render target.

This is the main entry point for the rendering pipeline. It:

1. Initializes rendering state
2. Processes each visual in order
3. Batches visuals with matching states
4. Handles special rendering modes (clipping, render targets)
5. Submits draw calls to the GPU

Private Members #

Number of draw calls made in the current frame. Lower values indicate better batching performance.

For the meshes sent with their own indices (see _drawMesh()): the list 0, 1, 2... used as the vertices of a mesh sent whole, and for a mesh sent in parts, the vertices and indices of the current part, the number each mesh vertex has in it (indexedSlot) and the part it was last numbered for (indexedStamp).

Currently active GPU shader program.

Number of custom float attributes per vertex for the active shader.

Whether we're currently rendering to the stencil buffer for clipping.

Last used texture to detect state changes.

Backend ID of the last used texture.

Last used shader to detect state changes.

Last used render target to detect state changes.

Last computed blending mode to detect state changes.

Last clipping visual to detect state changes.

Whether the last clip was a regular quad (can use scissor test).

Currently active texture slot for multi-texturing.

Backend texture management interface.

Backend shader management interface.

Logical width of the current texture.

Logical height of the current texture.

Actual GPU width of the current texture (may be power of 2).

Actual GPU height of the current texture (may be power of 2).

Default shader for textured rendering.

Default white texture used when no texture is specified.

Current quad being processed (for type casting optimization).

Current mesh being processed (for type casting optimization).

Whether the rendering state needs to be updated.

Current Z depth value for layering visuals. Incremented slightly for each visual to maintain order.

Indexes of textures used in the current batch.

Number of textures currently bound for multi-texturing.

Maximum number of textures that can be used in a single batch. Determined by GPU capabilities and shader limitations.

Whether the active shader supports multi-texture batching.

Currently active render target.

Z per render target

Draws a single quad to the current render target.

Optimized for the most common rendering case. Handles:

• Texture binding and UV mapping
• Color and alpha blending
• Matrix transformations
• Custom shader attributes
• Batching with previous quads when possible

Draws a Renderable visual: it emits its own draw commands via render().

Handles render target binding (same pattern as Quad/Mesh), re-applies the active scissor clip if any, then brackets the custom rendering with a flush + texture unbind so batched 2D state stays consistent afterwards.

Draws a mesh with arbitrary vertices and triangles.

More flexible than drawQuad but with similar optimizations:

• Vertex buffer management
• Color mapping (per-mesh, per-triangle, or per-vertex)
• Custom vertex attributes
• Large mesh splitting across multiple draw calls

The list 0, 1, 2... up to count (at least).

Makes room in the tables of the parts for a mesh of count vertices.

A new part number: no vertex is numbered for it yet.

Increments the Z (depth) value with a non-linear progression to maintain proper rendering order while avoiding Z-fighting issues. The formula applies a quadratic scaling factor to ensure adequate separation between consecutive depth values, particularly important for overlapping transparent objects.

Flushes pending draw commands to the GPU.

Called when:

• Render state changes (texture, shader, blend mode)
• Buffer capacity is reached
• Rendering is complete

Computes the actual blending mode for a quad.

Resolves AUTO blending based on render target:

• Regular rendering: PREMULTIPLIED_ALPHA
• Render-to-texture: RENDER_TO_TEXTURE

Computes the actual blending mode for a mesh.

Similar to computeQuadBlending but for mesh visuals.

Activates a shader program for subsequent draw calls.

Updates:

• Active shader state
• Multi-texture capability flags
• Custom attribute configuration

Configures GPU blending mode for transparency and compositing.

Supports various blend modes:

• PREMULTIPLIED_ALPHA: Standard alpha blending
• ADD: Additive blending for light effects
• ALPHA: Non-premultiplied alpha
• RENDER_TO_TEXTURE: Special mode for render targets

Sets the render target for subsequent draw calls.

Checks if a texture can be added to the current batch.

For multi-texture batching, checks if:

• Texture is already bound in a slot
• Free texture slots are available

Metadata #