Documentation menu

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

Scene Planning and Visibility

Damage and Repaint Reduction

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

Effects and Shader Specialization

Batching and Resource Reuse

Glyph Rendering

Image Transport and Presentation

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=1 selects 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.

    Source: retained damage comparison; timings and validation.

  • Experimental retained leaf draw plans. HERA_DRAW_CACHE=1 reuses 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. With HERA_RASTER_PLAN_CACHE enabled, 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.

    Source: damage identity construction and matching.

  • Masked source-over interiors. HERA_MASK_INTERIOR uses 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 unless 0; opaque suffix pixel reuse.
  • HERA_TRANSFORM_CACHE: on unless 0; eligible isolated surface raster reuse, with bounded capture admission.
  • HERA_RASTER_PLAN_CACHE: on unless 0; prove retired raster reuse before subtree draw expansion; requires transform caching and ordinary group-damage eligibility.
  • HERA_MASK_INTERIOR: on unless 0; 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 unless 0; bounded filter writes.
  • HERA_BORDER_CULL: on unless 0; 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; only 2 and 4 select reduced backdrop targets. Other values fall back to native resolution.
  • HERA_CURSOR_PACING: off; refresh-paced cursor updates.
  • HERA_RENDER_AHEAD: off; herad selects triple buffering for render-ahead acquisition.
  • HERA_PRECISE_TIMER: off; nonblocking Linux timerfd deadlines, with Tokio fallback.
  • HERA_PRESENT_MODE: auto; cpu forces CPU-copy presentation, zero requests 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_MIN and HERA_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=1

The 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=0

The 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:

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.rs
  • crates/renderer/src/vulkan/scene/renderer/resources.rs
  • crates/renderer/src/vulkan/scene/planning/damage.rs
  • crates/renderer/src/vulkan/scene/planning/groups.rs
  • crates/renderer/src/vulkan/scene/encode.rs
  • crates/renderer/src/vulkan/graph/render_graph.rs
  • crates/renderer/src/vulkan/glyph.rs
  • crates/renderer/src/runtime/vulkan.rs
  • crates/composer/src/composer.rs
  • crates/composer/src/scheduler.rs
  • apps/herad/src/config.rs
  • crates/server/src/frame/timer.rs
  • crates/renderer/src/vulkan/scene/renderer/transformed_groups.rs
  • crates/renderer/src/vulkan/scene/renderer/transformed_groups/reuse.rs
  • crates/renderer/src/vulkan/scene/planning/draw/rectangle.rs
  • crates/composer/src/input/prepared.rs
  • crates/composer/src/input/transforms.rs
  • crates/kit/src/text/field/visual.rs
  • crates/kit/src/text/field/mod.rs
  • crates/kit/src/threading/pacing.rs
  • crates/kit/src/host/mod.rs
  • crates/platform/src/scheduling.rs
  • apps/notes/SCROLL_PERFORMANCE.md

Related guides: Render Graph, Damage and Occlusion, Presentation, and Text and Fonts.