GUI

Purpose

GUI integrations connect toolkit-native widgets/documents to Engine input and retained rendering. The application controls session lifetime, UI ownership, focus, pointer selection and integration with game state.

Interface

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

The TGUI and RmlUi modules each own their session, native authoring API and recording/publication types.

Types and operations

API and purpose
`TGUI::Session`, `RmlUi::Session` Own toolkit lifetime; supply copied dimensions, time and input, and manage explicit keyboard focus. Session construction; routing.
`TGUI::RecordedScene`, `RmlUi::RecordedScene` Retain owned CPU recordings without live toolkit objects crossing to graphics. Update and publication.
`TGUI::SceneUploader`, `RmlUi::SceneUploader` Transfer owned recordings to the provider owner and publish complete scenes. Upload and cleanup.
`TGUI::Scene`, `RmlUi::Scene` Append retained UI draw packets during frame preparation. Retained publication; GUI task.

Configuration and capabilities

Type or choice	Purpose and details
`TGUI::SessionOptions`, `RmlUi::SessionOptions`	Set maximum texture size; TGUI also supplies explicit font scale. RmlUi uses native document styling. Adapter ownership; TGUI, RmlUi.
`TGUI::Capabilities`, `RmlUi::Capabilities`	Report keyboard focus, committed text, clipboard, cursor and IME availability; RmlUi also reports clipping/effects support. Unavailable services.
`CE::Input::Routing::KeyboardPolicy` and pointer selection	`Exclusive`/`PassThrough` controls keyboard gameplay. The application separately selects pointer recipients. GUI routing.
`TGUI::Materials`, `RmlUi::Materials`	Optionally override automatic defaults with compatible loaded material handles. Custom UI materials.
`TGUI::WidgetLayout`	Typed placement/resizing for native TGUI widgets; RmlUi uses native RML/RCSS layout. Choose an interface; TGUI layout declarations.
`CE::Text::FontService` and `CE::Text::Font`	Context-aware sessions inherit the Engine default and catalogue; per-widget/document overrides accept the same retained handle as direct text. GUI fonts; font service.

Usage

Choose a toolkit, construct its session on the UI owner and retain native widgets/documents there. Record owned CPU data, upload a complete scene on graphics, then append that scene during frame preparation.

        ---
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: GUI · TGUI publication
    accDescr: Local names omit UI::; ambiguous nested namespaces remain qualified. Arrows point toward dependencies. Application roles are rounded; named API operations have rounded corners. Dashed arrows mark optional choices.
    k0(["Application-owned UI"]):::app
    k1["TGUI::<br/>Session"]:::focal
    k2["Input::<br/>System"]:::neighbor
    k3["Text::<br/>FontService"]:::neighbor
    k4["TGUI::<br/>RecordedScene"]:::focal
    k5["TGUI::<br/>SceneUploader"]:::focal
    k6["Runtime::PlatformDispatcher::<br/>Submission"]:::neighbor
    k7["Rendering::Resources::<br/>Provider"]:::neighbor
    k8["TGUI::<br/>Scene"]:::focal
    k9(["Application<br/>prepare_render_frame()"]):::app
    k10["Rendering::<br/>PassWriter"]:::neighbor
    k0 --> k1
    k1 --> k2
    k1 --> k3
    k1 --> k4
    k5 --> k4
    k5 --> k6
    k5 --> k7
    k5 --> k8
    k9 --> k8
    k8 --> k10
    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 UI:: where unambiguous. Explore this diagram and its other views →

The RmlUi variant follows the same retained publication boundary with its own native document API. The application map includes runtime, view and focus connections.

Choose an authoring interface

Choice	Authoring and layout	Rendering/material rule
TGUI	Native widgets through `Session::gui()`; optional typed `WidgetLayout` rules.	Colored triangles with straight alpha. The uploader supplies defaults unless explicit `Materials` overrides are passed.
RmlUi	Native RML documents, RCSS styles and element/event APIs through `Session::context()`.	Colored triangles with premultiplied alpha; rectangular clipping is supported, effects are reported unavailable.

Both use retained Engine fonts and CPU image decoding. Their session, recording, scene and material types remain distinct. Each integration owns process-global toolkit state with its own coexistence restrictions; consult its module owner before composing sessions. Toolkit capabilities also define which input and platform services are actually available.

Uses

