Screen
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}');
}
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
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 |
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 |
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 |
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 |
Name | Type |
---|---|
buttonId |
Int |
Returns |
---|
Bool |
Name | Type |
---|---|
buttonId |
Int |
Returns |
---|
Bool |
Name | Type |
---|---|
buttonId |
Int |
Returns |
---|
Bool |
Name | Type |
---|---|
touchIndex |
Int |
Returns |
---|
Bool |
Name | Type |
---|---|
touchIndex |
Int |
Returns |
---|
Bool |
Name | Type |
---|---|
touchIndex |
Int |
Returns |
---|
Bool |
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 |
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
Event when any observable value as changed on this instance.
Name | Type |
---|---|
instance |
Screen |
fromSerializedField |
Bool |
Event when focusedVisual field changes.
Name | Type |
---|---|
current |
Visual |
previous |
Visual |
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.
mouseDown event
Name | Type |
---|---|
buttonId |
Int |
x |
Float |
y |
Float |
mouseUp event
Name | Type |
---|---|
buttonId |
Int |
x |
Float |
y |
Float |
mouseWheel event
Name | Type |
---|---|
x |
Float |
y |
Float |
mouseMove event
Name | Type |
---|---|
x |
Float |
y |
Float |
touchDown event
Name | Type |
---|---|
touchIndex |
Int |
x |
Float |
y |
Float |
touchUp event
Name | Type |
---|---|
touchIndex |
Int |
x |
Float |
y |
Float |
touchMove event
Name | Type |
---|---|
touchIndex |
Int |
x |
Float |
y |
Float |
pointerDown event
Name | Type |
---|---|
info |
TouchInfo |
pointerUp event
Name | Type |
---|---|
info |
TouchInfo |
pointerMove event
Name | Type |
---|---|
info |
TouchInfo |
multiTouchPointerDown event
Name | Type |
---|---|
info |
TouchInfo |
multiTouchPointerUp event
Name | Type |
---|---|
info |
TouchInfo |
multiTouchPointerMove event
Name | Type |
---|---|
info |
TouchInfo |
focus event
Name | Type |
---|---|
visual |
Visual |
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.
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:
- Updates scaling based on settings
- Emits resize event (allowing custom handling)
- Recomputes transformations
- 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.
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 |
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 |
Name | Type |
---|---|
info |
TouchInfo |
Name | Type |
---|---|
info |
TouchInfo |
Name | Type |
---|---|
info |
TouchInfo |
isMouse |
Bool |
updatePointer(): Void
Name | Type |
---|---|
buttonId |
Int |
x |
Float |
y |
Float |
Name | Type |
---|---|
buttonId |
Int |
x |
Float |
y |
Float |
Name | Type |
---|---|
x |
Float |
y |
Float |
Name | Type |
---|---|
touchIndex |
Int |
x |
Float |
y |
Float |
Name | Type |
---|---|
touchIndex |
Int |
x |
Float |
y |
Float |
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.
Name | Type |
---|---|
x |
Float |
y |
Float |
Name | Type |
---|---|
buttonId |
Int |
x |
Float |
y |
Float |
Name | Type |
---|---|
buttonId |
Int |
x |
Float |
y |
Float |
Name | Type |
---|---|
x |
Float |
y |
Float |
Name | Type |
---|---|
touchIndex |
Int |
x |
Float |
y |
Float |
Name | Type |
---|---|
touchIndex |
Int |
x |
Float |
y |
Float |
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
.
Name | Type |
---|---|
owner |
Entity |
Returns |
---|
Bool |
Name | Type |
---|---|
owner |
Entity |
Returns |
---|
Bool |
Name | Type |
---|---|
owner |
Entity |
Returns |
---|
Bool |
Name | Type |
---|---|
owner |
Entity |
Returns |
---|
Bool |
Name | Type |
---|---|
owner |
Entity |
Returns |
---|
Bool |
Name | Type |
---|---|
owner |
Entity |
Returns |
---|
Bool |
Name | Type |
---|---|
owner |
Entity |
Returns |
---|
Bool |
Name | Type |
---|---|
owner |
Entity |
Returns |
---|
Bool |
Name | Type |
---|---|
owner |
Entity |
Returns |
---|
Bool |
Name | Type |
---|---|
owner |
Entity |
Returns |
---|
Bool |
Name | Type |
---|---|
owner |
Entity |
Returns |
---|
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 |