Struct SceneCompiler 

pub struct SceneCompiler { /* private fields */ }

Compiles a frust_scene::Scene into strips and draws.

Create one per surface and reuse it across frames — the retained StripGenerator is the point.

Implementations

impl SceneCompiler

pub fn new(width: u16, height: u16) -> Self

A compiler sized for a width x height viewport.

The size is re-asserted on every compile call, so this is only the initial allocation hint; pass the surface’s current size to avoid an immediate resize.

Image residency starts on AtlasBudget::MOBILE, the smaller of the two tiers. A compiler built without an adapter in hand knows nothing about the device it will end up on, and over-budgeting a phone costs real memory while under-budgeting a desktop costs only an extra atlas layer — call for_caps or set_atlas_budget once the adapter is known.

pub fn for_caps(width: u16, height: u16, caps: &TierCaps) -> Self

A compiler sized for a width x height viewport, with image residency budgeted for caps’ adapter and glyph hinting decided by caps’ device class.

Hinting is turned on for a desktop-class adapter and left off for a mobile one — the same !is_mobile_tier split AtlasBudget::for_caps draws its own tier from, so a caller with an adapter in hand only ever answers the mobile-or-desktop question once. See [crate::text]’s module doc for why hinting defaults off and what the other half of the policy — the transform predicate glifo applies on top of this — is not this crate’s to make.

pub fn set_hint_text(&mut self, hint_text: bool)

Set whether a glyph run’s outline is hinted before it is rasterized, bypassing Self::for_caps’ TierCaps reading.

For a test that wants a chosen answer without building a TierCaps — Self::new and Self::with_atlas_budget already default to the mobile-safe false, so this is also how a caller that built one of those turns hinting on.

pub fn set_glyph_quads(&mut self, enabled: bool)

Set whether a glyph run resolved entirely out of the glyph atlas is drawn as glyph quads — one rect instance per glyph, one record per run and atlas layer — or the general way, one image record and one generated rectangle per glyph (see [crate::text]).

The per-compiler counterpart of FRUST_ENGINE_NO_GLYPH_QUADS, which only sets the value a compiler starts with: a caller comparing the two lowerings in one process sets it here rather than through a process-global environment variable. Takes effect from the next run.

pub fn glyph_quads_enabled(&self) -> bool

Whether resident glyph runs are drawn as glyph quads.

pub fn set_glyph_run_cache(&mut self, enabled: bool)

Set whether a glyph run drawn as glyph quads may be drawn out of the resident-run cache — its glyphs’ slots remembered from an earlier frame — instead of being resolved glyph by glyph through glifo (see [crate::text::ResidentPlan]).

The per-compiler counterpart of FRUST_ENGINE_NO_GLYPH_RUN_CACHE, on the same terms as Self::set_glyph_quads: the variable sets the value a compiler starts with, this decides it for one compiler. Takes effect from the next run. The cache only ever serves quads, so turning quads off turns it off too.

pub fn glyph_run_cache_enabled(&self) -> bool

Whether glyph runs may be drawn out of the resident-run cache.

pub fn set_retained_layers(&mut self, enabled: bool)

Set whether retained brackets are recorded for a retained-page store.

Off by default: a compiler built on its own has no store behind it, so it lowers every PushRetained inline exactly as frust_scene tells a renderer that does not retain to, and refuses a DrawRetained with EngineError::RetainedKeyMissing. The renderer turns it on for the compiler it owns (unless FRUST_ENGINE_NO_LAYERS is set): each outermost bracket’s body then becomes a recorded layer whatever its alpha and is listed in CompiledFrame::retained, and a DrawRetained becomes an empty layer at its painter-order position (see layers). Takes effect from the next frame.

pub fn retained_layers_enabled(&self) -> bool

Whether retained brackets are recorded for a retained-page store.

pub fn resident_glyph_run_count(&self) -> usize

How many glyph runs the resident-run cache currently remembers.

Bounded by MAX_RESIDENT_GLYPH_RUNS records (and a byte budget beside it), however many distinct runs have been drawn.

pub fn set_parallel_workers(&mut self, workers: usize)

Set how many threads generate a frame’s strips, the calling thread included (see the parallel module). One — or zero, read as one — is the sequential walk: no planning pass, no helper thread.

The per-compiler counterpart of FRUST_ENGINE_NO_PARALLEL, on the same terms as Self::set_glyph_quads: the variable sets the value a compiler starts with (DEFAULT_PARALLEL_WORKERS capped by the machine, or one with it set), this decides it for one compiler. Takes effect from the next frame. The frame a compiler produces is the same at every setting. Capped at MAX_PARALLEL_WORKERS — every helper is a thread spawned per frame and a strip generator kept across them, so a count far past any machine would only pay for threads that cannot run; the variable’s path is capped by the machine’s own thread count instead, so that a test can ask for the helper count it means to exercise on any host.

pub fn parallel_workers(&self) -> usize

How many threads generate a frame’s strips, the calling thread included.

pub fn set_parallel_min_cost(&mut self, cost: u64)

Set the estimated cost a frame’s planned helper work must reach before a helper is spawned for it (see DEFAULT_PARALLEL_MIN_COST for the unit). Zero spawns for any frame with a single planned command, which is how a test drives the helpers over a scene too small to earn them.

pub fn parallel_min_cost(&self) -> u64