Consumer	Dependency	Integration boundary
Toolkit `Session`	Input `Input::System` and copied `Input::Events::Record` values	Borrow input for the session lifetime; feed the entire ordered batch once. Keyboard focus leases and pointer selection are separate application decisions.
Font/image bridges	Text retained fonts and `FontRasterizer`; Assets CPU image decoding	Share CPU data/operations without sharing live toolkit objects or using the direct text renderer as the toolkit’s layout engine.
`SceneUploader`	Resources provider and Dispatch `PlatformDispatcher::Submission`	Upload on the original provider/owner. Submitted work owns its recording/material handles and contains no live widgets/documents.
Uploaded `Scene`	Rendering `FrameWriter` and retained draw packets	`write(frame)` appends a pass; rendering later needs no toolkit access.
Optional view/time attachments	Runtime `SimulationViewSource` and `RuntimeServices`	Apply copied dimensions or selected simulation-step time on the UI owner, not by reading a live window from simulation.

Used by

Consumer	Entry point	Responsibility
Application UI controller	`UI::TGUI::Session` or `UI::RmlUi::Session`	Own native authoring, focus policy, pointer selection and callbacks into simulation-owned application state. GUI construction.
Menus, HUD components and editors	Native widgets/documents in that session	Share the enclosing session’s routing identity and lifetime; release native references before toolkit closure. HUD tutorial.
Application frame preparation	`UI::TGUI::Scene::write()` or `UI::RmlUi::Scene::write()`	Select a complete uploaded scene and its pass order. `adopt_scene()` polls without waiting and preserves the current scene on failure.

Decide who supplies view and time

The Context constructor supplies input and the font catalogue, but automatic view/time participation still requires the corresponding options. Enable them on the initialized simulation owner, normally during init_simulation(); the automatic view source is not ready during init_platform().

Mode	View and time work	Work still supplied by the application
Automatic	Enable `SessionOptions::automatic_view` and/or `automatic_time` when constructing with Context, or explicitly call `follow_view()` / `follow_time()`.	Feed records, choose focus/pointer recipients, author UI, record/upload/adopt scenes and append them to frames.
Manual	Call `set_view()` with copied logical/framebuffer dimensions and `update_time()` with simulation elapsed seconds.	Initialize dimensions before input/recording and refresh changes; keep advancement on the UI owner.

A valid set_view() switches sizing to manual. Call detach_time() before manual time advancement when automatic time is attached. Automatic time starts with future selected simulation steps; it does not replay the current step. See the TGUI and RmlUi contracts for required attachment failure and teardown behavior.

Contracts

Create the session before native toolkit objects and call them only on the UI owner. Input must outlive its session; external widgets/fonts/textures/documents must not outlive toolkit shutdown. Toolkit global state imposes session coexistence limits described by each owner.

Feed the complete ordered input batch once so modifier releases remain visible. Keyboard focus and pointer selection are separate choices. Copied tick dimensions determine layout; monitor scale or a live window query must not be invented on simulation. Recording/upload must preserve earlier immutable generations already retained by frames.

Lifecycle

Prepare the scene uploader during platform-owned initialization. It creates default materials lazily through the selected resource provider. Create the toolkit session on its UI/simulation owner, then native objects. Update input, time and layout there, record CPU state, dispatch upload and retain the latest complete scene. During shutdown, stop UI calls and release application-held toolkit references before close_after_quiescence() and session destruction. Keep accepted upload dependencies alive until runtime settles them.

Execution

In concurrent runtime mode, UI mutation/recording belongs on simulation and resource upload belongs on graphics. Sessions permit final platform teardown after simulation has joined. Toolkit callbacks must update UI/simulation-owned state or submit owned work, not directly perform native graphics operations.

Integration

With session_ constructed on its owner as shown in GUI construction, create a native TGUI button. A session constructed with Context already inherits the Engine default font and configured catalogue; no widget font setup is needed for this case:

auto button = tgui::Button::create("Apply");
button->onPress([this] { apply_requested_ = true; });
session_->gui().add(button);
session_->request_keyboard_focus();

The application retains session_ and the callback target. It must also select pointer delivery, feed records and publish the recorded scene. The GUI construction guide explains those surrounding steps; the HUD tutorial connects TGUI widgets to a game, and the focused GUI task shows the RmlUi document approach.

Limits and further reading

There is no universal Engine widget API or context-owned UI manager. Reported capabilities define clipboard, cursor, text/focus and IME availability. Read the module owner guides, UI adapter contracts and the maintained toolkit demo.