Skip to main content

Crate sim_engine

Crate sim_engine 

Source
Expand description

§Sim;Engine

Sim;Engine is a validated visualization library built for simulation products. It provides a high-performance 2D renderer, scientific visualization paths, and a focused retained 3D stereometry pipeline.

Sim;X is the primary consumer and design driver, but the crate is reusable. Applications provide ready visual state. Sim;Engine owns cameras, drawing, clipping, interpolation, GPU resources, composition, recovery, and rendering diagnostics. Physics, simulation stepping, domain entities, UI navigation, and plugins remain in the host application.

This is Sim;Engine 0.4.2, focused on dense 2D mathematical visualization. See the 0.4.2 changelog. The crate remains pre-1.0, and its supported release target is Linux with Vulkan. A concrete adapter/driver is supported when the mandatory semantic fixture passes on it; untested drivers are not inferred from Mesa evidence. The minimum supported Rust version is 1.90.

The software-Vulkan CI fixture uses Mesa 25.3+ lavapipe. Mesa 25.2.8 llvmpipe has a reproduced MSAA scissor leak and does not pass the rendering contract; its upstream fix is included in Mesa 25.3. This does not impose an Ubuntu-version requirement on host applications.

The 0.4 API includes Opaque/Mask/Blend 3D materials, sidedness, vertex colors, optional Lambert lighting and distance fog, capacity-reusing mesh updates, mipmapped and repeating textures, atomic region edits, and complete material recovery. CPU-only fonts and reusable pre-shaped text reduce repeated text work; optional GPU timestamps and changing-scene fixtures make costs observable. See the 0.4 integration guide and 0.4.0 changelog for contracts and migration notes from 0.3.0.

Version 0.4.2 adds compact retained circles, independent round lines and axis-aligned rectangles, plus ordered same-atlas batches of prepared labels. They reuse capacity, support explicit clipping/DPI and device recovery, and keep numeric checks and resource budgets. Preparation substages and selected adapter metadata make remaining CPU/GPU costs visible. These paths are opt-in: an application must retain and submit batches; upgrading alone does not convert its existing streaming geometry. See the dense 2D guide.

The 0.4.1 performance guide covers earlier partial mip uploads, retained-3D validation, instancing, changed-uniform uploads and optional culling. Existing 0.4 integrations need no source migration. No universal frame rate or replacement for consumer testing is promised.

§Documentation

  • Library documentation - installation, concepts, every rendering path, recovery, performance, architecture, and examples.

  • Changelog - release history and migration notes.

  • Archived 0.3 documentation - the guide for integrations that have not upgraded.

  • Generated API reference:

    cargo doc --all-features --no-deps --open

§Capabilities

  • validated circles, rectangles, rounded rectangles, lines, and polylines, including sub-ULP radii, rounded corners, and world-width strokes preserved as camera-relative local offsets;
  • solid, linear-gradient, and radial-gradient fills;
  • logical/world-width strokes with bounded caps, joins, dashes, markers, clipping, and stable layer ordering;
  • 2D camera pan, rotation, zoom, fit, and picking;
  • fallible tweening and easing;
  • streaming, prepared, and dynamic triangle geometry;
  • compact retained screen circles, independent round lines and rectangles;
  • retained sRGB RGBA images, atlas sprite batches, and world-space image quads;
  • host-shaped, bounded glyph atlas runs with deterministic logical bounds;
  • many-placement glyph batches with independent translations, tints and clips;
  • optional CPU-only fonts feature for TTF/OTF loading, shaping and rasterization; text adds GPU atlases, retained runs and preparation from pre-shaped lines;
  • budgeted instanced particle rendering;
  • scalar-field textures, color maps, partial updates, and heatmaps;
  • offscreen targets, composition, and bounded trails;
  • device recovery with explicit retained-resource restoration;
  • typed logical-pixel, 2D/3D world-length, and target-scale boundaries;
  • retained 3D meshes, independent transforms, hardware depth, and visible or dashed hidden mathematical edges;
  • explicit StrictPortable/Native surface policies and source-triangle diagnostics;
  • capacity-reusing, alias-isolated mesh edits and material-only rebinding;
  • Opaque/Mask/Blend surfaces, sidedness, vertex colors, optional normals, ambient/directional Lambert lighting and distance fog;
  • complete mip chains, isolated repeating tiles and bounded texture-region edits;
  • atomic retained-3D scene recovery that preserves stable object IDs and visual state across logical-device replacement;
  • optional bounded GPU pass timestamps with correlation IDs and loss counters;
  • primitive/source-grouped diagnostics and repeatable release-mode workloads for static UI, prepared/streaming UI, viewports, atlases, glyphs, mixed layers, budget rejection, DPI reconfiguration, real compositor scale transitions, and recovery.

