ImSystem

View source
ceramic.Entity → ceramic.System → elements.ImSystem (Class)

The core system that manages the immediate mode UI rendering pipeline.

ImSystem extends Ceramic's System class to integrate with the engine's update loop and provide:

  • Render target management through filters
  • Window focus tracking
  • Frame lifecycle management
  • Automatic layout updates

The system uses a Filter to render all Im UI to a separate texture, allowing for proper layering and post-processing effects. It automatically activates when windows are present and deactivates when no UI is shown.

See: Im, Window, System

Static Members

elements
shared: ImSystem

The shared singleton instance of ImSystem. Lazily initialized on first access.

Instance Members

elements
new(): Void

Creates a new ImSystem instance.

Sets up the system with:

  • Early update order of 100 (runs before most systems)
  • Late update order of 6000 (runs after most systems)

This ensures Im.beginFrame() runs early and Im.endFrame() runs late in the frame lifecycle.

Private Members

elements
filter: ceramic.Filter

Filter that renders all Im UI to a separate texture.

elements
view: ceramic.View

Root view container for all Im windows and UI elements.

elements
makeFilterActive: Int

State counter for filter activation/deactivation. Ranges from -2 (fully inactive) to 2 (fully active).

elements
createView(): Void

Creates the root view and filter for Im UI rendering.

This method:

  • Creates a filter bound to native screen size for crisp rendering
  • Sets up a transparent root view at depth 1000 (above most content)
  • Configures automatic layout updates
  • Tracks focus changes for window management

@allow elements.Im

elements
requestRender(): Void

Requests a render update for the Im UI.

Marks the filter's render texture as dirty, ensuring the UI is re-rendered in the next frame.

@allow elements.Im

elements
handleFocusedVisualChange(focusedVisual: ceramic.Visual, prevFocusedVisual: ceramic.Visual): Void

Handles focus changes to track which Im window has focus.

This method:

  • Determines if the focused visual is within an Im window
  • Handles special cases like color picker popovers
  • Updates the context's focused window reference
Name Type Description
focusedVisual ceramic.Visual The visual that gained focus
prevFocusedVisual ceramic.Visual The visual that lost focus
elements
earlyUpdate(delta: Float): Void

Early update called at the beginning of each frame.

Updates view size to match filter dimensions and calls Im.beginFrame() to start the Im rendering cycle.

Name Type Description
delta Float Time elapsed since last frame in seconds
elements
lateUpdate(delta: Float): Void

Late update called at the end of each frame.

Finalizes the Im frame and manages filter activation:

  • Gradually activates filter when windows are present
  • Gradually deactivates filter when no windows are shown
  • Ensures smooth transitions to avoid visual glitches

The activation counter provides a 2-frame delay for stability.

Name Type Description
delta Float Time elapsed since last frame in seconds

Metadata

Name Parameters
:build tracker.macros.EventsMacro.build()
:autoBuild tracker.macros.EventsMacro.build()
:build ceramic.macros.EntityMacro.buildForCompletion()
:autoBuild ceramic.macros.EntityMacro.buildForCompletion()