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 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.