Ordinary scenes support explicit construction, tessellation, and upload budgets, fixed logical-screen geometry, and independent positioned viewport or offscreen-target rendering. FrameComposer orders streaming and prepared scenes, compact primitives, dynamic meshes, particles, scalar fields, images, glyph runs/batches, and 2D/3D color targets under one frame budget and one surface presentation. DynamicMeshBudget limits caller-provided filled triangles and makes full updates allocation-fallible and atomic.

GPU transform validation enforces bounded arithmetic for 2D scenes, dynamic triangles, particles, and retained 3D. Nonzero subnormal coordinate/transform operands, coordinate magnitudes above 2^120, ambiguous geometry-branch thresholds, and arithmetic ranges that cannot be proven portable are rejected with a structured transform error before submission. Normalized linear color channels are not geometric operands and may include subnormal values; their contribution is below the precision of current normalized render targets. This intentionally prefers a clear rejection over backend-dependent geometry disappearance or topology. Retained 3D defaults to StrictPortable, which also proves clipping topology and rejects ambiguous surface classifications. Opt-in Native uses hardware surface clipping while retaining arithmetic checks; mathematical-edge validation stays strict.

Blend sorts objects, not triangles within a mesh; intersecting transparent surfaces can still overlap incorrectly. General section materials, hatching, projected 3D anchors, 3D picking, point lights, shadows and PBR remain outside 0.4.2. Unlit remains available and is the default.

An additional Intel UHD (CML GT2) / Mesa 26.1.6 Vulkan qualification run did not complete the material readback fixture; the same wait reproduced on the unchanged dev.4 baseline. This configuration is not qualified by the successful NVIDIA or software-Vulkan runs. See known boundaries.

§Installation

The default feature set includes the wgpu renderer:

cargo add sim-engine@0.4.2

or add it directly to Cargo.toml:

[dependencies]
sim-engine = "0.4.2"

Use core visual-state APIs without GPU dependencies:

[dependencies]
sim-engine = { version = "0.4.2", default-features = false }

Run the examples from a repository checkout matching the library version:

cargo run --release --features text --example text_ui_updates
cargo run --release --features text --example text_ui_updates -- --page fonts
cargo run --release --features text --example text_ui_updates -- --font /path/to/MyFont.ttf
cargo run --release --features text --example text_ui_updates -- --acceptance
cargo run --release --example frame_cache_benchmark
cargo run --release --example frame_cache_benchmark -- --case mixed --labels 1000 --trials 3 --frames 120
cargo run --release --example stroke_gallery -- --page 5
cargo run --release --example editable_textured_3d
cargo run --release --example editable_textured_3d -- --acceptance
cargo run --release --example dense_scene_benchmark -- --constructions 500 --mode analytic --labels batch

The text lab has three pages: 1 compares DejaVu Sans/Serif/Mono, Inter and DejaVu Math; 2 (default) shows 𝓣𝔂𝓹𝓮 𝓼𝓸𝓶𝓮𝓽𝓱𝓲𝓷𝓰 𝓽𝓸 𝓼𝓽𝓪𝓻𝓽, math symbols, Japanese, combining accents and one Arabic RTL run; 3 exercises retained updates, clipping and motion at 16/24/48 logical pixels. Use the wheel to scroll shorter gallery windows, and --page fonts|unicode|motion to select the initial page. Licensed font fixtures are embedded, including an 89 KiB Japanese example subset, not a full CJK font. --font replaces the selected font comparison and motion samples with your TTF/OTF file. Font support is opt-in; the default renderer and core-only builds retain their dependency boundary. UI navigation, audio, and domain logic stay in the host. --acceptance exercises public update, composition and recovery routes and requires 40 actual presented frames on each page. Automatic font fallback and mixed-script paragraph layout are not implied by these independently shaped, explicitly font-selected rows. For changing-text diagnostics, use frame_cache_benchmark --case recolored --labels 1000 --cache on; compare with --upload-staging 0 to isolate bounded uniform-upload packing without disabling the other caches. Transfer memory and GPU copy work are reported separately from host-upload bytes.

§Loading a font

Enable the optional text feature:

sim-engine = { version = "0.4.2", features = ["text"] }
use sim_engine::{FontBudget, FontFace};

let font = FontFace::from_bytes(
    std::fs::read("assets/MyFont.ttf")?,
    FontBudget::default(),
)?;

Then create a TextAtlas2d, prepare a TextRun2d, and draw it through the frame composer. The font guide covers the complete render/update/DPI/recovery workflow. Supply trusted, appropriately licensed font assets. Automatic font fallback, paragraph bidi, wrapping, color emoji, and font-file I/O are not built into the engine.

For CPU-only font work, use default-features = false, features = ["fonts"]. TextShapingSession reuses shaping state; TextAtlas2d::prepare_from_shaped and update_from_shaped consume its results without shaping again.