The estimated cost a frame’s planned work must reach before a helper is spawned.

pub fn with_atlas_budget(width: u16, height: u16, budget: AtlasBudget) -> Self

A compiler sized for a width x height viewport, with image residency budgeted explicitly.

pub fn bind_external_texture(&mut self, id: u64, size: (u32, u32)) -> bool

Records an externally owned texture as bound under id at size texels, answering whether the extent is one a paint can be composed against at all (see ExternalExtents::bind).

Only the extent: the view the frame’s passes sample is the renderer’s (see crate::gpu::bindings). A caller that registers one half without the other gets a texture that draws nothing, which is why the renderer’s own bind_texture writes both.

pub fn unbind_external_texture(&mut self, id: u64)

Forgets the extent recorded for id, so a SceneTexture naming it draws nothing again.

pub fn externals(&self) -> &ExternalExtents

The externally bound extents this compiler resolves against.

pub fn glyph_atlas_mut(&mut self) -> &mut GlyphAtlas

The glyph entry map, for the caller that has to drain the pages this compiler’s last frame dirtied.

The engine produces no glyph pixels itself: glifo records the fills that rasterize a newly cached glyph into a per-page recorder, and crate::gpu::atlas::AtlasRenderer::render_pending replays them into the atlas array before the frame’s scene pass. That replay needs the map itself, which is what this hands over.

pub fn glyph_atlas_entries(&self) -> usize

How many glyphs this compiler currently holds resident in the atlas.

Observational, and the counter the policy’s whole claim rests on: a page of static text reaches a fixed number here and stays there, while an animating size never contributes at all.

pub fn glyph_atlas_enabled(&self) -> bool

Whether any glyph may be cached at all — false under FRUST_ENGINE_NO_ATLAS.

pub fn images(&self) -> &ImageResidency

The images this compiler currently holds resident.

pub fn acknowledge_image_plan(&mut self)

Record that a compiled frame’s image_evictions and image_uploads have been serviced against a live atlas array.

The other half of the plan seam: compile reports the plan without consuming it, and it goes on being reported — identically, never duplicated — until this is called. Call it only once the regions have really been written, so a frame refused after compiling keeps its uploads for the next frame that is not (see crate::cache::images’s module doc).

pub fn glyph_replay_pending(&self) -> bool

Whether glifo still holds recorded page commands, bitmap uploads or freed rectangles that have not reached the atlas array.

The gate a caller drives crate::gpu::atlas::AtlasRenderer::render_pending from. Deliberately not CompiledFrame::atlas_glyph_draws: glifo dirties a page when it inserts an entry, not when a draw survives, so a run scrolled behind a clip inserts entries and records fills while contributing no draw at all. Gating on draws leaves those commands recorded — and a recorded command outliving the slot it names is old ink replayed into whichever glyph was let that rectangle next.

Stays true across a frame the caller refuses, exactly as the image plan does, until acknowledge_glyph_replay.

pub fn acknowledge_glyph_replay(&mut self)

Record that the recorded page commands were replayed into the atlas array.

Also what lets glifo’s eviction pass resume: while a replay is outstanding the policy defers ageing, so that no rectangle a recorded command still names can be freed and re-let underneath it (see [crate::text::atlas_policy]).

pub fn glyph_clears_pending(&self) -> bool

Whether any rectangle freed by glyph eviction is still waiting to be zeroed.

pub fn acknowledge_glyph_clears(&mut self)

Record that this frame’s CompiledFrame::glyph_clears were written to the atlas array.

The glyph half of the same re-offer contract acknowledge_image_plan closes for images: compile reports the clears without consuming them, and goes on reporting the same ones, until a caller that really issued the writes says so. A frame compiled and then dropped therefore leaves no rectangle holding an evicted glyph’s pixels.

pub fn set_atlas_budget(&mut self, budget: AtlasBudget)

Re-budget image residency, dropping every image currently resident.

The atlas geometry is what an allocation’s coordinates mean, so a change to it invalidates every rectangle already handed out: residency starts over and each image re-uploads on the next frame that draws it. A caller that owns the atlas texture must recreate it at the new extent in the same step — this is an adapter-change or start-up operation, never a per-frame one.

pub fn set_image_residency(&mut self, images: ImageResidency)

Replace this compiler’s image residency wholesale, dropping every image currently resident.

The same invalidation set_atlas_budget carries, exposed for the residencies a budget alone cannot express — a deliberately disabled one, or one a caller built against an adapter’s own capabilities.

The glyph policy is rebuilt alongside it, and for the same reason: its slots came out of the allocator being replaced, so every one of them names a rectangle of a geometry that no longer exists. Text re-caches on the next frame that draws it, exactly as an image re-uploads.

pub fn compile( &mut self, scene: &Scene, root: Affine, size: (u16, u16), ) -> Result<CompiledFrame, EngineError>

Compile scene for a size viewport, with root applied ahead of every command’s own transform.

Errors

EngineError::TargetTooLarge when size cannot be rounded up to whole tiles inside u16; EngineError::InvalidTransform when a composed transform is non-finite and so maps geometry to coordinates no u16 pixel can hold; and EngineError::InvalidGeometry when a command the compiler lowers carries non-finite geometry of its own (see [check_geometry]). All three are refused before any strip is generated — the frame path returns errors and never panics.

Trait Implementations

impl Debug for SceneCompiler

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.