Screen

Entityceramic.Screen (Class)
Implements: tracker.Observable

Core screen management class that handles display properties, coordinate transformations, and input events.

Screen provides a unified interface for managing screen properties across different platforms, handling logical vs native coordinates, and dispatching input events. It serves as the bridge between the backend's native screen handling and Ceramic's logical coordinate system.

Key responsibilities:

  • Coordinate transformation: Converts between native and logical coordinates
  • Screen scaling: Manages different scaling modes (FIT, FILL, RESIZE, FIT_RESIZE)
  • Input handling: Processes and dispatches mouse, touch, and pointer events
  • Visual hit testing: Determines which visuals receive input events
  • Focus management: Tracks and manages focused visuals
  • Screenshot capture: Provides methods to capture screen content

The screen uses a matrix transformation system to handle scaling and positioning, ensuring consistent behavior across different screen sizes and densities.

Example usage:

// Access screen properties
trace('Screen size: ${screen.width} x ${screen.height}');
trace('Native size: ${screen.nativeWidth} x ${screen.nativeHeight}');

// Listen for screen events
screen.onResize(this, () -> {
    trace('Screen resized');
});

// Check input states
if (screen.mousePressed(MouseButton.LEFT)) {
    trace('Left mouse button pressed at ${screen.mouseX}, ${screen.mouseY}');
}
See: App#screen, ScreenScaling, Visual

Static Members

Instance Members

observedDirty: Bool

Default is false, automatically set to true when any of this instance's observable variables has changed.


density: Float

Screen density computed from app's logical width/height settings and native width/height.


width: Float

Logical width used in app to position elements. Updated when the screen is resized.


height: Float

Logical height used in app to position elements. Updated when the screen is resized.


actualWidth: Float

The actual width available on screen, including offsets, in the same unit as width. Updated when the screen is resized.


actualHeight: Float

The actual height available on screen, including offsets, in the same unit as width. Updated when the screen is resized.


offsetX: Float

Logical x offset. Updated when the screen is resized.


offsetY: Float

Logical y offset. Updated when the screen is resized.


nativeWidth: Float

Native width


nativeHeight: Float

Native height


nativeDensity: Float

Native pixel ratio/density.


pointerX: Float

Pointer x coordinate, computed from mouse and touch events. When using multiple touch inputs at the same time, x will be the mean value of all touches x value. Use this as a convenience when you don't want to deal with multiple positions.


pointerY: Float

Pointer y coordinate, computed from mouse and touch events. When using multiple touch inputs at the same time, y will be the mean value of all touches y value. Use this as a convenience when you don't want to deal with multiple positions.


pointerDeltaX: Float

Pointer x delta since last frame


pointerDeltaY: Float

Pointer y delta since last frame


mouseX: Float

Mouse x coordinate, computed from mouse events.


mouseY: Float

Mouse y coordinate, computed from mouse events.


mouseDeltaX: Float

Mouse x delta since last frame


mouseDeltaY: Float

Mouse y delta since last frame


mouseWheelDeltaX: Float

Mouse wheel x delta since last frame


mouseWheelDeltaY: Float

Mouse wheel y delta since last frame


touches: Touches

Touches x and y coordinates by touch index.


focusedVisual: Visual

Focused visual


texturesDensity: Float

Ideal textures density, computed from settings targetDensity and current screen state.


isPointerDown: Bool

Whether the screen is between a pointer down and an pointer up event or not.


invalidateFocusedVisual(): Void

invalidateTexturesDensity(): Void

addHitVisual(visual: Visual): Void

Registers a visual as a hit visual.

Hit visuals are special visuals that block input events from reaching visuals behind them, even if they don't handle the events themselves. This is useful for modal dialogs, overlays, or invisible blocking areas.

Name Type Description
visual Visual The visual to register as a hit visual

removeHitVisual(visual: Visual): Void

Unregisters a visual as a hit visual.