§Quick Start

use sim_engine::{Camera2d, Color, Rect, Scene, ShapeStyle, Vec2};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let camera = Camera2d::new(Vec2::ZERO, 2.0)?;
    let mut scene = Scene::new(Color::rgb8(12, 14, 18))?;

    scene.try_circle(
        Vec2::new(10.0, 20.0),
        8.0,
        ShapeStyle::filled(Color::rgb8(86, 195, 255)),
    )?;
    scene.try_rect(
        Rect::from_center_size(Vec2::ZERO, Vec2::new(120.0, 64.0)),
        8.0,
        ShapeStyle::fill_stroke(
            Color::rgb8(24, 31, 44),
            2.0,
            Color::rgb8(86, 195, 255),
        ),
    )?;

    let _ = camera;
    Ok(())
}

Window creation stays in the host. Renderer initialization is asynchronous; steady-state updates and rendering are synchronous submissions. Standalone retained-resource mutations submit their transfer immediately (without waiting for GPU completion), while a skipped surface frame enqueues no uploads:

ⓘ
let options = WgpuRendererOptions::new(
    RendererPresentMode::Vsync,
    window.scale_factor(),
)?;
let mut renderer = WgpuRenderer::new_with_options(
    window.clone(),
    width,
    height,
    options,
).await?;
let notify_window = window.clone();
renderer.set_pre_present_notify(move || notify_window.pre_present_notify());

let mut frame = renderer.begin_frame(scene.background(), FrameBudget::default())?;
frame.draw_scene(&scene, camera, FramePassOptions::default())?;
let report = frame.present()?;

§Choose A Rendering Path

WorkloadPreferred API
Small changing sceneScene
Static geometry with a moving cameraPreparedScene
Frequently changing trianglesDynamicMesh2d
Images and atlas spritesImage2d plus ImageBatch2d
TTF/OTF labels and counters (text feature)FontFace, TextAtlas2d and TextRun2d
Host-shaped scientific textGlyphAtlas2d plus GlyphRun2d
Large point or circle populationParticleField2d
Dense scalar gridScalarFieldTexture
Mixed UI, viewports, fields, and targetsFrameComposer
Bounded gas plus particle overlayrender_layered_visualization
Stereometry solids and hidden edgesMesh3d plus Scene3d
Changing 3D geometry with immutable aliasesupdate_scene3d_mesh with DynamicMesh3dBudget
Material or background changes without geometry uploadScene3d::set_texture_material / set_background
Partial 3D texture editsupdate_scene3d_texture_region

§Examples

cargo run --release --example demo
cargo run --release --example ui_demo -- --uncapped
cargo run --release --example star_remnant_stress -- --benchmark
cargo run --release --no-default-features --example particle_cpu_benchmark
cargo run --release --no-default-features --example scene_construction_benchmark
cargo run --release --example rendering_benchmark_suite -- --fixture ui_90_10
cargo run --release --example stroke_gallery -- --uncapped
cargo run --release --example stereometry_3d -- --uncapped
cargo run --release --example cylinder_derivation_3d -- --uncapped --benchmark
cargo run --release --example materials_3d
cargo run --release --example lighting_3d
cargo run --release --example texture_lifecycle_3d
cargo run --release --example texture_lifecycle_3d -- --acceptance
cargo run --release --all-features --example mesh3d_scene_benchmark -- --case repeated

From a Sim;Engine repository checkout, run the complete named performance/contract matrix on a Vulkan-capable Linux machine with ./scripts/rendering_benchmark_matrix.sh. Release scripts are repository tooling and are intentionally not shipped in the crates.io source archive. Gated surface workloads require a 1280x720 physical surface at scale 1.0; both values are printed in every result. Absolute timings are comparable only when surface extent, scale, adapter, driver, backend, present mode, and workload are recorded together; deterministic command/vertex/upload counters are portable. The matrix first probes the real production surface. It pins the selected high-performance Vulkan adapter by PCI bus address as well as backend, name, vendor, and model, then requires the offscreen semantic oracle and every surface/HiDPI process to use that same physical GPU. The oracle uses the production surface format and its selected MSAA count. A nested compositor may advertise a different surface format; its HiDPI evidence remains pinned by the physical PCI identity rather than pretending two surfaces have identical capabilities. Every warmup and measured report must be Drawn; a timeout, occlusion, or outdated surface fails the fixture instead of inflating throughput with skipped attempts. Gated workloads use three independent 120-frame trials. Every trial must meet the wall-throughput floor; the reported median is diagnostic only. Renderer-work percentiles cover all 360 drawn frames, so one failed trial cannot be hidden by two faster trials.

