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 #

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

Visuals added directly to the screen (via screen.add() or visual.renderTarget = screen). Like a visual's children, this lists direct additions only, not their descendants.

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

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

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

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

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

Logical x offset. Updated when the screen is resized.

Logical y offset. Updated when the screen is resized.

Native width

Native height

Native pixel ratio/density.

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.

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.

Pointer x delta since last frame

Pointer y delta since last frame

Mouse x coordinate, computed from mouse events.

Mouse y coordinate, computed from mouse events.

Mouse x delta since last frame

Mouse y delta since last frame

Mouse wheel x delta since last frame

Mouse wheel y delta since last frame

Touches x and y coordinates by touch index.

Focused visual

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

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

Add a visual to the screen so that it gets mounted and rendered (same as visual.renderTarget = screen). If the visual has a parent, it is removed from it first.

Remove a visual previously added to the screen, which unmounts it (same as visual.renderTarget = null).

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.

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.

Checks if a visual is registered as 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.

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

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

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.

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.

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.

Events #

Event when any observable value as changed on this instance.

Event when focusedVisual field changes.

Event when texturesDensity field changes.

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

Private Members #

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

Internal inverted matrix computed from root matrix.

In order to prevent nested resizes.

Event when any observable value as changed on this instance.

Event when focusedVisual field changes.

Event when texturesDensity field changes.

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

mouseDown event

mouseUp event

mouseWheel event

mouseMove event

touchDown event

touchUp event

touchMove event

pointerDown event

pointerUp event

pointerMove event

multiTouchPointerDown event

multiTouchPointerUp event

multiTouchPointerMove event

focus event

blur event

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.

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

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

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.

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)

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.

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.

Creates a new Screen instance.

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

Metadata #