UIHost.h file

UIHost: the engine's side of GG-UI.

The UI core knows nothing about the engine. The host owns the documents the engine shows, one per window, and runs them: once per display frame each document re-runs what changed, reads its bindings, lays out, paints, and publishes. The renderer draws each window's latest snapshot.

Threads:

Mount, unmount, and scale changes can be requested from any thread and apply at the next update.
UpdateAll and Read are called on Encoder at the start of its frame, so the UI on screen is the one built for that frame. Unrelated documents update in parallel, each on a job, with Encoder working alongside until all are done. A document's functions and handlers therefore run on whichever thread updates it, and two documents' may run at once: anything they share must be safe for that (an atomic, a GGRevision, a queue).
Documents that do share state update serially, in the order given: a popup with its owner, and a document mounted as following another (a tool that reads or changes the document it shows). Sharing a style table doesn't count: tables are only read during updates.
UpdateAll returns on time. A document that overruns the frame's budget (UpdateBudgetSetting) keeps updating on its job after UpdateAll returns. Until it is done it is drawn from its last published snapshot, gets no further update, and its input queues up. Anything requested of it meanwhile (mounting over it, unmounting, closing its popups) waits. The host never touches a document that is updating, and no document waits on another.
Shared read-only state is only changed while none of the documents using it is updating. For a style table that is what ChangeStyles is for; sheet files and a tool's token overrides go through the same path.
Pointer input arrives on Sentinel (RouteInput). Sentinel only decides, from the document's last published snapshot, whether the UI takes it, and queues what it takes. Handlers run in the next update. Sentinel never waits for Encoder, or Encoder for Sentinel.
Styles and the binding reader are set before the engine runs. The reader is called from whichever threads update documents.

Classes

class UIHost: The documents the engine shows, one per window, and the libraries, styles, strings, and services they share. See the file description for which thread does what.
struct UIHost::DockWindowSink: Opens, places, and closes the windows panels float in, and sets window ownership for keep-above.
struct UIHost::PopupWindowSink: Opens, places, and closes the windows popups ask for (GGUI::PopupProps::bOwnWindow).
struct UIHost::TextSink: Text input and clipboard.
struct UIHost::Surface: A window drawn this frame and its target size in pixels.