The visual will no longer block input events from reaching visuals behind it unless it explicitly handles those events.

Name Type Description
visual Visual The visual to unregister

isHitVisual(visual: Visual): Bool

Checks if a visual is registered as a hit visual.

Name Type Description
visual Visual The visual to check
Returns Description
Bool true if the visual is a hit visual

mouseAllowed(owner: Entity): Bool

Checks if mouse events are currently allowed for the given entity.

This is primarily used with the elements plugin to ensure UI windows can block events from reaching entities behind them. For most use cases, this will always return true.

Name Type Description
owner Entity The entity to check
Returns Description
Bool true if the entity can receive mouse events

mousePressed(buttonId: Int): Bool
Name Type
buttonId Int
Returns
Bool

mouseJustPressed(buttonId: Int): Bool
Name Type
buttonId Int
Returns
Bool

mouseJustReleased(buttonId: Int): Bool
Name Type
buttonId Int
Returns
Bool

touchPressed(touchIndex: Int): Bool
Name Type
touchIndex Int
Returns
Bool

touchJustPressed(touchIndex: Int): Bool
Name Type
touchIndex Int
Returns
Bool

touchJustReleased(touchIndex: Int): Bool
Name Type
touchIndex Int
Returns
Bool

touchDeltaX(touchIndex: Int): Float

Gets the X-axis movement delta for a specific touch since the last frame.

Name Type Description
touchIndex Int The index of the touch to check
Returns Description
Float The X delta in logical coordinates, or 0 if touch not found

touchDeltaY(touchIndex: Int): Float

Gets the Y-axis movement delta for a specific touch since the last frame.

Name Type Description
touchIndex Int The index of the touch to check
Returns Description
Float The Y delta in logical coordinates, or 0 if touch not found

toTexture(done: Function): Void

Captures the current screen content as a texture.

This is an asynchronous operation that renders the current frame to a texture. The resulting texture can be used for effects, transitions, or saving screenshots.

Name Type Description
done Function Callback that receives the captured texture, or null if capture failed

toPixels(done: Function): Void

Captures the current screen content as raw pixel data.

Returns the screen content as an array of RGBA pixels in row-major order. This is useful for image processing or custom screenshot implementations.

Name Type Description
done Function Callback that receives pixel data, width, and height

toPng(done: Function): Void

Captures the current screen content as PNG data.

This overload returns the PNG data as bytes, which can be used for further processing or transmission.

Name Type Description
done Function Callback that receives the PNG data as bytes

Private Members

unobservedFocusedVisual: Visual

unobservedTexturesDensity: Float

matrix: Transform

Root matrix applied to every visual. This is recomputed on screen resize but can be changed otherwise.


reverseMatrix: Transform

Internal inverted matrix computed from root matrix.


resizing: Bool

In order to prevent nested resizes.


pressedMouseButtons: IntIntMap

pressedTouches: IntIntMap

prevTouchPositions: IntFloatMap

prevMouseX: Float

prevMouseY: Float

maxTouchIndex: Int

visualsListenPointerOver: Bool

matchedDownListeners: Map

matchedOverListeners: Map

hitVisuals: Array<Visual>

emitObservedDirty(instance: Screen, fromSerializedField: Bool): Void

Event when any observable value as changed on this instance.

Name Type
instance Screen
fromSerializedField Bool

emitFocusedVisualChange(current: Visual, previous: Visual): Void

Event when focusedVisual field changes.

Name Type
current Visual
previous Visual

emitTexturesDensityChange(current: Float, previous: Float): Void

Event when texturesDensity field changes.

Name Type
current Float
previous Float

emitResize(): Void

Resize event occurs once at startup, then each time any of native width, height or density changes.


emitMouseDown(buttonId: Int, x: Float, y: Float): Void

mouseDown event

Name Type
buttonId Int
x Float
y Float

emitMouseUp(buttonId: Int, x: Float, y: Float): Void

mouseUp event

Name Type
buttonId Int
x Float
y Float

