Renderer Optimizations
A source-indexed inventory of the work Hera avoids when preparing, drawing, and presenting a frame.
Hera keeps rendering on the server. Its optimizations reduce scene preparation, submitted draws, shaded pixels, filter passes, allocations, transfers, and waits while preserving retained-scene ownership and paint order. This inventory covers the server render path, including composer preparation, Vulkan shaders and resources, and DRM presentation. Client-side view memoization, layout, and text shaping have their own evaluation, layout, and text guides.
Initial source audit: October 15, 2026; scrolling follow-up: October 18, 2026. File names and one-based line numbers refer to the working checkout at the time of each audit, including local renderer changes. Links open the corresponding file on GitHub’s main branch; unpublished changes and later edits can shift those lines. Each reference points to the implementing function, branch, or shader, rather than an optimization proposal. These are implementation claims, not promises of a measured speedup on every GPU.
The sections follow the frame pipeline. “Automatic” means the path is enabled when its eligibility checks pass. Opt-in paths are identified explicitly; all environment switches are collected under Controls and Defaults.
Frame Preparation and Scheduling
-
Unchanged-frame suppression. The composer compares the last successfully submitted revision by identity. With no active animations or live mutable buffers, it returns before snapshot preparation and renderer submission. Frame-schedule notifications continue, so clients can still drive animation.
Source: crates/composer/src/composer.rs:414; crates/server/src/frame/driver.rs:103.
-
Shared scene snapshots. Retained nodes and snapshots share
Arcstorage. Mutation uses copy-on-write, so unchanged node payloads, child lists, and glyph data need not be deep-cloned for each rendered snapshot.Source: crates/graph/src/lib.rs:407; crates/graph/src/snapshot.rs:37.
-
Static-scene scan avoidance. Maintained image and secondary-transform counts avoid resource-name resolution and animation/transform walks when the scene has neither. Buffer IDs are rewritten only when resolution changes them; animation sampling mutates tracked nodes rather than cloning every static node.
Source: crates/composer/src/composer.rs:455; crates/composer/src/animation/controller.rs:328; crates/graph/src/lib.rs:138.
-
Measured render lead time. The scheduler reserves a future presentation boundary using recent CPU preparation/submission durations plus the asynchronous GPU tail and a configurable margin. It skips boundaries that cannot be reached and preserves display phase instead of accumulating timer drift.
Source: crates/composer/src/scheduler.rs:183; crates/composer/src/scheduler.rs:175.
-
Render ahead with triple buffering. Opt-in
HERA_RENDER_AHEAD=1selects triple buffering inherad, which may acquire a free slot while a previous presentation is pending. The runtime retains deferred work and uses nonblocking retirement checks; double buffering uses ordinary acquisition. GPU completion and KMS release both remain prerequisites for safe slot reuse.Source: apps/herad/src/config.rs:31; crates/renderer/src/runtime/vulkan.rs:245; crates/renderer/src/swapchain/core.rs:235.
-
Precise render deadlines. Opt-in
HERA_PRECISE_TIMER=1uses a nonblocking Linuxtimerfdfor scheduled render wakeups, avoiding coarse timer rounding without spinning. Unsupported platforms and timer failures fall back to Tokio deadlines. This changes wakeup precision, not whether an unchanged scene needs a frame.Source: apps/herad/src/config.rs:35; crates/server/src/frame/timer.rs:14.
Scene Planning and Visibility
-
Early subtree rejection and shared traversal context. Invisible nodes and non-invertible evaluated transforms stop traversal. Scene indices and output builders are borrowed once by the traversal context, while inherited transforms, clips, opacity, and ordering travel with each visit.
Source: crates/renderer/src/vulkan/scene/planning/draw/traversal.rs:18; crates/renderer/src/vulkan/scene/planning/draw/traversal.rs:73.
-
Empty and transparent draw removal. Planning removes clipped-out draws, empty group targets, and material fills proven to have no ink. A separate repaint-time check can omit transparent interiors inside the active repaint; borders, masks, and effects keep conservative eligibility checks.
Source: crates/renderer/src/vulkan/scene/planning/groups.rs:471; crates/renderer/src/vulkan/scene/planning/groups.rs:525; crates/renderer/src/vulkan/scene/renderer/admission.rs:80.
-
Opaque tile culling. Reverse paint-order scans track fully covered tiles and omit earlier draws hidden by proven opaque rectangles. Coverage uses 32-pixel tiles for ordinary targets and one-pixel tiles for groups at most 32 by 32 pixels. Partial tiles never prove opacity; direct and nested backdrop readers reset coverage.
Source: crates/renderer/src/vulkan/scene/planning/groups.rs:525; crates/renderer/src/vulkan/scene/planning/cull.rs:35.
-
Bitset coverage operations. Tile marking and containment queries operate on word spans rather than individual tile bits. Small local groups retain precise coverage without allocating a full framebuffer-sized pixel mask.
Source: crates/renderer/src/vulkan/scene/planning/cull.rs:109; crates/renderer/src/vulkan/scene/planning/cull.rs:123.
-
Hidden isolated-subtree elimination. When an isolated group’s complete output is covered, its composite and descendant draws are removed together, avoiding the group’s GPU passes and resources. A shared visited traversal propagates removal once per group. Destination-reading groups retain their dependency barriers.
Source: crates/renderer/src/vulkan/scene/planning/groups.rs:649.
-
Linear backdrop propagation and stable compaction. A reverse-edge work queue marks ancestors containing backdrop readers once. Draw compaction remaps group membership in place in the same index space, preserving ordering and reusing the resulting metadata during damage admission instead of rebuilding it at every stage.
Source: crates/renderer/src/vulkan/scene/planning/groups.rs:205; crates/renderer/src/vulkan/scene/planning/groups.rs:685.
-
Transparent border-center omission. Large combined fill/border rectangles with transparent centers are split into at most four disjoint edge scissors. The original geometry and derivatives stay intact. At most 64 candidates are split; the hole must save at least 4,096 pixels and half the original area. Enabled by default.
Source: crates/renderer/src/vulkan/scene/planning/border.rs:13.
-
Combined border and fill. Eligible solid borders and their fill share one primitive and coverage calculation, reducing separate draws while avoiding an antialiased seam. Border geometry or paint that cannot use this representation follows the other rectangle paths.
Source: crates/renderer/src/vulkan/scene/planning/draw/rectangle.rs:68.
Damage and Repaint Reduction
-
Per-output-image damage history. Each target compares its own last accepted evaluated draw snapshot against the current one. This preserves untouched pixels across rotating swapchain images and catches animation, transforms, moves, removals, paint changes, and reorderings without relying on commit IDs alone. Missing or oversized history falls back conservatively.
Source: crates/renderer/src/vulkan/scene/planning/damage.rs:520; crates/renderer/src/vulkan/scene/planning/damage.rs:791; crates/renderer/src/vulkan/scene/renderer.rs:141.
-
Stable content matching. Damage comparisons match surviving draws across insertion and group renumbering and compare referenced style/gradient contents rather than their relocated table offsets. Masked group output comparisons can ignore scratch padding changes that do not change visible output; cache identity remains stricter.
Source: crates/renderer/src/vulkan/scene/planning/damage.rs:991; crates/renderer/src/vulkan/scene/planning/damage.rs:1135.
-
Hidden-damage subtraction. Unchanged later opaque coverage can suppress damage from changes behind it, including coverage exported through eligible group composites. Exact rectangle subtraction preserves holes. Visible backdrop readers keep the input pixels they need, and coverage/fragmentation limits fall back to repainting more.
Source: crates/renderer/src/vulkan/scene/planning/damage.rs:266; crates/renderer/src/vulkan/scene/planning/damage.rs:947.
-
Disjoint damage regions. Opt-in
HERA_DAMAGE_REGIONS=1keeps up to eight disjoint repaint rectangles instead of shading the gaps in one bounding rectangle. Reader footprints are considered before splitting; excessive fragmentation or graph cost falls back to a conservative bounding repaint.Source: crates/renderer/src/vulkan/scene/planning/damage.rs:18; crates/renderer/src/vulkan/scene/planning/damage.rs:83; crates/renderer/src/vulkan/scene/renderer/admission.rs:155.
-
Immutable buffer-frame damage chains. Frame stamps and predecessor history allow the renderer to union producer damage across frames skipped by a particular output image. Local pixel rectangles are mapped into each occurrence of the image in the scene. Missing history, cross-stream changes, and unsupported mappings trigger conservative redraw.
Source: crates/renderer/src/vulkan/resources/external_images/frame_history.rs:87; crates/renderer/src/vulkan/scene/planning/damage.rs:1080.
-
Repaint-driven resource preparation. Admission removes draws that cannot contribute to the repaint or its effect inputs before glyph raster/upload work and instance growth. Empty repaint clears the active draw/group lists and skips paint-table uploads. Full scene history remains available for the next comparison.
Source: crates/renderer/src/vulkan/scene/renderer/admission.rs:67; crates/renderer/src/vulkan/scene/renderer/recording.rs:39.
-
Local group repaint. Eligible unfiltered groups render only the local input region needed for their damaged output, including a sampling margin. Filters and nested readers expand the required input conservatively; clipping a composite never authorizes dropping convolution inputs.
Source: crates/renderer/src/vulkan/scene/planning/groups.rs:162; crates/renderer/src/vulkan/scene/passes/group.rs:261.
-
Opaque group background elimination. A group proven to cover the whole repaint can discard earlier main operations and the group’s own members preceding its opaque base. This also removes unnecessary copied-background dependencies when the proof establishes that those pixels cannot reach the output.
Source: crates/renderer/src/vulkan/scene/passes/main.rs:134.
Partial Occlusion and Backdrop Copies
-
Opaque-interior repaint partitioning. With
HERA_PARTIAL_OCCLUSION=1, a large useful opaque core can divide the repaint into at most five regions. The core must cover at least 65,536 pixels and half the repaint. Scenes with backdrop or content-filter dependencies keep the original region to avoid composite seams.Source: crates/renderer/src/vulkan/scene/passes/opaque.rs:19.
-
Group occlusion culling and partial cache restoration. With
HERA_PARTIAL_OCCLUSION=1, one proven opaque rectangle from a later group can hide earlier main draws and top-level group output. Fully hidden output skips the group; partially visible output restricts ordinary group draws, retained-run restore copies, and final composites to at most four disjoint rectangles. Scissors retain the original geometry, and copies/composites stay in one pass. Backdrop reader footprints are excluded from the hidden area, and source rendering preserves a two-pixel sampling margin. Filtered producers and nested groups remain conservative; cache population always renders the complete run so moving a covering window cannot reveal incomplete cached pixels.Source: crates/renderer/src/vulkan/scene/passes/main.rs:188; crates/renderer/src/vulkan/scene/passes/opaque.rs:153; crates/renderer/src/vulkan/scene/passes/opaque.rs:171.
-
Backdrop initialization copy reduction. Before drawing a group that contains backdrops, the renderer can omit parent pixels guaranteed to be overwritten by an opaque member. It stops at the first useful overwrite, preserves earlier direct/nested reader inputs, and emits at most four copy regions in one transfer pass. Shares
HERA_PARTIAL_OCCLUSION.Source: crates/renderer/src/vulkan/scene/passes/opaque.rs:92; crates/renderer/src/vulkan/scene/passes/group.rs:272.
Retained Pixel Caches
-
Opaque suffix caching. Enabled by default, the retained-run cache captures a stable suffix beginning at a fully opaque rectangular base inside an existing group target. Hits replace its draws with integer image copies, including eligible nested content. Candidates need at least two members, a footprint of at least 4,096 pixels, containment inside the opaque base, and no backdrop dependence.
Source: crates/renderer/src/vulkan/scene/renderer/retained_runs.rs:16; crates/renderer/src/vulkan/scene/passes/retained_runs.rs:69.
-
Stable-run population and partial restoration. A matching previous plan makes an opaque suffix eligible for population. A partially damaged window can render the complete stable suffix into its existing target to populate the cache, while keeping final output damage unchanged. Hits restore only needed visible regions; captures always preserve complete pixels.
Source: crates/renderer/src/vulkan/scene/passes/group.rs:253; crates/renderer/src/vulkan/scene/passes/group.rs:314.
-
Exact cache identities with translation reuse. Keys normalize integer origins and group numbering while preserving fractional sampling phase, topology, evaluated draws, materials, and immutable image identities. Matching keys reuse their retained allocation. Mutable or unknown image contents cannot prove a hit; neither hashes nor scene versions alone authorize reuse.
Source: crates/renderer/src/vulkan/scene/run_cache.rs:73; crates/renderer/src/vulkan/scene/run_cache.rs:202.
-
Completed content-blur image caching. Opt-in
HERA_FILTER_CACHE=1reuses complete top-level filtered groups with no root mask or descendant backdrop. A hit skips drawing and filtering and uses the ordinary composite. A miss retains the existing final filtered image without adding a copy or filter pass; only complete results in the last repaint region are captured.Source: crates/renderer/src/vulkan/scene/renderer/filtered_groups.rs:16; crates/renderer/src/vulkan/scene/passes/main.rs:575.
-
Bounded cache ownership and fallback. Both caches share limits of 32 completed images and 32 MiB of actual allocation bytes, with at most 1,024 draws per key and bounded candidate inspection. Images become reusable only after GPU retirement. Optional cache plans can retry uncached; scratch-budget pressure can return unused completed filter images to the pool and retry compilation once.
Source: crates/renderer/src/vulkan/scene/run_cache.rs:21; crates/renderer/src/vulkan/scene/renderer/resources.rs:375; crates/renderer/src/vulkan/scene/renderer.rs:369.
Effects and Shader Specialization
-
ROI-sized intermediate targets. Isolated group and backdrop targets use bounded regions of interest instead of full output-sized images. Bounds include finite filter support and mask/antialiasing requirements. Nested encoding rebases into the target’s local coordinates, keeping source texture extent separate from visible composite output.
Source: crates/renderer/src/vulkan/scene/planning/draw/group.rs:15; crates/renderer/src/vulkan/scene/planning/blur.rs:245; crates/renderer/src/vulkan/scene/encode/coordinates.rs:24.
-
Separable three-box blur and identity-stage removal. The blur planner approximates the Gaussian with three box filters, each executed horizontally then vertically. Zero-radius stages produce no passes or instance reservations. Kernel support is finite and bounded to the shader’s supported radius.
Source: crates/renderer/src/vulkan/scene/planning/blur_math.rs:53; crates/renderer/src/vulkan/scene/planning/blur.rs:81; crates/renderer/src/vulkan/scene/passes/blur.rs:768.
-
Bilinear paired blur taps. Each midpoint texture fetch combines two adjacent box-filter taps, doubles the weight, and retains the final unpaired texel. The loop processes two pairs per iteration. This reduces sampling work with the existing linear clamp-to-edge sampler and premultiplied color convention.
-
Bounded blur writes. Enabled by default,
HERA_BLUR_REGIONSbounds backdrop and content-blur output to what consumers need. The planner walks backward through every kernel and the final linear sampler to produce enough input texels. Texture sizes and UV mapping remain unchanged; content source drawing stays conservative.Source: crates/renderer/src/vulkan/scene/planning/blur.rs:96; crates/renderer/src/vulkan/scene/passes/blur.rs:709.
-
Optional backdrop downsampling.
HERA_BACKDROP_DOWNSAMPLE=2or4reduces eligible backdrop filter targets while keeping final masks and foreground geometry at native resolution. This is a quality/performance tradeoff. Small filters, targets below 16 pixels on either axis, and insufficient boundary support stay at native size; eligibility requires sigma of at least 8.Source: crates/renderer/src/vulkan/scene/planning/blur.rs:10; crates/renderer/src/vulkan/scene/passes/blur.rs:79.
-
Plain solid-fill pipeline. Canonical borderless, unrounded, unfiltered fills use a minimal vertex/fragment path, avoiding general shape, style, and effect evaluation. Tiny specialized runs next to compatible general-solid batches can be folded back into the general pipeline to avoid paying for extra state changes.
Source: crates/renderer/src/vulkan/scene/encode.rs:91; crates/renderer/shaders/plain.frag:5; crates/renderer/src/vulkan/scene/encode.rs:130.
-
Rounded solid-fill pipeline. Borderless rounded solid fills use a dedicated coverage shader with the same rounded-edge calculation as the general shader. Non-default geometry/effect cases retain the general path.
Source: crates/renderer/src/vulkan/scene/encode.rs:97; crates/renderer/shaders/rounded.frag:36.
-
Image, glyph, group, and blur pipelines. Ordinary unblurred images/glyphs without gradient paint use the texture shader; eligible premultiplied group composites use the group shader; box-filter passes use the blur shader. Each specialization avoids unrelated branches while retaining general fallbacks.
Source: crates/renderer/src/vulkan/scene/encode.rs:80; crates/renderer/src/vulkan/scene/encode.rs:942; crates/renderer/src/vulkan/scene/passes/blur.rs:525.
-
Direct box-shadow evaluation. Modern outset/inset box shadows are emitted as silhouette draws rather than full offscreen content-blur chains. The shader integrates the Gaussian analytically in the horizontal direction and with bounded vertical quadrature, with a zero-sigma coverage path.
Source: crates/renderer/src/vulkan/scene/planning/draw/box_shadow.rs:5; crates/renderer/shaders/box_shadow.glsl:1.
-
Optional shadow-only shader.
HERA_SHADOW_SPECIALIZE=1selects a dedicated shader for eligible shadow draws, leaving unsupported cases on the general solid pipeline. This is independent of the direct box-shadow representation.Source: crates/renderer/src/vulkan/scene/renderer.rs:339; crates/renderer/shaders/shadow.frag:9.
-
Backdrop interior overwrite. Opt-in
HERA_COMPOSITE_OVERWRITE=1replaces the two attenuation/addition draws inside proven unit-opacity, unit-coverage mask interiors with one overwrite. Curved/antialiased edges keep both blend steps. The axis-aligned interior must be at least 4,096 pixels;HERA_MASK_COPY=1additionally selects a minimal sampling shader for that interior.Source: crates/renderer/src/vulkan/scene/encode.rs:1005; crates/renderer/src/vulkan/scene/encode.rs:913; crates/renderer/shaders/mask_copy.frag:7.
-
Compatible color-pass fusion. Opt-in
HERA_MERGE_COLOR_PASSES=1joins an unmasked group composite to its immediately preceding compatible attachment-only pass, eliminating an intermediate STORE/LOAD and barrier. Fusion is pairwise, preserves paint order and scissors, and requires the same single-sampled RGBA8/BGRA8 UNORM target. Destination sampling, transfers, later clears, and incompatible writes retain boundaries.Source: crates/renderer/src/vulkan/graph/fusion.rs:5; crates/renderer/src/vulkan/graph/fusion.rs:78.
Batching and Resource Reuse
-
Instanced quad batching. Draws with compatible pipeline, scissor, and sampled-image state are packed into adjacent batches and issued as indexed instances over shared quad geometry. Painter order is preserved. Empty batches emit no vertex binding or draw.
Source: crates/renderer/src/vulkan/scene/encode.rs:495; crates/renderer/src/vulkan/scene/encode.rs:319; crates/renderer/src/vulkan/scene/renderer/resources.rs:263.
-
Redundant command-state elimination. The encoder binds vertex buffers once per uploaded segment and uses
firstInstanceoffsets. It changes pipelines, scissors, and sampled-image descriptor sets only when the batch state changes; shared pipeline layouts keep sampled bindings valid across pipeline switches. -
Reusable CPU instance packing. CPU instance and batch vectors are leased, cleared, and reused after uploads. Allocations above 16,384 retained items are discarded after the segment to bound warm storage. Recorded GPU work uses separate slot storage.
Source: crates/renderer/src/vulkan/scene/encode/scratch.rs:10; crates/renderer/src/vulkan/scene/encode/scratch.rs:19.
-
Geometric mapped-buffer growth. Per-slot instance and shader-table buffers retain mapped allocations and grow geometrically when necessary. Completed-slot ownership prevents overwrite while a prior submission still uses them.
Source: crates/renderer/src/vulkan/scene/buffer.rs:20; crates/renderer/src/vulkan/scene/renderer/resources.rs:147; crates/renderer/src/vulkan/scene/table.rs:31.
-
Shared default style and stable table bindings. Canonical default box styles share the seven-row record at offset zero. Storage-table descriptor writes are skipped when descriptor, buffer, binding, and range are unchanged. Paint bytes are still copied on nonempty repaints; this is storage/binding reuse, not a cache of table uploads.
Source: crates/renderer/src/vulkan/scene/shader_data/style.rs:61; crates/renderer/src/vulkan/scene/table.rs:61.
-
Scratch-image pooling. Compatible format/extent/usage/sample-count scratch images reuse Vulkan allocations after GPU completion. Idle cache counts and bytes are bounded separately from total allocated resources; actual allocation sizes are charged and prior access scopes survive recycling.
Source: crates/renderer/src/vulkan/graph/image_pool.rs:260; crates/renderer/src/vulkan/graph/image_pool.rs:400.
-
Transient reuse between repaint regions. Independent repaint sequences may reuse matching virtual transient images inside the same graph, reducing resource multiplication from split damage. Imported targets and preserved cache captures are excluded, and all hazards remain attached to the reused image identity.
Source: crates/renderer/src/vulkan/graph/render_graph.rs:264.
-
Sampled-descriptor reuse. Within one recording, identical pool/layout/sampler/image-view bindings share one sampled-image descriptor set. The lookup is cleared per recording so completed-slot pool resets cannot leave stale descriptor handles.
Source: crates/renderer/src/vulkan/graph/descriptors.rs:31; crates/renderer/src/vulkan/graph/render_graph.rs:427.
-
Persistent slot descriptor capacity. Scratch descriptor pools grow to accommodate the admitted pass count, then reset after the slot is safe instead of being recreated for every frame. Frame uniforms, tables, and instance buffers are also slot-owned.
Source: crates/renderer/src/vulkan/scene/renderer/resources.rs:472; crates/renderer/src/vulkan/scene/renderer/resources.rs:435.
-
Admission before expensive preparation. Graph pass, pixel, instance, and resource work is budgeted before glyph preparation and frame-buffer growth. Optional cache plans fall back first, then split-damage plans retry a bounding repaint. This bounds optimization overhead without rejecting a scene solely because an optional plan costs more.
Source: crates/renderer/src/vulkan/scene/renderer/admission.rs:124; crates/renderer/src/vulkan/graph/work.rs:5.
-
Dependency-based barriers. The graph derives synchronization from declared image uses and emits pre-barriers in a batch for each pass. Compatible read-only state can avoid a barrier when no prior write/layout transition requires one; same-layout writes still synchronize. This is conservative hazard tracking, not unconditional barrier removal.
Source: crates/renderer/src/vulkan/graph/hazards.rs:238; crates/renderer/src/vulkan/graph/render_graph.rs:446.
Glyph Rendering
-
Persistent atlas glyphs. Rasterized glyphs are cached by font, glyph, quantized size, and subpixel phase. Shelf packing reuses space in 1,024-by-1,024 atlases; coverage and color glyphs use their appropriate formats. Warm glyphs reuse pixels and descriptor bindings instead of rerasterizing and uploading.
Source: crates/renderer/src/vulkan/glyph.rs:64; crates/renderer/src/vulkan/glyph/atlas.rs:15; crates/renderer/src/vulkan/glyph/packing.rs:23.
-
Bounded subpixel and transform variants. Four horizontal raster phases bound subpixel cache growth. Positive uniform scaling uses a screen-resolution raster; other affine transforms select power-of-two density tiers based on maximum stretch, avoiding a new atlas size for every small animated transform change.
Source: crates/renderer/src/vulkan/glyph.rs:77; crates/renderer/src/vulkan/scene/planning/text.rs:15.
-
CPU metrics cache before rasterization. A bounded two-generation metrics cache lets scene bounds and damage planning reuse glyph measurements even when the glyph never reaches an atlas. Metrics preserve exact requested size rather than aliasing uncached outlines through the atlas’s size quantization.
Source: crates/renderer/src/vulkan/glyph/metrics.rs:11; crates/renderer/src/vulkan/glyph/metrics.rs:53.
-
Miss-only glyph preparation. The renderer scans surviving glyph requests, collects only misses, and avoids repeated font/size hashing for consecutive atlas groups. No-consumer frames return early. Required atlases are pinned even for hit-only frames, and uploads run before draw passes.
Source: crates/renderer/src/vulkan/glyph/preparation.rs:17; crates/renderer/src/vulkan/glyph/uploads.rs:15.
-
Raster scratch reuse. Outline and scan-conversion scratch capacity is retained across glyph misses, reducing allocation churn during new text rasterization.
-
Pressure eviction without invalidating active text. The glyph cache can evict unused completed atlas groups and retry preparation under its memory limits. Required groups and GPU-pinned atlases remain live; failed preparation rolls back additions rather than poisoning warm entries.
Source: crates/renderer/src/vulkan/glyph/eviction.rs:40; crates/renderer/src/vulkan/glyph/preparation.rs:87.
Image Transport and Presentation
-
Supported tiled scanout layouts. Explicit DRM modifier selection prefers the first allocator-supported non-linear layout over linear storage, retaining linear only when both the display plane and allocator advertise it. Format and modifier validation remain required before importing the storage into Vulkan.
Source: crates/renderer/src/display/selection/modifiers.rs:7.
-
Mapped CPU readback storage. The CPU-copy fallback keeps a mapped readback buffer on the image, prefers host-cached coherent memory for CPU reads, and exposes a borrowed byte view after successful completion instead of allocating a second pixel vector. It still performs the display copy.
Source: crates/renderer/src/vulkan/resources/readback.rs:18; crates/renderer/src/vulkan/resources/readback.rs:100.
-
DMA-BUF sampling. External DMA-BUF images are imported as Vulkan images and sampled by the server without staging their pixels through the CPU. Format/modifier compatibility and producer/consumer ownership transfers still apply. CPU-backed buffers retain their upload path.
Source: crates/renderer/src/vulkan/resources/external_images/import.rs:10; crates/renderer/src/vulkan/resources/external_images/mod.rs:667.
-
Zero-copy scanout storage. On compatible devices the runtime renders into imported scanout storage, avoiding GPU readback and a CPU copy into the display buffer. Automatic selection checks required device extensions; forced CPU-copy and zero-copy modes remain available. This is server-composed output, not client direct scanout.
Source: crates/renderer/src/present/selection.rs:39; crates/renderer/src/runtime/factory.rs:25.
-
Asynchronous GPU/display handoff. The zero-copy submission path exports synchronization for presentation, allowing supported KMS input fences to wait on the GPU without a synchronous CPU completion wait. Unsupported handoff and cursor-specific paths retain completion waits; zero-copy storage does not by itself imply asynchronous presentation.
Source: crates/renderer/src/vulkan/execution/submission.rs:20; crates/renderer/src/runtime/vulkan.rs:346.
-
Resource-specific completion waits. External-image replacement/release waits for the submissions that actually reference those buffer IDs, instead of indiscriminately waiting for all device work. Completed submissions retire nonblockingly with their graphs, uploads, and atlas pins.
Source: crates/renderer/src/vulkan/execution/state.rs:334; crates/renderer/src/vulkan/execution/state.rs:244.
-
Hardware cursor plane. When supported, the display presents a server-owned cursor through its dedicated plane and the Vulkan scene omits the software cursor. Cursor motion can be handled independently by its worker, with latest-position coalescing. Unsupported hardware uses the scene cursor.
Source: crates/renderer/src/runtime/vulkan.rs:274; crates/renderer/src/display/cursor/plane.rs:35; crates/renderer/src/display/cursor/worker.rs:160.
-
Optional cursor pacing.
HERA_CURSOR_PACING=1coalesces bursts onto refresh-paced cursor updates, skips stale slots after delays, and avoids filling KMS with obsolete motion. The pacing clock does not grant permission to reuse scanout storage.Source: crates/renderer/src/display/cursor/worker.rs:58; crates/renderer/src/display/cursor/pacing.rs:1.
October 16 Audit Follow-up
The subsequent release deployment also changes shell movement to one retained root-offset update, memoizes dock controls independently of window movement, and skips the producer-history comparison for draws without frame history. These CPU changes need no flag. Paired Pi measurements improve isolated CPU costs but do not establish a four-window FPS gain; see the deployment and planning results.
The renderer audit tracks measured results against revision 1f358406 for these additions:
-
Cursor-only frame suppression. The server samples confirmed hardware cursor ownership before frame admission. Active cursor motion does not invalidate the scene; hardware failure restores software invalidation at the next frame boundary even if the pointer has stopped. Client edits and animations still render. This is automatic when hardware promotion succeeds.
-
Exact clipped-texture specialization. Opt-in
HERA_CLIPPED_TEXTURE=1selects a smaller shader for unblurred sampled images and glyphs with exact clips. It uses the same nested rectangular, rounded, transformed, and path coverage function as the general shader. Gradients and blur at or above the existing 0.5 threshold keep the general pipeline. Unclipped draws retain their existing specialization. -
Single retained-damage comparison for ordinary draws. Producer frame-history availability is checked before attempting buffer-independent geometry/table comparison. Draws without history skip that extra comparison and use the ordinary comparison once. DMA-BUF damage-history traversal and conservative fallback remain intact. This is automatic, with no flag. Pi trials reduce isolated retained comparison time by about 47% and sparse-grid CPU scene recording from 1.377–1.391 ms to 1.297–1.304 ms. Live four-window FPS does not improve in the measured matrix; these are CPU-stage savings, not a 47% frame-time gain.
-
Experimental retained leaf draw plans.
HERA_DRAW_CACHE=1reuses CPU geometry, style records and gradient stops for unchanged non-group leaves. Keys include immutable node identity and exact inherited transform/clip state. Two matching visits are required before admitting products; entries are bounded to 4,096 and a 16 MiB accounting budget. Text stays on the existing path pending an atlas-metrics revision key. Group planning, damage, resource checks and GPU work remain per-frame. The switch defaults off; see the paired timing results and enablement recommendation.Source: leaf-plan cache.
Source: cursor synchronization, frame admission, clipped-texture shader, pipeline selection.
October 18 Scrolling Follow-up
The OnePlus scrolling work combines renderer savings with shared HeraKit and composer changes. The renderer still owns all drawing, damage decisions, and GPU resources. Client changes reduce the descriptions submitted to it; the scheduler changes when work starts. The Notes scrolling audit records the individual comparisons, rejected experiments, release hashes, and validation limits.
Raster Reuse and Planning Costs
-
Transform raster reuse with bounded admission. Eligible isolated, masked surface groups retain complete pixels across positive axis-aligned transforms. The current mask, clips, and opacity are applied at output resolution. Live buffers, destination-dependent effects, and unsupported transforms retain ordinary drawing. A history of at most four candidates delays another capture while content changes at a stationary root, as during typing or scrolling. Stable content or root motion can make capture worthwhile again; idle frames do not redraw just to populate a cache.
Source: raster eligibility and admission.
-
Shared raster proofs and early reuse. Raster plans retain immutable scene nodes and content through
Arc, avoiding deep copies of glyph payloads. Pointer identity proves unchanged nodes; changed allocations undergo structural comparison. WithHERA_RASTER_PLAN_CACHEenabled, proven retired raster content can replace subtree expansion before primitive planning. Content changes invalidate reuse, and GPU retirement remains required before cached pixels can be sampled.Source: shared content comparison, early raster reuse.
-
Transparent container rejection. A solid alpha-zero fill with no border, box style, shadow, filter, or blur is rejected before style allocation and downstream draw planning. Traversal still visits its children and preserves clipping and isolation.
Source: rectangle emission.
-
Batched damage identities. Adjacent glyphs sharing a node/subdraw/marker key need one occurrence-map lookup per run. Adjacent identities are checked directly before a full-index lookup, and reorder scans share the computed matches. Counts remain distinct across separated runs and repeated surface embeddings; unchanged topology avoids the match table.
-
Masked source-over interiors.
HERA_MASK_INTERIORuses a smaller sampling shader where coverage is proven to be one, preserving source-over blending. Curved and antialiased edges keep the general mask shader and original texture mapping. This is separate from the optional backdrop-replacement overwrite path.Source: composite pipeline selection.
Shared UI and Scheduling Work
HeraKit text fields retain complete editing and shaping state while emitting stable 16-line visual chunks that intersect the viewport. Selection and underline visuals are windowed too. Immutable text and style snapshots share storage across input handlers, avoiding whole-document copies during interaction. This bounds submitted visual work; it does not virtualize the full shaping layout, and very long unwrapped lines and bitmap/color-font documents retain conservative behavior. Notes also memoizes its stationary sidebar, toolbar, and title.
Source: text chunks, shared field content, HeraKit performance notes.
Opt-in HERA_UI_FRAME_PACING=1 coalesces view construction around submission acknowledgments. Input updates still apply in order, and CommitAccepted remains the retained-state baseline. Only the latest sent commit's CommitAck grants new construction; a 50 ms fallback prevents missing advisories from freezing dirty UI. This avoids building intermediate scenes that cannot become distinct presentations. Custom hosts driving dispatch/rendering retain their own scheduling.
Source: UI admission, host acknowledgment handling.
The composer reuses input topology after checking immutable snapshot/node identities and topology dependencies, while hit geometry continues to come from the current scene. Surface-coordinate traversal visits the required embedding ancestry instead of unrelated trees. Optional Linux utilization minima request CPU performance for the renderer and UI threads without changing affinity, governors, scheduling class, or resource ownership. They are deployment choices with potential power and thermal costs, not CPU reservations.
Source: prepared input cache, surface transforms, utilization hints.
The final scheduler correction addresses display counters that pause during idle. On the OnePlus, two presentation timestamps were 1.2335 seconds apart while the DRM sequence advanced only nine counts. Treating that interval as nine refresh periods incorrectly slowed the fixed clock. Feedback now refines the period only within ±25% of the configured rate; newer display phase is still accepted, and an explicit mode change resets the reference. This is automatic and has no device-specific branch.
Source: fixed-clock feedback.
Measured Device Results
Release Hera and Notes were measured on the OnePlus 8T / Adreno 650 at 1080×2400, 120 Hz, scale 2, with release Browser running behind Notes. The fixture contains 64 paragraphs / 1,920 words and 21 notes. Rates count distinct presented (CRTC, sequence) pairs inside the input helper's monotonic measurement window, excluding idle vblanks. All final captures have zero trace overruns and no per-frame logging, overlays, or validation layers.
| Workload | Before the fixed-clock correction | Final release | | --- | --- | --- | | Fresh six-second drag | 57.50–57.66 FPS, two runs | 61.66–63.33 FPS, three runs | | Inertia | 62.08–64.78 FPS, two runs | 62.95–63.94 FPS, three runs | | Subsequent six-second drags | — | 61.33–62.50 FPS, six runs |
The clock correction resolves the measured fresh-scroll throughput deficit; the inertia results do not establish a separate gain. Most p95 presentation intervals remain approximately 24.95 ms, so throughput above 60 FPS does not imply perfectly even cadence. The sustained captures cover 36 seconds of active dragging, not a long thermal or battery test. These results establish this workload's performance, not every application's frame rate or input latency.
The retained changes passed their focused unit, GPU fixture, and mount/commit integration checks. The final clock fix passed 141 composer and 34 server tests. The integration harness uses mockherad for RN mount/acknowledgment; actual display evidence comes from the device captures. The final screenshot differs from the prior reference at only 26 pixels by at most 1/255 per channel, with matching layout and content. The broader Vulkan suite still has five reproduced pre-existing failures and an unavailable headless DMA-BUF export case, detailed in the audit.
A general virtual-list experiment, eight-line text chunks, per-frame glyph-metrics promotion, and tested render-history changes were removed after failing to establish a repeatable benefit. A combined CPU/GPU history-expiry candidate was never deployed after tracing identified the clock defect. None is part of the retained optimization set.
Controls and Defaults
These switches are read when their owning renderer, scheduler, cursor worker, or UI runtime is initialized. Restart that owner when comparing settings. “Off” below means unset by default; setting an opt-in switch to 1 enables it, subject to the eligibility rules above.
HERA_DRAW_CACHE: off; bounded CPU leaf-plan reuse, keyed by immutable node identity and exact inherited transform/clip state. See the retained leaf planning results.HERA_RUN_CACHE: on unless0; opaque suffix pixel reuse.HERA_TRANSFORM_CACHE: on unless0; eligible isolated surface raster reuse, with bounded capture admission.HERA_RASTER_PLAN_CACHE: on unless0; prove retired raster reuse before subtree draw expansion; requires transform caching and ordinary group-damage eligibility.HERA_MASK_INTERIOR: on unless0; specialized source-over sampling inside proven full-coverage mask regions.HERA_FILTER_CACHE: off; complete content-blur image reuse.HERA_DAMAGE_REGIONS: off; separate damage rectangles. Ordinary bounding damage tracking remains automatic.HERA_BLUR_REGIONS: on unless0; bounded filter writes.HERA_BORDER_CULL: on unless0; transparent border-center scissors.HERA_PARTIAL_OCCLUSION: off; opaque-core partitioning, partial hidden-region scissors, and reduced backdrop initialization copies.HERA_COMPOSITE_OVERWRITE: off; one-pass overwrite inside eligible backdrop mask interiors.HERA_MASK_COPY: off; minimal shader for the overwrite interior. It needs the composite-overwrite path to have a qualifying interior.HERA_SHADOW_SPECIALIZE: off; eligible shadow-only shader selection.HERA_CLIPPED_TEXTURE: off; exact-coverage specialization for eligible clipped images and glyphs (October 16 follow-up).HERA_MERGE_COLOR_PASSES: off; compatible pairwise color-pass fusion.HERA_BACKDROP_DOWNSAMPLE: 1; only2and4select reduced backdrop targets. Other values fall back to native resolution.HERA_CURSOR_PACING: off; refresh-paced cursor updates.HERA_RENDER_AHEAD: off;heradselects triple buffering for render-ahead acquisition.HERA_PRECISE_TIMER: off; nonblocking Linux timerfd deadlines, with Tokio fallback.HERA_PRESENT_MODE: auto;cpuforces CPU-copy presentation,zerorequests zero-copy with capability validation.HERA_RENDER_MARGIN_US: 3,000 microseconds by default; accepted overrides are 250 through 10,000 microseconds.HERA_RENDER_UTIL_MINandHERA_UI_UTIL_MIN: unset; preserve inherited CPU policy. Optional Linux per-thread minima accept 0 through 1024; zero removes the minimum. Unsupported or restricted requests retain normal execution and report the failure.HERA_UI_FRAME_PACING: off; submission-paced view construction in the standard HeraKit UI runtime, with a 50 ms fallback for dirty work.
Defaults: crates/renderer/src/vulkan/scene/renderer/resources.rs:43; crates/renderer/src/display/cursor/worker.rs:58; crates/renderer/src/present/selection.rs:16; crates/composer/src/scheduler.rs:87.
OnePlus Scrolling Test Configuration
The October 18 release measurements used the settings below in the environment inherited by Hera and its apps. CPU and GPU governors remained automatic. The utilization minima are the measured device configuration, not global defaults or a recommendation for every device.
export HERA_SCALE=2
export HERA_SHELL_MODE=touch
export HERA_TRANSFORM_CACHE=1
export HERA_RASTER_PLAN_CACHE=1
export HERA_RUN_CACHE=1
export HERA_BLUR_REGIONS=1
export HERA_BORDER_CULL=1
export HERA_MASK_INTERIOR=1
export HERA_PRECISE_TIMER=1
export HERA_RENDER_UTIL_MIN=1024
export HERA_UI_UTIL_MIN=512
export HERA_UI_FRAME_PACING=1The fixed-clock correction, transparent-fill rejection, shared raster proofs, batched damage matching, and input-topology reuse need no additional switch. Keep profiling overlays and per-frame diagnostics disabled when reproducing the throughput measurements.
Pi Release Test Configuration
The October 15 review configuration enables the boolean optimizations reviewed on October 15, including the shadow-only shader. These are runtime environment settings for the release executable; they do not require Cargo features or change the global defaults. Export them before launching the server or its session launcher:
export HERA_RUN_CACHE=1
export HERA_FILTER_CACHE=1
export HERA_DAMAGE_REGIONS=1
export HERA_BLUR_REGIONS=1
export HERA_BORDER_CULL=1
export HERA_PARTIAL_OCCLUSION=1
export HERA_COMPOSITE_OVERWRITE=1
export HERA_MASK_COPY=1
export HERA_SHADOW_SPECIALIZE=1
export HERA_MERGE_COLOR_PASSES=1
export HERA_CURSOR_PACING=1
export HERA_RENDER_AHEAD=1
export HERA_PRECISE_TIMER=1
export HERA_BACKDROP_DOWNSAMPLE=4
export HERA_PRESENT_MODE=auto
export HERA_PROFILE_OVERLAY=0
export HERA_DAMAGE_OVERLAY=0
export HERA_AUDIT_GPU_PASSES=0The 4× backdrop setting is the existing Pi review setting and deliberately trades filter quality for speed; use HERA_BACKDROP_DOWNSAMPLE=1 for native-resolution blur comparisons. Automatic presentation retains hardware capability checks and selects zero-copy when supported. The scheduler keeps its normal render margin; reducing that margin is a latency experiment, not an additional rendering optimization. Render-ahead is explicitly enabled through triple buffering, and precise render deadlines use the Linux timerfd path where available. Ordinary scene culling is automatic. CPU blur currently exists as a comparison benchmark, not a production mode to enable alongside GPU blur. Profiling and damage overlays stay off for visual review.
Correctness and Verification
Optimizations must preserve source pixels needed by filters, exact paint order, antialiased edges, and the distinction between GPU completion and scanout release. Retained pixels become reusable after retirement; damage history is accepted only when submission succeeds. The ordinary rendering path remains the fallback when a proof or optional plan is unavailable.
The checkout contains focused planning, command-recording, and GPU image regressions. These provide useful starting points when changing the optimizations:
- Damage, group visibility, and content identity: crates/renderer/src/vulkan/scene/renderer/tests.rs:288.
- Repaint image equivalence: crates/renderer/src/vulkan/tests/tests_damage.rs:89.
- Occlusion and repaint interaction: crates/renderer/src/vulkan/tests/tests_occlusion_damage.rs:90.
- Filtered cache reuse: crates/renderer/src/vulkan/tests/filtered_cache.rs:188.
- Specialized plain pipelines: crates/renderer/src/vulkan/tests/plain_solids.rs:4.
- Command-state suppression: crates/renderer/src/vulkan/scene/encode/command_tests.rs:109.
- Color-pass fusion eligibility: crates/renderer/src/vulkan/graph/fusion.rs:181.
- Scratch reuse and allocation limits: crates/renderer/src/vulkan/graph/image_pool/tests.rs:49.
- Glyph preparation and lifetime: crates/renderer/src/vulkan/glyph/tests.rs:254.
Use Performance and Profiling for measurement workflows and Verification for the repository’s test procedures. Compare both image output and work counters when changing a switch; a smaller pass count alone does not establish a faster frame. Changes to rendering or timing require the repository’s integration verification.
Source Reference
The per-entry links above identify implementing lines. The main ownership and configuration files are listed here for navigation and documentation source checks. Recheck line references and switch defaults whenever these implementations move; the linked function names and descriptions are the durable context.
crates/renderer/src/vulkan/scene/renderer.rscrates/renderer/src/vulkan/scene/renderer/resources.rscrates/renderer/src/vulkan/scene/planning/damage.rscrates/renderer/src/vulkan/scene/planning/groups.rscrates/renderer/src/vulkan/scene/encode.rscrates/renderer/src/vulkan/graph/render_graph.rscrates/renderer/src/vulkan/glyph.rscrates/renderer/src/runtime/vulkan.rscrates/composer/src/composer.rscrates/composer/src/scheduler.rsapps/herad/src/config.rscrates/server/src/frame/timer.rscrates/renderer/src/vulkan/scene/renderer/transformed_groups.rscrates/renderer/src/vulkan/scene/renderer/transformed_groups/reuse.rscrates/renderer/src/vulkan/scene/planning/draw/rectangle.rscrates/composer/src/input/prepared.rscrates/composer/src/input/transforms.rscrates/kit/src/text/field/visual.rscrates/kit/src/text/field/mod.rscrates/kit/src/threading/pacing.rscrates/kit/src/host/mod.rscrates/platform/src/scheduling.rsapps/notes/SCROLL_PERFORMANCE.md
Related guides: Render Graph, Damage and Occlusion, Presentation, and Text and Fonts.