The matrix always enforces fixture-specific p95 ceilings for renderer work excluding surface acquisition. Immediate additionally requires 60 presented FPS. Mailbox/FIFO wall throughput must reach 95% of the confirmed current monitor refresh, bounded to a 30-60 Hz release floor. The window is mapped by an unmeasured drawn frame before any output metadata is used. Immediate does not require refresh metadata; Mailbox/FIFO require a positive refresh rate from the window’s confirmed current monitor. Zero/unknown refresh and primary/first-monitor fallbacks are never accepted for synchronized evidence. Warmup and measured frames advance one RedrawRequested at a time, allowing compositor events between every sample. A resize, scale transition, or changed current-output identity invalidates the confirmation and discards partial timing samples; a surface outside the fixed release extent/scale fails rather than being measured as a cheaper workload. The benchmark registers Window::pre_present_notify with the renderer. The callback runs after queue submission and immediately before present only for the concrete FIFO, FIFO- relaxed, or Mailbox modes; Immediate remains unpaced. The final measured present then yields through a compositor-aware redraw boundary and repeats the generation/output check before evidence is published. Acquire percentiles remain reported but do not independently flip the verdict from one scheduler-sensitive sample. The mandatory workloads include the fused bounded particle/scalar path and a retained-3D target-composition path with 4,096 budgeted dynamic triangles, so per-particle portability/culling/upload, dynamic-triangle proofs, and per-object surface/hidden-edge validation cannot regress outside the release performance evidence. The matrix also drives a nested KWin compositor through a real scale 1.00-to-1.25 transition and records the paired event and successful redraw for the exact revision on that same physical adapter. The automatic transition requires dbus-run-session, kwin_wayland, and kscreen-doctor; a missing executable fails the matrix instead of silently skipping HiDPI evidence. The wrapper, standalone matrix, and standalone HiDPI gate reject a dirty worktree, then build and execute from a read-only detached worktree of the captured commit with a separate Cargo target directory. They recheck the calling checkout before accepting results. Replacement refs and legacy grafts are rejected, and all Git operations run with replacement objects disabled. Evidence therefore remains bound to Git object data for the exact recorded SHA even if the mutable calling worktree changes while a long gate is running. Child gates write only to hidden staging. The launcher atomically publishes a completed bundle after the entire requested gate succeeds; failed, killed, or crashed runs cannot leave a bundle that claims success. A nonblocking process lock rejects concurrent release gates before either invocation can invalidate or publish evidence.

stroke_gallery is the visual oracle for the stroke contract. Pages 1-4 show every cap/join, half-alpha overlap probes, bounded animated dashes, outward endpoint arrow markers, miter fallback, camera rotation, and the accepted 0.005-world-unit line at zoom 10,000. Press Space, arrows, +/-, or R to pause, scrub, zoom, and reset. Page 5 adds the exact-tip scientific arrows introduced in 0.3.

ui_demo includes a retained host-rasterized scientific glyph probe above all four independently changing scene workloads. It demonstrates one-time atlas and run creation without requiring the optional font loader or shaping path.

§Verification

From a clean Sim;Engine repository checkout, the Linux release gate checks the declared Rust 1.90 MSRV, all targets with and without the renderer and CPU fonts, strict clippy, rustdoc, Vulkan semantic GPU readback with a backend assertion, the Vulkan performance matrix on a real surface, real text/standalone-mesh recovery, a transactional nested-compositor HiDPI transition, and the publishable package boundary:

./scripts/linux_release_gate.sh

After all 11 steps pass, the launcher atomically publishes target/linux-release-evidence/. Its completion.txt binds the successful gate and exact SHA; the same directory contains linux-vulkan-surface.txt, linux-vulkan-adapter.txt, linux-vulkan-performance.txt, and linux-hidpi-transition.txt. The performance manifest preserves the complete fixture counters, timings, thresholds, and passed verdicts for all nine surface runs instead of leaving them only in terminal output.

Maintainers should follow the complete official release procedure. Publishing is complete only when crates.io exposes the immutable package, the annotated Git tag points at the evidenced commit, and the matching GitHub Release is public.

§License

Licensed under either MIT or Apache-2.0, at your option.

Structs§