emitMouseWheel(x: Float, y: Float): Void

mouseWheel event

Name Type
x Float
y Float

emitMouseMove(x: Float, y: Float): Void

mouseMove event

Name Type
x Float
y Float

emitTouchDown(touchIndex: Int, x: Float, y: Float): Void

touchDown event

Name Type
touchIndex Int
x Float
y Float

emitTouchUp(touchIndex: Int, x: Float, y: Float): Void

touchUp event

Name Type
touchIndex Int
x Float
y Float

emitTouchMove(touchIndex: Int, x: Float, y: Float): Void

touchMove event

Name Type
touchIndex Int
x Float
y Float

emitPointerDown(info: TouchInfo): Void

pointerDown event

Name Type
info TouchInfo

emitPointerUp(info: TouchInfo): Void

pointerUp event

Name Type
info TouchInfo

emitPointerMove(info: TouchInfo): Void

pointerMove event

Name Type
info TouchInfo

emitMultiTouchPointerDown(info: TouchInfo): Void

multiTouchPointerDown event

Name Type
info TouchInfo

emitMultiTouchPointerUp(info: TouchInfo): Void

multiTouchPointerUp event

Name Type
info TouchInfo

emitMultiTouchPointerMove(info: TouchInfo): Void

multiTouchPointerMove event

Name Type
info TouchInfo

emitFocus(visual: Visual): Void

focus event

Name Type
visual Visual

emitBlur(visual: Visual): Void

blur event

Name Type
visual Visual

backendReady(): Void

Initializes the screen after the backend is ready.

Sets up event listeners for native screen events, initializes coordinate transformations, and configures settings observers. This method is called automatically by the App during initialization.


updatePointerOverState(delta: Float): Void

Updates pointer over/out states for visuals.

Called each frame to track which visuals have pointers hovering over them, triggering pointerOver and pointerOut events as needed.

Name Type Description
delta Float Time elapsed since last frame (unused)

resize(): Void

Handles screen resize events.

Recalculates screen dimensions, scaling, and transformations based on current settings and native screen properties. This method is called automatically when the native screen size changes.

The resize process:

  1. Updates scaling based on settings
  2. Emits resize event (allowing custom handling)
  3. Recomputes transformations
  4. Updates texture density

updateTexturesDensity(): Void

Updates the ideal texture density based on screen density and settings.

The texture density determines which resolution of assets should be loaded. If targetDensity is set in settings, it overrides the calculated value. Otherwise, density is rounded to the nearest integer (minimum 1).


updateScaling(): Void

Recomputes screen dimensions and density based on scaling mode and native properties.

This method implements the different scaling modes:

  • FIT: Scales to fit within target size, may show borders
  • FILL: Scales to fill target size, may crop content
  • RESIZE: Matches native size exactly
  • FIT_RESIZE: Adjusts target size to match native aspect ratio

Updates width, height, actualWidth, actualHeight, density, offsetX, and offsetY.


updateTransform(): Void

Recomputes the root transformation matrix from current screen properties.

The matrix is used to transform all visual coordinates from logical to native screen space. It applies scaling and translation to properly position content on screen based on the current scaling mode.


matchFirstDownListener(x: Float, y: Float, ?touchIndex: Int = -1, ?buttonId: Int = -1): Visual

Finds the topmost visual that should receive a pointer down event at the given coordinates.

This method performs hit testing through the visual hierarchy, respecting:

  • Visual touchability and visibility
  • Event interception by parents
  • Special handling for hit visuals (visuals that block events behind them)
Name Type Default Description
x Float X coordinate in logical screen space
y Float Y coordinate in logical screen space
touchIndex Int -1 Touch index for touch events, -1 for mouse events
buttonId Int -1 Mouse button ID, -1 for touch events
Returns Description
Visual The visual that should receive the event, or null if none found

matchFirstOverListener(x: Float, y: Float): Visual

