Module render_world 

Render world definitions and the extract pipeline.

Worlds

• Main world (App::world): UI state, layout, scripts. Tick stages: Input -> CommandDrain -> Systems -> LayoutSync -> A11ySync.
• Render world (App::render_world): per-frame extracted draw data, GPU resource caches, renderer state. Tick stages: Prepare -> Render.

Extract step

After the main schedule and before the render schedule, the registered chain of ExtractFn entries runs. Each function takes (&mut World, &mut World) and copies or upserts draw data from the main world into the render world.

Drawable model

Each render-world entity represents one drawable. Adding a primitive consists of: one Extracted* component, one extract fn, and one render system.

Structs

AnimationsActive

Per-tick flag raised by animation drivers (hover / press tweens, opacity transitions, scroll inertia) while a value is still in motion.

ExtractContextCache

Per-extract-phase memo of the parent-derived maps that every extract fn recomputes identically within a single frame.

ExtractSchedule

Schedule label for the dedicated extract schedule on the render world.

ExtractedBorder

CSS border for one entity: per-side widths, one solid color, painted between the outer border-box edge and the padding box (inside the rect, unlike ExtractedOutline which strokes centered on the box edge). Emitted by extract_borders at the entity’s own PaintOrder; the IR builder pushes borders after rects, so at the shared order key the border paints above the background fill and below all descendants - CSS’s background -> border -> content order.

ExtractedClipBox

One rectangular clip region constraining descendant paints.

ExtractedImage

One decoded image to render this frame in RGBA8 row-major pixels. The renderer wraps rgba in a peniko::Blob whose stable identity keys the vello/wgpu upload cache across frames.

ExtractedOutline

Stroked outline ring rendered around an entity (typically when crate::input::Focused).

ExtractedRect

One filled rectangle to render this frame.

ExtractedScrollbar

Overlay-scrollbar draw list for one scroll container (spec section 16.2 / section 16.6). Emitted by extract_scrollbars; the IR builder appends the rects - in draws order - AFTER every other leaf sharing the same PaintOrder, so bars always paint above the container’s content (the order is the container’s max descendant order + 1, which also places them outside the container’s clip bracket - overlay bars are never clipped by their own viewport).

ExtractedShadow

Shadow extracted for one entity. The renderer draws it at order = rect.order - 1 so it appears underneath the source rect without bleeding onto unrelated siblings.

ExtractedText

One text run to render this frame.

FrameDamage

Per-frame list of damage rectangles for partial-redraw / dirty-region rendering.

FrameDirty

Per-frame flag indicating that the upcoming frame requires a fresh GPU encode.

HiddenExtracts

Render-world snapshot of the set of MAIN-world entities that are hidden by a [Visible(false)] on themselves or any ancestor (CSS visibility: hidden semantics - the box keeps its layout space but paints nothing).

OverlayLayer

Marker component lifting an entity and its whole subtree into the top-layer paint band (browser top-layer / Qt popup-window semantics): the subtree paints after ALL normal tree content regardless of its document position, keeps its internal document order, and escapes ancestor clip / scroll-cull rects (its own internal clips still apply).

OverlayOpenOrder

Main-world resource tracking the order in which OverlayLayer roots became visible, so concurrently open popups stack later-opened-on-top (like OS popup windows).

Rect

Axis-aligned rectangle in logical pixel coordinates. Used by FrameDamage.

Render

Schedule label for the render schedule.

RenderEntityMap

Persistent map from a main-world entity to its render-world entity for each Extracted* type. Upserting extracts read the prior map, update render entities in place, and write the new map back; legacy despawn-and-respawn extracts leave their slot untouched.

ScrollbarDrawRect

One rounded solid rect of an overlay scrollbar (track or thumb).

SurfaceCapture

Coordination handle for on-screen surface screenshots, inserted as a Resource into both worlds.

SurfaceFrame

One CPU-side snapshot of the on-screen window surface produced by a GPU->CPU readback.

Viewport

Window viewport, inserted as a Resource into both the main and render worlds. The window plugin writes both copies on every resize.

Enums

Brush

Fill brush for an ExtractedRect. Gradient variants store their stops in an Arc<[...]> so cloning the brush bumps the Arc instead of deep-copying.

ExtractSet

SystemSet label for render-world extract systems registered via crate::app::App::add_extract_systems.

RenderStage

Ordered stages inside the Render schedule.

Constants

DEFAULT_SELECTION_BG

