Display

Purpose

Display manages native windows, monitor inventory, modes and dimensions. It supplies the window used by input and presentation; rendering is a separate responsibility.

Interface

Types below are in CE::Platform unless another namespace is shown.

Types and operations

API and purpose
DisplaySystem Enumerate monitors, create/select display-owned windows and query monitor scale. Inventory and selection; adapter catalogue.
Window Read size/mode/close state, request resize/mode/cursor changes and check deferred failures. Sizes, modes and observation.
Monitor Inspect a borrowed monitor inventory entry; copy values before deferred use. Monitor identity and freshness.
WindowResized, CE::Platform::window_resized_event Receive copied drawable pixels and a display-borrowed window pointer. Resize observations; typed channels.

Native GLFW implements these desktop contracts.

Dimensions and modes

Type or choice	Purpose and details
Dimensions	Logical window coordinates; creation/resize requests need positive dimensions. Size units.
FramebufferSize	Drawable pixels, which may be zero; runtime copies them into ticks. Framebuffer observations.
WindowMode	NORMAL, BORDERLESS, FULLSCREEN; backend policy determines supported transitions. Window modes.
Monitor content scale	X/Y scale for a recognized monitor snapshot; separate from per-window notification and explicit UI font scale. Scale and UI capabilities.

Usage

Use the selected window directly during platform initialization or an explicit platform-dispatch callback. During updates, use the runtime’s copied dimensions; that route works in both sequential and concurrent mode.

        ---
config:
  theme: base
  themeVariables:
    fontFamily: system-ui, sans-serif
    fontSize: 14px
  flowchart:
    htmlLabels: true
    curve: linear
    nodeSpacing: 22
    rankSpacing: 38
    padding: 12
---
flowchart LR
    accTitle: Display · application access
    accDescr: Local names omit Platform::; ambiguous nested namespaces remain qualified. Arrows point toward the API or type used, not call order or data flow. Methods beneath type names are selected application entry points; Implement hooks marks engine-invoked overrides. Dashed arrows mark optional choices.
    k0(["Application<br/>init_platform()"]):::app
    k1["<b>Runtime::<br/>Context</b><br/><br/>display(): DisplaySystem<br/><br/>window(): Window<br/><br/>platform_dispatcher(): Runtime::PlatformDispatcher"]:::neighbor
    k2(["Application<br/>platform-owner work"]):::app
    k3["<b>Runtime::PlatformDispatcher::<br/>Submission</b><br/><br/>submit(Work): Result"]:::neighbor
    k4["<b>Window</b><br/><br/>resize(width, height)<br/><br/>set_mode(WindowMode)<br/><br/>hide_cursor(hide)"]:::focal
    k5["<b>DisplaySystem</b><br/><br/>monitors(): Monitor[]<br/><br/>primary_monitor(): Monitor<br/><br/>content_scale(Monitor)"]:::focal
    k6["Monitor"]:::focal
    k7["Dimensions"]:::focal
    k8["WindowMode"]:::focal
    k9(["Application<br/>update()"]):::app
    k10["Game::<br/>TickContext"]:::neighbor
    k11["FramebufferSize"]:::focal
    k12["<b>Rendering::<br/>Camera2D</b><br/><br/>set_framebuffer_size(FramebufferSize)"]:::neighbor
    k0 --> k1
    k2 --> k3
    k2 --> k4
    k1 --> k5
    k1 --> k4
    k5 --> k6
    k4 --> k7
    k4 --> k8
    k9 --> k10
    k10 --> k11
    k9 --> k12
    k12 --> k11
    classDef focal fill:#e7f3ef,stroke:#387d6b,color:#153d33,stroke-width:1.2px
    classDef neighbor fill:#f0f3f8,stroke:#8c9bb1,color:#35445b,stroke-width:1px
    classDef app fill:#fff2df,stroke:#c09452,color:#674515,stroke-dasharray:5 3
    classDef system fill:#eaf0fc,stroke:#617fab,color:#263f69,stroke-width:1.2px
    linkStyle default stroke:#7e8fa7,stroke-width:1.2px

    