Finds the topmost visual that should receive pointer over events at the given coordinates.

Similar to matchFirstDownListener but for hover/over events. Only active when at least one visual is listening for pointer over events.

Name Type Description
x Float X coordinate in logical screen space
y Float Y coordinate in logical screen space
Returns Description
Visual The visual that should receive over events, or null if none found

prepareMultiTouchPointerDown(info: TouchInfo): Void
Name Type
info TouchInfo

prepareMultiTouchPointerUp(info: TouchInfo): Void
Name Type
info TouchInfo

prepareMultiTouchPointerMove(info: TouchInfo, isMouse: Bool): Void
Name Type
info TouchInfo
isMouse Bool

updatePointer(): Void

didEmitMouseDown(buttonId: Int, x: Float, y: Float): Void
Name Type
buttonId Int
x Float
y Float

didEmitMouseUp(buttonId: Int, x: Float, y: Float): Void
Name Type
buttonId Int
x Float
y Float

updateMouseOver(x: Float, y: Float): Void
Name Type
x Float
y Float

didEmitTouchDown(touchIndex: Int, x: Float, y: Float): Void
Name Type
touchIndex Int
x Float
y Float

didEmitTouchUp(touchIndex: Int, x: Float, y: Float): Void
Name Type
touchIndex Int
x Float
y Float

updateTouchOver(touchIndex: Int, x: Float, y: Float): Void
Name Type
touchIndex Int
x Float
y Float

resetDeltas(): Void

Resets all input deltas to zero.

Called at the beginning of each frame to clear movement deltas for pointer, mouse, and touch inputs. This ensures deltas only reflect movement within the current frame.


willEmitMouseMove(x: Float, y: Float): Void
Name Type
x Float
y Float

willEmitMouseDown(buttonId: Int, x: Float, y: Float): Void
Name Type
buttonId Int
x Float
y Float

willEmitMouseUp(buttonId: Int, x: Float, y: Float): Void
Name Type
buttonId Int
x Float
y Float

willEmitMouseWheel(x: Float, y: Float): Void
Name Type
x Float
y Float

willEmitTouchMove(touchIndex: Int, x: Float, y: Float): Void
Name Type
touchIndex Int
x Float
y Float

willEmitTouchDown(touchIndex: Int, x: Float, y: Float): Void
Name Type
touchIndex Int
x Float
y Float

willEmitTouchUp(touchIndex: Int, x: Float, y: Float): Void
Name Type
touchIndex Int
x Float
y Float

new(): Void

Creates a new Screen instance.

Typically not called directly - use the singleton instance via app.screen.


elements
canEmitMultiTouchPointerDown(owner: Entity): Bool
Name Type
owner Entity
Returns
Bool

elements
canEmitMultiTouchPointerMove(owner: Entity): Bool
Name Type
owner Entity
Returns
Bool

elements
canEmitMultiTouchPointerUp(owner: Entity): Bool
Name Type
owner Entity
Returns
Bool

elements
canEmitMouseDown(owner: Entity): Bool
Name Type
owner Entity
Returns
Bool

elements
canEmitMouseMove(owner: Entity): Bool
Name Type
owner Entity
Returns
Bool

elements
canEmitMouseUp(owner: Entity): Bool
Name Type
owner Entity
Returns
Bool

elements
canEmitTouchDown(owner: Entity): Bool
Name Type
owner Entity
Returns
Bool

elements
canEmitTouchMove(owner: Entity): Bool
Name Type
owner Entity
Returns
Bool

elements
canEmitTouchUp(owner: Entity): Bool
Name Type
owner Entity
Returns
Bool

elements
canEmitPointerDown(owner: Entity): Bool
Name Type
owner Entity
Returns
Bool

elements
canEmitPointerMove(owner: Entity): Bool
Name Type
owner Entity
Returns
Bool

elements
canEmitPointerUp(owner: Entity): Bool
Name Type
owner Entity
Returns
Bool

Metadata

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