Renderer

Entityceramic.Renderer (Class)

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);
See: Visual The base class for all renderable objects, backend.Draw The backend interface for GPU operations, Shader For custom GPU shader programs, RenderTexture For off-screen rendering

Instance Members

render(isMainRender: Bool, ceramicVisuals: Array<Visual>): Void

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
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.


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


usedTextureIndexes: Array<Int>

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

computeQuadBlending(quad: Quad): Blending

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

computeMeshBlending(mesh: Mesh): Blending

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

isSameShader(shaderA: Shader, shaderB: Shader): Bool
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

isNotRenderedRenderTexture(texture: Texture): Bool
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()