Local names omit Platform:: where unambiguous. Explore this diagram and its other views →

Explore the engine-side display relationships. Arrows point from a consumer to the type it uses.

Choose a window observation

Need	Use	What the value means
Size gameplay or a camera for this update	Game::TickContext	The logical/pixel size pair selected for this simulation tick.
Apply required UI sizing before dependent updates	engine.simulation_view().watch(...)	A seeded, simulation-owned selection; retain its Runtime::ViewAttachment.
Inspect current copied platform state from another thread	engine.window_state().snapshot()	A synchronized Runtime::WindowState, including optional native focus. No native window is retained.
Change mode, size or cursor visibility; query a live window	engine.window() on platform	A borrowed Platform::Window with native owner requirements. Dispatch explicit requests from other owners.
Observe a raw native framebuffer resize	Platform::window_resized_event	Copied pixels plus a borrowed window pointer. Native GLFW publishes on the default Events::EventSystem bus.
Observe the runtime’s sampled main-window close intent	Platform::window_close_requested_event on engine.events()	An owned intent fact; negotiation belongs to Runtime’s shutdown policy.

Prefer the selected runtime view for game/UI layout. The raw resize channel and Context bus are distinct routes. A raw callback may be followed by another native change before runtime selects its view. See committed views and native close intent.

Uses

Dependency	Display’s use
Platform::Monitor	Identify entries from this display’s monitor inventory when creating windows or querying scale.
Platform::Dimensions, Platform::FramebufferSize	Keep logical coordinates and drawable pixels distinct. Zero pixel extent can describe a minimized drawable.
Events::EventSystem	Native GLFW dispatches legacy and typed framebuffer-resize observations through the default bus. Events.

Native-library state belongs to the selected backend; the portable display interface does not choose or own a renderer.

Used by

Consumer	Relationship to the window
Runtime::Context, Runtime::GameRuntime	Context owns the display; Runtime samples its active window and coordinates dependent teardown. Runtime.
Input::System	Borrow the live window for native callbacks; detach while it is still alive. Input.
Rendering::OpenGL::GLFWContext	Use the compatible native window for presentation/context operations. OpenGL integration.
Rendering::Camera2D and application layout	Consume copied drawable dimensions; a camera does not own a native window. Rendering.
UI::TGUI::Session, UI::RmlUi::Session	Follow copied simulation dimensions through the supported session integration. GUI.

Contracts

Window dimensions use logical window coordinates; framebuffer dimensions use drawable pixels and may be zero. Creation/resize requests require positive logical dimensions. Monitor inventory references are borrowed and expire on backend refresh or destruction. Copy values before deferred use. The current Native GLFW inventory is captured once at construction and has no hotplug refresh.

Monitor content scale is not a per-window scale notification contract. Window activation alone does not switch a renderer’s graphics-resource domain. A resize payload’s window pointer neither extends its lifetime nor grants access from another thread.

Lifecycle

The display owns created windows; pointers returned to callers are borrowed. Construct compatible input/presentation dependents while the display is live. Detach callbacks and close graphics dependents before destroying their window. Runtime coordinates the normal session cleanup; application-supplied services must preserve the same order during partial initialization and failure.

Execution

Native display/window operations run on the platform owner. Queries do not synchronize access from simulation. Resize callbacks remain on platform; pass their copied observations through runtime input/frame handoff rather than mutating simulation state directly.

Integration

Update a simulation-owned camera from the runtime’s copied observation:

void update(const CE::Game::TickContext& tick) override {
    camera_.set_framebuffer_size(tick.framebuffer_size);
    // Update the game without querying engine_.window() here.
}

Game initialization can read the live window on platform. Later updates use the tick in either runtime mode, so the same game remains safe when concurrent.

Limits and further reading

Read display/window contracts for monitor freshness, mode transitions, scale and native failure limits. The Window and DisplaySystem headers define the portable interface; module details stay in the owner guide.