Single built-in fallback for the selection highlight when no selection-color token is set - the platform “highlight” blue at ~40 % alpha (mirrors macOS / web selection tints and Qt’s Highlight role). Translucent on purpose so the text underneath keeps its contrast, so no selection-text-color is required for legibility. Skins override the whole look via the --lumen-selection token; this is the one Rust fallback.

OVERLAY_ORDER_BASE

First PaintOrder of the top-layer band. Every rank in an OverlayLayer subtree is >= OVERLAY_ORDER_BASE; every normal-tree rank is below it (real UI trees are nowhere near 0x2000_0000 entities), so overlay content always paints after all normal content.

Functions

build_parent_map

Returns (parent_map, document_order_map) used by every extract fn to compute PaintOrder consistently.

clear_extracted

Despawns transient render-world entities carrying Extracted* components, called once per frame before any ExtractFn runs.

cull_hidden

Prepare-stage guard that despawns every extracted render entity whose owning main entity is hidden (per HiddenExtracts), then drops those entries from RenderEntityMap so the next frame’s keyed upserts start clean. Runs before crate::node_ir::transform_extracted_to_nodes so no hidden leaf reaches the retained tree.

cull_offscreen

Despawns extracted entities whose AABB lies fully outside the Viewport.

extract_borders

Extract fn that emits one ExtractedBorder per main-world entity carrying a Transform and a Visuals::border. A border paints even when the entity has no background fill (CSS: background: none; border: 1px solid ... still draws the border). Logical border edges (border-inline-*) are resolved against the entity’s crate::components::ResolvedDirection.

extract_clips

Extracts one ExtractedClipBox per clipping entity (carrying crate::input::Scroll or Style.overflow_x / overflow_y == Hidden). Each emission carries the containing rect plus the (start_order, end_order) range bracketing descendant paints so the renderer can push/pop a vello layer.

extract_rects

Default extract fn that emits one ExtractedRect per main-world entity carrying a Transform and a Visuals::fill.

extract_scrollbars

Extract fn emitting one ExtractedScrollbar per crate::input::Scroll container whose content overflows on an allowed axis and whose fade alpha is above zero. Geometry comes from the shared crate::input::vertical_scrollbar / crate::input::horizontal_scrollbar math so painted pixels and hit regions always agree. All visuals (colors, thickness, minimums) resolve through crate::input::ScrollbarStyle - CSS scrollbar-color / scrollbar-width per container, with the component’s Default as the no-stylesheet fallback.

extract_shadows

Extract fn that emits one ExtractedShadow per entry in Visuals::shadows. Each shadow is placed at rect.order - 1 + idx so it paints under the source rect and stacked shadows keep source order.

extract_text

Default extract fn that emits one ExtractedText per entity with Transform and TextContent.

hidden_entities

Returns the set of entities hidden by a [Visible(false)] on themselves or any ancestor.

paint_order_of

Returns the PaintOrder for e - the document-order rank precomputed by build_parent_map (whose second return value is the map passed here as cache).

parent_opacities

Returns each entity’s cumulative ANCESTOR opacity product (own Opacity excluded - extract fns already fold that in). CSS semantics: opacity multiplies down the subtree, so fading a dialog root fades every descendant. Returns an empty map when no entity carries an Opacity (the overwhelmingly common case - extracts then skip the lookup entirely).

parent_scroll_clip_rects

Returns the nearest clipping-ancestor rect (origin and size in window coordinates) for every entity.

parent_scroll_offsets

Returns each entity’s cumulative ancestor-chain ScrollOffset.

reset_animations_active

Clears AnimationsActive at the top of every tick (registered in crate::tick::TickStage::Input, which is chained before the Systems stage where animation drivers run). Recomputing the flag from scratch each tick is what guarantees idle-quiescence: a tick with no live animation leaves it false.

roll_up_frame_dirty

Rolls up render-relevant change signals into FrameDirty. Runs each tick in crate::tick::TickStage::A11ySync; the window backend reads the flag right before encoding and clears it after submission.

stash_hidden_entities

Extract fn: recompute the hidden-subtree set from the main-world hierarchy and mirror it into the render world for cull_hidden.

Type Aliases

ExtractFn

Function pointer for an extract step. Stateless; closures are disallowed, so per-extract state lives in render-world resources.

PaintOrder

Painter-algorithm sort key for Extracted* entries. Higher values paint later (closer to the viewer).