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.
25
26pub mod cache;
27pub mod compile;
28pub mod config;
29pub mod diag;
30pub mod effects;
31pub mod error;
32pub mod filters;
33pub mod gpu;
34pub mod renderer;
35pub mod schedule;
36pub(crate) mod text;
37
38pub use cache::{
39    AtlasBudget, AtlasRegion, CachedRamp, GradientCache, GradientTextureLayout, ImageResidency,
40    ImageSkip, ImageUpload, ResidentImage,
41};
42pub use compile::blur_rrect::{encode_blurred_rounded_rect, inflated_bounds};
43pub use compile::paint::{
44    BrushEncoding, ImageEncoding, LutRequest, encode_brush, encode_image, encode_image_brush,
45    encode_image_command,
46};
47pub use compile::{CompiledFrame, DepthCounter, EngineDraw, SceneCompiler};
48pub use diag::{EngineSpan, FrameTimestamps};
49pub use effects::ShaderQuadPass;
50pub use error::EngineError;
51pub use gpu::{
52    ATLAS_FORMAT, AtlasArray, DepthAttachment, DepthTexture, EnginePipeline, EngineShaderModule,
53    EngineShaders, GpuConfig, GpuEncodedPaint, GpuStrip, IntermediateTargets, IntermediateTexture,
54    StripDraw, lower_encoded_image,
55};
56pub use renderer::EngineRenderer;
57pub use schedule::{Composite, PageParity, PageTarget, Round, RoundOp, RoundTarget, Schedule};
58
59/// Alpha output mode for the render target.
60#[derive(Debug, Clone, Copy, PartialEq, Eq)]
61pub enum OutputAlpha {
62    /// Premultiplied alpha (color already multiplied by alpha).
63    Premultiplied,
64    /// Straight (unpremultiplied) alpha.
65    Straight,
66}
67
68/// Render target descriptor passed to [`EngineRenderer::encode`].
69///
70/// Describes one frame's destination: the view to draw into, the format and
71/// extent that view was created with, and how the result's alpha is to be
72/// interpreted.
73///
74/// `depth` is the caller's own depth attachment, for a host that already ran a
75/// 3D pass into the same colour target and wants the 2D pass to test against
76/// the depth that pass established. Leaving it `None` lets the engine own a
77/// depth attachment of its own; either way, pair it with
78/// [`EngineRenderer::set_depth_pre_cleared`] so the frame loads a populated
79/// buffer instead of clearing it.
80#[derive(Debug)]
81pub struct EngineTarget<'a> {
82    /// The destination texture view to render into.
83    pub view: &'a wgpu::TextureView,
84    /// The texture format of the target (must match the view).
85    pub format: wgpu::TextureFormat,
86    /// Width in pixels.
87    pub width: u32,
88    /// Height in pixels.
89    pub height: u32,
90    /// Optional depth texture view for depth operations.
91    pub depth: Option<&'a wgpu::TextureView>,
92    /// Alpha output mode.
93    pub output: OutputAlpha,
94}
95
96/// Engine-wide render settings and configuration.
97///
98/// Collects render options such as quality, feature toggles, and resource constraints.
99pub struct EngineSettings {
100    // Settings to be defined as phases progress
101}
frust_engine/lib.rs

frust_engine/
lib.rs