AmbientLight3d
Normalized opaque RGB and bounded ambient intensity.
Camera2d
2D camera mapping world coordinates into logical screen pixels.
Camera3d
Validated 3D view and projection used for stereometry rendering.
Circle
Circle primitive in world coordinates.
Color
Linear RGBA color with channels in the 0.0..=1.0 range.
ColorMap
A piecewise-linear map from normalized scalar values to linear RGBA colors.
ColorStop
One normalized color-map control point.
DirectionalLight3d
One directional source whose direction points from a surface toward the light.
DynamicMesh2d
Mutable GPU triangle-list geometry for high-frequency simulation visuals.
DynamicMesh3dBudget
Limits one scene-owned mesh update, including reserved buffers and overlap.
DynamicMesh3dUpdateReport
Exact engine-owned work/capacity counters for a committed full source update.
DynamicMeshBudget
Explicit retained and upload limits for caller-provided colored triangles.
DynamicMeshUpdateReport
CPU-side outcome of one dynamic mesh update.
DynamicVertex2d
One world-space vertex in a dynamic triangle-list mesh.
Fog3d
Exponential RGB fog using camera-forward world distance, never a culling rule.
FontBudget
Limits checked before taking ownership of a parsed font. Parser-owned metadata and allocator overhead are not included in source bytes.
FontFace
One owned TTF/OpenType outline face (collection index zero).
FrameBudget
Explicit upper bounds for one heterogeneous presentation frame.
FrameCacheBudget
Idle retention limits for composition scratch and cached draw bindings.
FrameCacheStatistics
Library-owned retained allocation sizes and the last composition’s cache work. CPU byte counts use actual Vec capacities, uniform and transfer-storage bytes use buffer sizes, and texture bytes count each cached resource identity once.
FrameComposer
One bounded, stably ordered surface frame under construction.
FramePassOptions
Shared placement and ordering state for one frame item.
FrameReport
Outcome and diagnostics for one composed frame.
FrameSourceStatistics
Ordered frame inputs grouped by their renderer source path.
FrameStatistics
Bounded work and retained allocations referenced by one composed frame.
GlyphAtlas2d
Renderer-owned sRGB RGBA glyph atlas with exact pixels and sorted metadata.
GlyphAtlasBudget
Image and metadata limits retained with a GlyphAtlas2d.
GlyphAtlasEntry
Maps one glyph identity to a non-empty rectangle in an atlas image.
GlyphBatch2d
A retained, ordered snapshot of prepared glyph placements sharing one atlas.
GlyphBatchBudget
Explicit limits for a retained many-placement glyph batch.
GlyphBatchUploadReport
Allocation and upload outcome of a transactional glyph-batch update.
GlyphId
Opaque host-provided glyph identity within one GlyphAtlas2d.
GlyphRun2d
Renderer-owned positioned glyph run drawn as at most one instanced atlas batch.
GlyphRunBounds
Deterministic logical-pixel bounds of a submitted positioned glyph run.
GlyphRunBudget
Retained glyph-run count and byte limits.
GlyphRunPlacement2d
One prepared run’s placement in an ordered atlas batch.
GlyphRunStatistics
Bounded retained glyph-run statistics independent of frame timing.
GlyphRunUploadReport
Outcome of an atomic capacity-aware glyph-run update.
GlyphUploadReport
Result of uploading one glyph image into an existing atlas.
GpuTimingBatch
Fixed-capacity result of one nonblocking GPU-diagnostics collection.
GpuTimingId
Opaque correlation key returned by a submitted render report.
GpuTimingSample
One completed GPU render-pass interval obtained from hardware timestamps.
GpuTimingStatistics
Current-device bounded diagnostics resource and loss accounting.
Image2d
Renderer-owned straight-alpha sRGB RGBA image with exact recovery pixels.
ImageBatch2d
Renderer-owned atlas sprite batch drawn with at most one instanced draw call.
ImageBatchBudget
Hard retained-count and byte limits for an ImageBatch2d.
ImageBatchPlacement
Independent presentation of one retained image batch or glyph run.
ImageBatchUploadReport
CPU outcome of replacing a retained image/sprite instance batch.
ImageBudget
Immutable resource limits retained with an Image2d.
ImageSprite2d
One validated atlas region placed in local logical-screen coordinates.
ImageTexelRect
Validated non-empty atlas rectangle in physical source texels.
ImageUploadReport
CPU outcome of a complete or partial image upload.
Layer
Draw layer used to order scene commands.
LayeredVisualizationOptions
Validated presentation settings for a scalar field with a particle overlay.
LayeredVisualizationReport
Status, timings, and encoded-work counters for one fused scalar/particle frame.
Lighting3d
Ready visual lighting state: ambient and at most one directional source.
Line
Stroked line primitive in world coordinates.
LinearGradient
Linear color gradient in world coordinates.
LogicalPixels
Positive finite scalar measured in logical screen pixels.
LogicalScreenPosition
Point measured in logical screen pixels with a top-left origin.
LogicalScreenVector
Offset or size measured in logical screen pixels.
LogicalViewport
Logical pixel dimensions of the viewport currently being drawn into.
LogicalViewportRegion
A logical viewport positioned inside a larger presentation target.
Mesh3d
Immutable validated topology for retained stereometry rendering.
Mesh3dAttributes
Extensible model-vertex data for super::Mesh3d::with_attributes.
Mesh3dInstance
One retained mesh reference plus its independent model transform and style.
Mesh3dPreflightReport
Non-mutating preflight counts for the exact scene, camera, target and budget.
Mesh3dRenderBudget
Limits submitted surfaces and additional clip-space topology in one 3D draw.
Mesh3dRenderReport
CPU-side result of one depth-tested offscreen 3D draw.
Mesh3dUploadBudget
Per-upload limits checked before caller-scale staging or GPU allocation.
Mesh3dUploadReport
Nominal buffer/source accounting for an accepted immutable replacement.
MeshEdge3d
One explicit display edge in a retained 3D mesh.
MeshStyle3d
Extensible visual material bundle for a retained 3D object.
Object3dId
Stable scene handle for a retained 3D object.
Palette
Default visual palette for Sim;Engine demos and early integrations.
ParticleField2d
Renderer-owned instanced particles for high-volume simulation visuals.
ParticleFieldUpdateReport
CPU-side outcome of one particle-field update.
ParticleInstance2d
One validated visual particle used by the optional instanced GPU renderer.
ParticleRenderBudget
Hard steady-state per-field limits for bounding particle visualization.
ParticleStatistics
Counts associated with one particle-field update or draw.
PhysicalPerLogical
Backend-stable physical texels per logical screen pixel.
PhysicalScreenPosition
Point measured in physical surface pixels with a top-left origin.
Polyline
Connected line-strip primitive in world coordinates.
PositionedGlyph2d
One host-shaped glyph quad in local logical-screen coordinates.
PreparedScene
Immutable scene geometry tessellated and uploaded once for repeated drawing.
PreparedScreenScene
Immutable prepared geometry whose positions are logical screen pixels.
PrimitiveCommandCounts
Command counters grouped by ordinary 2D primitive category.
ProjectedPoint3d
Result of projecting a 3D point into a logical viewport.
Projection2d
Lightweight pseudo-depth projection for 2D scenes.
Projection3d
Perspective or orthographic camera projection with a finite depth range.
RadialGradient
Radial color gradient in world coordinates.
RasterizedGlyph
Grayscale coverage at physical-pixel resolution, relative to baseline zero. Coverage is linear alpha (0..255), not an sRGB intensity or premultiplied RGB.
Rect
Axis-aligned rectangle represented by minimum and maximum corners.
RectShape
Axis-aligned rectangle primitive in world coordinates.
RenderReport
Status and CPU timing breakdown for one renderer frame.
RenderTarget2d
A renderer-owned offscreen color target in physical texture pixels.
RenderTarget3d
Offscreen color and depth attachments for stereometry rendering.
RendererDiagnostics
Adapter and presentation context captured from the active renderer.
RendererFrameMetrics
CPU-side durations measured while preparing and submitting one renderer frame.
RendererPreparationMetrics
Non-overlapping CPU preparation stages for a heterogeneous composed frame.
RetainedMesh3d
Immutable retained GPU buffers for one validated Mesh3d.
Rotation3d
Normalized 3D rotation applied in a right-handed coordinate system.
ScalarField
A finite, rectangular scalar grid for dense simulation data.
ScalarFieldTexture
Renderer-owned scalar texture retaining its validated source field.
ScalarFieldUploadReport
CPU-side outcome of one scalar-field texture upload.
Scene
Ordered list of visual draw commands for a single frame.
Scene3d
Ready 3D visual state rendered with one camera and depth attachment.
Scene3dBudget
Bounds scene-owned slots and distinct retained mesh allocations.
Scene3dMeshUpdateReport
Accounting for an immutable mesh rebinding, including old/new overlap.
Scene3dRestoreReport
Result of atomically migrating a retained 3D scene to the active renderer device.
Scene3dStatistics
Current scene-owned capacities and unique mesh allocations, excluding drivers.
SceneBudget
Explicit upper bounds for engine-owned ordinary-scene work.
SceneCommand
Draw command with layer and stable insertion order metadata.
SceneStatistics
Construction and conservative rendering work accumulated by a scene.
ScreenClipRect
Axis-aligned clipping rectangle in logical screen pixels.
ScreenPrimitive2d
One validated solid primitive in viewport-local logical pixels. Coordinates have a top-left origin and positive y downward. Clipping is viewport-local, not translated with the primitive. Shapes are independent; a sequence of capsules is not a polyline join implementation. Constructors reject non-portable geometry, non-normalized linear RGBA and unrepresentable source precision. Drawing additionally checks a combined boundary-error bound of 0.25 physical pixels at the actual target density; accepted construction does not guarantee acceptance at every later DPI.
ScreenPrimitiveBatch2d
An ordered immutable draw snapshot of solid screen primitives.
ScreenPrimitiveBudget
Explicit primitive, resident CPU/GPU and per-update upload limits. During capacity growth old/new resources may overlap, bounded by twice the resident limits. Input slices and driver/in-flight allocations are excluded.
ScreenPrimitiveUploadReport
Actual work of one accepted full snapshot update.
ScreenScene
A bounded 2D scene whose geometry is expressed in logical screen pixels.
Shadow
Simple screen-space shadow used by the first renderer slice.
ShapeStyle
Fill, stroke, and shadow styling for solid primitives.
ShapedGlyph
A shaped glyph’s font-local identity and baseline-relative logical placement.
ShapedLine
Immutable shaped placement; rasterization and GPU ownership are separate.
Stroke
Stroke color and width for lines and shape outlines.
StrokeDashPattern2d
Fixed-size, allocation-free dash pattern in source path-coordinate units.
StrokeMarker2d
Reusable arrow marker definition for a line endpoint.
StrokeStyle2d
Complete bounded styling for open 2D lines and polylines.
SurfaceStyle3d
Validated surface tint, alpha policy and projected face visibility.
TessellationStats
Outcome of converting accepted scene commands into GPU vertices.
TextAtlas2d
Antialiased font cache for one font, logical EM size, direction and DPI.
TextAtlasBudget
Fixed atlas texel/cache capacity and per-run limits for optional font rendering.
TextLayoutBudget
Per-line and per-glyph work limits.
TextRun2d
Retained, shaped single-line text and its baseline metrics.
TextShapingSession
Caller-owned reusable CPU shaping state for one borrowed font and fixed style. Available with fonts, without a renderer or GPU dependency.
TextStyle
Immutable logical em size and raster DPI, independent of text color/placement.
TextUpdateReport
Successful update diagnostics. Unchanged text reports zero work.
Texture3d
Cheap immutable snapshot of an independently filtered sRGB RGBA8 mip chain.
Texture3dOptions
Explicit creation policy for independently filtered 3D RGBA8 images.
Texture3dUpdateBudget
Explicit operation-local limits for atomic texture edits and alias detachment.
Texture3dUpdateReport
Exact edit work and nominal resource storage; no GPU timing is inferred.
TextureCoordinate2d
Normalized texture coordinate with a top-left origin and downward V axis.
TextureMaterial3d
Cheap immutable unlit material sharing one texture and filter state.
TextureUvTransform3d
Affine texture coordinates: sample_uv = source_uv * scale + offset.
TrailBuffer2d
A pair of offscreen targets used for bounded temporal accumulation.
Transform3d
Model transform with translation, rotation, and positive per-axis scale.
Tween
Time-based interpolation from one value to another.
Vec2
A 2D vector used for world-space and screen-space coordinates.
Vec3
Finite vector or point in a right-handed 3D coordinate space.
WgpuRenderer
wgpu backend that renders Scene commands into a presentation surface.
WgpuRendererOptions
Options used when creating a WgpuRenderer.
WireframeStyle3d
Logical-screen presentation for explicit mathematical mesh edges.
WorldLength
Positive finite distance measured in caller-defined world units.

