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:
- Sort visuals by depth and rendering state
- Group visuals into batches with matching states
- Submit batches to GPU with minimal state changes
- 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:
- Initializes rendering state
- Processes each visual in order
- Batches visuals with matching states
- Handles special rendering modes (clipping, render targets)
- Submits draw calls to the GPU
Name | Type | Description |
---|---|---|
isMainRender |
Bool | Whether this is the main render pass (vs render-to-texture) |
ceramicVisuals |
Array<Visual> | Array of visuals to render, pre-sorted by depth |
new(): Void
Private Members
drawCalls: Int
Number of draw calls made in the current frame. Lower values indicate better batching performance.
activeShader: backend.Shader
Currently active GPU shader program.
customFloatAttributesSize: Int
Number of custom float attributes per vertex for the active shader.
stencilClip: Bool
Whether we're currently rendering to the stencil buffer for clipping.
lastTexture: Texture
Last used texture to detect state changes.
lastTextureId: backend.TextureId
Backend ID of the last used texture.
lastShader: Shader
Last used shader to detect state changes.
lastRenderTarget: RenderTexture
Last used render target to detect state changes.
lastComputedBlending: Blending
Last computed blending mode to detect state changes.
lastClip: Visual
Last clipping visual to detect state changes.
lastClipIsRegular: Bool
Whether the last clip was a regular quad (can use scissor test).
activeTextureSlot: Int
Currently active texture slot for multi-texturing.
backendTextures: backend.Textures
Backend texture management interface.
backendShaders: backend.Shaders
Backend shader management interface.
texWidth: Int
Logical width of the current texture.
texHeight: Int
Logical height of the current texture.
texWidthActual: Int
Actual GPU width of the current texture (may be power of 2).
texHeightActual: Int
Actual GPU height of the current texture (may be power of 2).
defaultTexturedShader: backend.Shader
Default shader for textured rendering.
defaultWhiteTexture: Texture
Default white texture used when no texture is specified.
quad: Quad
Current quad being processed (for type casting optimization).
mesh: Mesh
Current mesh being processed (for type casting optimization).
stateDirty: Bool
Whether the rendering state needs to be updated.
z: Float
Current Z depth value for layering visuals. Incremented slightly for each visual to maintain order.
Indexes of textures used in the current batch.
usedTextures: Int
Number of textures currently bound for multi-texturing.
maxUsableTexturesInBatch: Int
Maximum number of textures that can be used in a single batch. Determined by GPU capabilities and shader limitations.
activeShaderCanBatchMultipleTextures: Bool
Whether the active shader supports multi-texture batching.
usedRenderTarget: RenderTexture
Currently active render target.
drawQuad(draw: backend.Draw, quad: Quad): Void
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
Name | Type | Description |
---|---|---|
draw |
backend.Draw | Backend draw interface |
quad |
Quad | The quad visual to render |
drawMesh(draw: backend.Draw, mesh: Mesh): Void
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
Name | Type | Description |
---|---|---|
draw |
backend.Draw | Backend draw interface |
mesh |
Mesh | The mesh visual to render |
flush(draw: backend.Draw): Bool
Flushes pending draw commands to the GPU.
Called when:
- Render state changes (texture, shader, blend mode)
- Buffer capacity is reached
- Rendering is complete
Name | Type | Description |
---|---|---|
draw |
backend.Draw | Backend draw interface |
Returns | Description |
---|---|
Bool | True if anything was flushed |
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
Name | Type | Description |
---|---|---|
quad |
Quad | The quad to compute blending for |
Returns | Description |
---|---|
Blending | The resolved blending mode |
Computes the actual blending mode for a mesh.
Similar to computeQuadBlending but for mesh visuals.
Name | Type | Description |
---|---|---|
mesh |
Mesh | The mesh to compute blending for |
Returns | Description |
---|---|
Blending | The resolved blending mode |
Name | Type |
---|---|
shaderA |
Shader |
shaderB |
Shader |
Returns |
---|
Bool |
useShader(draw: backend.Draw, shader: backend.Shader): Void
Activates a shader program for subsequent draw calls.
Updates:
- Active shader state
- Multi-texture capability flags
- Custom attribute configuration
Name | Type | Description |
---|---|---|
draw |
backend.Draw | Backend draw interface |
shader |
backend.Shader | Backend shader to activate (null for default) |
useBlending(draw: backend.Draw, blending: Blending): Void
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
Name | Type | Description |
---|---|---|
draw |
backend.Draw | Backend draw interface |
blending |
Blending | The blending mode to apply |
scissorWithQuad(draw: backend.Draw, quad: Quad): Void
Name | Type |
---|---|
draw |
backend.Draw |
quad |
Quad |
Name | Type |
---|---|
texture |
Texture |
Returns |
---|
Bool |
useRenderTarget(draw: backend.Draw, renderTarget: RenderTexture): Void
Sets the render target for subsequent draw calls.
Name | Type | Description |
---|---|---|
draw |
backend.Draw | Backend draw interface |
renderTarget |
RenderTexture | Texture to render to (null for screen) |
useFirstTextureInBatch(draw: backend.Draw, texture: Texture): Void
Name | Type |
---|---|
draw |
backend.Draw |
texture |
Texture |
useTexture(draw: backend.Draw, texture: Texture, reusing: Bool): Void
Name | Type |
---|---|
draw |
backend.Draw |
texture |
Texture |
reusing |
Bool |
canUseTextureInSameBatch(draw: backend.Draw, texture: Texture): Bool
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
Name | Type | Description |
---|---|---|
draw |
backend.Draw | Backend draw interface |
texture |
Texture | Texture to check |
Returns | Description |
---|---|
Bool | True if batching can continue |
useTextureInSameBatch(draw: backend.Draw, texture: Texture): Void
Name | Type |
---|---|
draw |
backend.Draw |
texture |
Texture |
unbindUsedTextures(draw: backend.Draw): Void
Name | Type |
---|---|
draw |
backend.Draw |
Metadata
Name | Parameters |
---|---|
:build |
ceramic.macros.EntityMacro.buildForCompletion() |
:autoBuild |
ceramic.macros.EntityMacro.buildForCompletion() |
:build |
tracker.macros.EventsMacro.build() |
:autoBuild |
tracker.macros.EventsMacro.build() |