frust_engine/
lib.rs

1//! Layer 4: Frust Engine — the sparse-strip GPU render pipeline.
2//!
3//! `frust-engine` turns a `frust_scene::Scene` into recorded GPU work. One
4//! [`EngineRenderer`] drives one surface: it compiles the display list into
5//! sparse strips ([`compile`]), packs them into the layouts the WGSL reads
6//! ([`gpu`]), and records the frame's passes into a [`EngineTarget`] through a
7//! command encoder the *caller* owns and submits. Every rendering path returns
8//! an [`EngineError`] rather than panicking (E17).
9//!
10//! The crate splits along one line throughout: pure decisions over plain
11//! values on one side (sizing, packing, addressing, pool keying — all
12//! host-testable with no GPU), and a small number of named entry points that
13//! touch a live `wgpu::Device` on the other. [`renderer`] is where the two
14//! meet.
15//!
16//! Configuration is process-global and cached, selected from environment
17//! variables read at compile time (`option_env!`) or run time
18//! (`std::env::var`); see [`config`] for the kill switches over layers, atlas,
19//! pooling, depth and resource limits. `FRUST_ENGINE_NO_ATLAS` and
20//! `FRUST_ENGINE_ATLAS_SIZE` are consulted by [`cache::images`]: the first
21//! makes every image draw a logged skip, the second overrides the atlas extent
22//! the adapter's tier would otherwise choose, and
23//! `FRUST_ENGINE_NO_SHADER_EFFECTS` turns off [`effects::shader_quad`]'s user
24//! fragment programs. `FRUST_ENGINE_NO_LAYERS` turns off [`cache::retained`]'s
25//! retained pages and `FRUST_ENGINE_RETAINED_BUDGET_MB` overrides their budget.
26
27pub mod cache;
28pub mod compile;
29pub mod config;
30pub mod diag;
31pub mod effects;
32pub mod error;
33pub mod filters;
34pub mod gpu;
35pub mod renderer;
36pub mod schedule;
37pub(crate) mod text;
38
39pub use cache::{
40    AtlasBudget, AtlasRegion, CachedRamp, GradientCache, GradientTextureLayout, ImageResidency,
41    ImageSkip, ImageUpload, ResidentImage, RetainedBudget, RetainedEntry, RetainedPages,
42};
43pub use compile::blur_rrect::{encode_blurred_rounded_rect, inflated_bounds};
44pub use compile::paint::{
45    BrushEncoding, ImageEncoding, LutRequest, encode_brush, encode_image, encode_image_brush,
46    encode_image_command,
47};
48pub use compile::{
49    CompiledFrame, DepthCounter, EngineDraw, RetainedBracket, RetainedKind, RetainedPlacement,
50    SceneCompiler,
51};
52pub use diag::{EngineSpan, FrameTimestamps};
53pub use effects::ShaderQuadPass;
54pub use error::EngineError;
55pub use gpu::{
56    ATLAS_FORMAT, AtlasArray, DepthAttachment, DepthTexture, EnginePipeline, EngineShaderModule,
57    EngineShaders, GpuConfig, GpuEncodedPaint, GpuStrip, IntermediateTargets, IntermediateTexture,
58    StripDraw, lower_encoded_image,
59};
60pub use renderer::EngineRenderer;
61pub use schedule::{
62    Composite, PageParity, PageTarget, RetainedLayers, RetainedRole, RetainedSource,
63    RetainedTarget, Round, RoundOp, RoundTarget, Schedule,
64};
65
66/// Alpha output mode for the render target.
67#[derive(Debug, Clone, Copy, PartialEq, Eq)]
68pub enum OutputAlpha {
69    /// Premultiplied alpha (color already multiplied by alpha).
70    Premultiplied,
71    /// Straight (unpremultiplied) alpha.
72    Straight,
73}
74
75/// Render target descriptor passed to [`EngineRenderer::encode`].
76///
77/// Describes one frame's destination: the view to draw into, the format and
78/// extent that view was created with, and how the result's alpha is to be
79/// interpreted.
80///
81/// `depth` is the caller's own depth attachment, for a host that already ran a
82/// 3D pass into the same colour target and wants the 2D pass to test against
83/// the depth that pass established. Leaving it `None` lets the engine own a
84/// depth attachment of its own; either way, pair it with
85/// [`EngineRenderer::set_depth_pre_cleared`] so the frame loads a populated
86/// buffer instead of clearing it.
87#[derive(Debug)]
88pub struct EngineTarget<'a> {
89    /// The destination texture view to render into.
90    pub view: &'a wgpu::TextureView,
91    /// The texture format of the target (must match the view).
92    pub format: wgpu::TextureFormat,
93    /// Width in pixels.
94    pub width: u32,
95    /// Height in pixels.
96    pub height: u32,
97    /// Optional depth texture view for depth operations.
98    pub depth: Option<&'a wgpu::TextureView>,
99    /// Alpha output mode.
100    pub output: OutputAlpha,
101}
102
103/// Engine-wide render settings and configuration.
104///
105/// Collects render options such as quality, feature toggles, and resource constraints.
106pub struct EngineSettings {
107    // Settings to be defined as phases progress
108}
frust_engine/lib.rs

frust_engine/
lib.rs