Enums§

BlendMode
How a render target is combined with the presentation surface.
Camera2dError
Invalid camera configuration or inverse projection request.
ColorMapError
Rejection reason for color-map construction or sampling.
DrawCommand
Renderable primitive command.
DynamicMesh3dBudgetResource
Operation-local overlap category that exceeded the dynamic update budget.
DynamicMesh3dError
Synchronous update failure; the object’s drawable revision remains unchanged.
DynamicMeshBudgetResource
Host-selected work category constrained by DynamicMeshBudget.
DynamicMeshError
Validation or ownership failure while changing a dynamic mesh.
DynamicMeshRenderError
Failure while rendering a DynamicMesh2d.
Easing
Easing curve used to remap normalized tween progress.
Fill
Paint used to fill a shape.
Fog3dError
Invalid source fog state, rejected before scene mutation.
FontBudgetResource
Resource whose explicit font or layout limit was exceeded.
FontError
Explicit loading, shaping or rasterization failure.
FrameBudgetResource
Work category constrained by a FrameBudget.
FrameComposerError
Failure while constructing or presenting a heterogeneous frame.
FrameSourceKind
Renderer-owned source category used in structured composer errors.
GlyphError
Failure while constructing, updating, or restoring glyph resources.
GpuTimingSource
Render pass measured by a sample, not CPU uploads or presentation latency.
GpuTimingStatus
Availability of the explicitly requested render-pass GPU diagnostics.
ImageError
Failure while creating, restoring, or updating an RGBA image.
ImageSampling
Texture filtering used by a composed image or atlas region.
LayeredVisualizationError
Failure while drawing a bounded scalar-field and particle composition.
Lighting3dError
Invalid source lighting state, rejected before any scene mutation.
LogicalViewportError
Invalid logical dimensions supplied to LogicalViewport.
Mesh3dError
Rejection reason for retained 3D topology.
Mesh3dObjectError
Instance-local numerical rejection category from authoritative 3D preflight.
Mesh3dRenderError
Failure while encoding a depth-tested 3D scene.
Mesh3dResourceError
Resource creation or ownership failure for retained 3D rendering.
Mesh3dStyleError
Rejection reason for logical-screen 3D edge presentation.
Mesh3dSurfaceError
Specific cause of failure for an original source surface triangle.
Mesh3dUploadBudgetResource
Byte category bounded before immutable mesh upload or replacement.
ParticleBudgetError
Invalid particle visualization resource budget.
ParticleFieldError
Failure while creating or updating a ParticleField2d.
ParticleFieldRenderError
Failure while rendering a ParticleField2d.
ParticleInstanceError
Rejection reason for particle visual state.
PreparedSceneError
Failure while uploading or restoring immutable prepared-scene geometry.
PreparedSceneRenderError
Failure to draw geometry prepared by WgpuRenderer::prepare_scene.
PreparedTextError
Rejected prepared-text provenance/limits or an underlying atlas/run operation. Existing UTF-8 APIs retain their original TextError return type.
Projection2dError
Invalid pseudo-depth projection parameters.
Pseudo3dError
Invalid pseudo-3D visual state or arithmetic.
RenderStatus
Result of attempting to draw a frame.
RenderTargetError
Failure while creating or composing a RenderTarget2d.
RenderTargetLoad
How a target-rendering pass initializes its destination pixels.
RendererConfigurationError
Invalid runtime or initialization configuration for WgpuRenderer.
RendererCoordinateError
Failure while converting between logical and physical screen coordinates.
RendererFrameError
Fatal failure while preparing or submitting one frame.
RendererInitError
Errors that can happen while creating the wgpu renderer.
RendererPresentMode
Presentation behavior for the window surface.
RendererSurfacePresentMode
Concrete presentation mode selected from the active Linux surface.
RendererSurfaceStatus
Recoverable or fatal state reported by the presentation surface.
ScalarFieldError
Rejection reason for scalar-field construction or mutation.
ScalarFieldRenderError
Failure while rendering a scalar texture as a heatmap.
ScalarFieldSampling
Scalar-field sampling mode used by heatmap rendering.
ScalarFieldTextureError
Failure while creating or updating a ScalarFieldTexture.
Scene3dBudgetResource
Bounded scene resource whose limit rejected a mutation.
Scene3dError
Rejection reason for 3D scene visual state.
SceneBudgetResource
Work category constrained by a SceneBudget.
SceneError
Reason a command or temporary scene state was rejected.
ScenePrimitive
Primitive category attached to structured scene validation errors.
ScreenPrimitiveError
Explicit rejection from analytic primitive construction or resource updates.
ShapedLineError
A prepared line cannot be reused with the requested font, style or limits. Kept separate from FontError so existing exhaustive matches remain valid.
StrokeCap2d
Presentation used at an open line or dash endpoint.
StrokeJoin2d
Presentation used where two visible polyline segments meet.
StrokeMarkerAnchor2d
Placement of a logical-pixel arrow relative to its mathematical path endpoint.
StrokeStyleError
Invalid bounded line-style configuration.
StrokeWidthMode2d
Coordinate space used by a line or polyline stroke width.
SurfaceAlphaMode3d
Coverage/depth behavior for a retained surface.
SurfaceLighting3d
Surface RGB illumination; alpha and mathematical display edges are unaffected.
SurfaceRasterization3d
Selects the portability contract for filled 3D surfaces, not display edges.
SurfaceSidedness3d
Surface face visibility after camera projection; display edges are unaffected.
TextDirection
Horizontal shaping direction for one single-script directional run. This does not perform Unicode bidi paragraph segmentation.
TextError
A rejected text asset, layout, cache operation or GPU resource operation.
Texture3dError
Validation or allocation failure for a retained 3D texture/material.
Texture3dUpdateBudgetResource
The operation-local limit exceeded before a texture edit was published.
Texture3dUpdateError
Synchronous texture-update failure; existing drawable state is unchanged.
TextureAddressMode3d
Addressing of a complete independently filtered texture, not a packed tile.
TextureMipmaps3d
Optional mip generation for a retained 3D texture.
TextureUvTransformError
Rejected UV mapping, never silently clamped into another coordinate system.
TweenError
Rejection reason for tween construction, retargeting, or interpolation.
UnitError
Invalid scalar supplied to an explicitly typed rendering unit.

Constants§

MAX_STROKE_DASH_SUBSEGMENTS
Maximum visible dash pieces one command may request from tessellation.

Traits§

Interpolate
Value type that can be interpolated by Tween.