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.
Version 0.2.0 is the current official Sim;Engine release. 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.
Version 0.2.0 adds the bounded Sim;X integration foundation: fixed-screen scenes, positioned 2D viewports, offscreen scene rendering, a heterogeneous single-present frame composer, retained RGBA images and atlas batches, host-shaped glyph runs, explicitly budgeted dynamic triangles, richer bounded 2D strokes, and a named rendering benchmark matrix. See the 0.2.0 changelog for the complete delta from 0.1.0.
§Documentation
-
Library documentation - installation, concepts, every rendering path, recovery, performance, architecture, and examples.
-
Changelog - release history and user-visible changes.
-
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;
- retained sRGB RGBA images, atlas sprite batches, and world-space image quads;
- host-shaped, bounded glyph atlas runs with deterministic logical bounds;
- 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;
- atomic retained-3D scene recovery that preserves stable object IDs and visual state across logical-device replacement;
- 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, dynamic meshes, particles, scalar fields, images, glyph runs, 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 uses one conservative portability envelope 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.
Translucent section materials, hatching, projected 3D anchors, and 3D picking are not part of v0.2.0.
§Installation
The default feature set includes the wgpu renderer:
cargo add sim-engine@0.2or add it directly to Cargo.toml:
[dependencies]
sim-engine = "0.2"Use core visual-state APIs without GPU dependencies:
[dependencies]
sim-engine = { version = "0.2", default-features = false }§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
| Workload | Preferred API |
|---|---|
| Small changing scene | Scene |
| Static geometry with a moving camera | PreparedScene |
| Frequently changing triangles | DynamicMesh2d |
| Images and atlas sprites | Image2d plus ImageBatch2d |
| Host-shaped scientific text | GlyphAtlas2d plus GlyphRun2d |
| Large point or circle population | ParticleField2d |
| Dense scalar grid | ScalarFieldTexture |
| Mixed UI, viewports, fields, and targets | FrameComposer |
| Bounded gas plus particle overlay | render_layered_visualization |
| Stereometry solids and hidden edges | Mesh3d plus Scene3d |
§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 --benchmarkFrom 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 v0.2 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.
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 making the engine responsible for font selection or
text shaping.
§Verification
From a clean Sim;Engine repository checkout, the v0.2.0 Linux release gate checks the declared Rust 1.90 MSRV, all targets with and without the renderer, strict clippy, rustdoc, Vulkan semantic GPU readback with a backend assertion, the Vulkan performance matrix on a real surface, a transactional nested-compositor HiDPI transition, and the publishable package boundary:
./scripts/linux_release_gate.shAfter 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§
- 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.0range. - Color
Map - A piecewise-linear map from normalized scalar values to linear RGBA colors.
- Color
Stop - One normalized color-map control point.
- Dynamic
Mesh2d - Mutable GPU triangle-list geometry for high-frequency simulation visuals.
- Dynamic
Mesh Budget - Explicit retained and upload limits for caller-provided colored triangles.
- Dynamic
Mesh Update Report - CPU-side outcome of one dynamic mesh update.
- Dynamic
Vertex2d - One world-space vertex in a dynamic triangle-list mesh.
- Frame
Budget - Explicit upper bounds for one heterogeneous presentation frame.
- Frame
Composer - One bounded, stably ordered surface frame under construction.
- Frame
Pass Options - Shared placement and ordering state for one frame item.
- Frame
Report - Outcome and diagnostics for one composed frame.
- Frame
Source Statistics - Ordered frame inputs grouped by their renderer source path.
- Frame
Statistics - Bounded work and retained allocations referenced by one composed frame.
- Glyph
Atlas2d - Renderer-owned sRGB RGBA glyph atlas with exact pixels and sorted metadata.
- Glyph
Atlas Budget - Image and metadata limits retained with a
GlyphAtlas2d. - Glyph
Atlas Entry - Maps one glyph identity to a non-empty rectangle in an atlas image.
- GlyphId
- Opaque host-provided glyph identity within one
GlyphAtlas2d. - Glyph
Run2d - Renderer-owned positioned glyph run drawn as at most one instanced atlas batch.
- Glyph
RunBounds - Deterministic logical-pixel bounds of a submitted positioned glyph run.
- Glyph
RunBudget - Retained glyph-run count and byte limits.
- Glyph
RunStatistics - Bounded retained glyph-run statistics independent of frame timing.
- Glyph
Upload Report - Result of uploading one glyph image into an existing atlas.
- Image2d
- Renderer-owned straight-alpha sRGB RGBA image with exact recovery pixels.
- Image
Batch2d - Renderer-owned atlas sprite batch drawn with at most one instanced draw call.
- Image
Batch Budget - Hard retained-count and byte limits for an
ImageBatch2d. - Image
Batch Upload Report - CPU outcome of replacing a retained image/sprite instance batch.
- Image
Budget - Immutable resource limits retained with an
Image2d. - Image
Sprite2d - One validated atlas region placed in local logical-screen coordinates.
- Image
Texel Rect - Validated non-empty atlas rectangle in physical source texels.
- Image
Upload Report - CPU outcome of a complete or partial image upload.
- Layer
- Draw layer used to order scene commands.
- Layered
Visualization Options - Validated presentation settings for a scalar field with a particle overlay.
- Layered
Visualization Report - Status, timings, and encoded-work counters for one fused scalar/particle frame.
- Line
- Stroked line primitive in world coordinates.
- Linear
Gradient - Linear color gradient in world coordinates.
- Logical
Pixels - Positive finite scalar measured in logical screen pixels.
- Logical
Screen Position - Point measured in logical screen pixels with a top-left origin.
- Logical
Screen Vector - Offset or size measured in logical screen pixels.
- Logical
Viewport - Logical pixel dimensions of the viewport currently being drawn into.
- Logical
Viewport Region - A logical viewport positioned inside a larger presentation target.
- Mesh3d
- Immutable validated topology for retained stereometry rendering.
- Mesh3d
Instance - One retained mesh reference plus its independent model transform and style.
- Mesh3d
Render Report - CPU-side result of one depth-tested offscreen 3D draw.
- Mesh
Edge3d - One explicit display edge in a retained 3D mesh.
- Mesh
Style3d - Extensible visual material bundle for a retained 3D object.
- Object3d
Id - Stable scene handle for a retained 3D object.
- Palette
- Default visual palette for Sim;Engine demos and early integrations.
- Particle
Field2d - Renderer-owned instanced particles for high-volume simulation visuals.
- Particle
Field Update Report - CPU-side outcome of one particle-field update.
- Particle
Instance2d - One validated visual particle used by the optional instanced GPU renderer.
- Particle
Render Budget - Hard steady-state per-field limits for bounding particle visualization.
- Particle
Statistics - Counts associated with one particle-field update or draw.
- Physical
PerLogical - Backend-stable physical texels per logical screen pixel.
- Physical
Screen Position - Point measured in physical surface pixels with a top-left origin.
- Polyline
- Connected line-strip primitive in world coordinates.
- Positioned
Glyph2d - One host-shaped glyph quad in local logical-screen coordinates.
- Prepared
Scene - Immutable scene geometry tessellated and uploaded once for repeated drawing.
- Prepared
Screen Scene - Immutable prepared geometry whose positions are logical screen pixels.
- Primitive
Command Counts - Command counters grouped by ordinary 2D primitive category.
- Projected
Point3d - 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.
- Radial
Gradient - Radial color gradient in world coordinates.
- Rect
- Axis-aligned rectangle represented by minimum and maximum corners.
- Rect
Shape - Axis-aligned rectangle primitive in world coordinates.
- Render
Report - Status and CPU timing breakdown for one renderer frame.
- Render
Target2d - A renderer-owned offscreen color target in physical texture pixels.
- Render
Target3d - Offscreen color and depth attachments for stereometry rendering.
- Renderer
Frame Metrics - CPU-side durations measured while preparing and submitting one renderer frame.
- Retained
Mesh3d - Immutable retained GPU buffers for one validated
Mesh3d. - Rotation3d
- Normalized 3D rotation applied in a right-handed coordinate system.
- Scalar
Field - A finite, rectangular scalar grid for dense simulation data.
- Scalar
Field Texture - Renderer-owned scalar texture retaining its validated source field.
- Scalar
Field Upload Report - 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.
- Scene3d
Restore Report - Result of atomically migrating a retained 3D scene to the active renderer device.
- Scene
Budget - Explicit upper bounds for engine-owned ordinary-scene work.
- Scene
Command - Draw command with layer and stable insertion order metadata.
- Scene
Statistics - Construction and conservative rendering work accumulated by a scene.
- Screen
Clip Rect - Axis-aligned clipping rectangle in logical screen pixels.
- Screen
Scene - A bounded 2D scene whose geometry is expressed in logical screen pixels.
- Shadow
- Simple screen-space shadow used by the first renderer slice.
- Shape
Style - Fill, stroke, and shadow styling for solid primitives.
- Stroke
- Stroke color and width for lines and shape outlines.
- Stroke
Dash Pattern2d - Fixed-size, allocation-free dash pattern in source path-coordinate units.
- Stroke
Marker2d - Reusable arrow marker definition for a line endpoint.
- Stroke
Style2d - Complete bounded styling for open 2D lines and polylines.
- Surface
Style3d - Surface material for one retained 3D instance.
- Tessellation
Stats - Outcome of converting accepted scene commands into GPU vertices.
- Trail
Buffer2d - 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.
- Wgpu
Renderer wgpubackend that rendersScenecommands into a presentation surface.- Wgpu
Renderer Options - Options used when creating a
WgpuRenderer. - Wireframe
Style3d - Logical-screen presentation for explicit mathematical mesh edges.
- World
Length - Positive finite distance measured in caller-defined world units.
Enums§
- Blend
Mode - How a render target is combined with the presentation surface.
- Camera2d
Error - Invalid camera configuration or inverse projection request.
- Color
MapError - Rejection reason for color-map construction or sampling.
- Draw
Command - Renderable primitive command.
- Dynamic
Mesh Budget Resource - Host-selected work category constrained by
DynamicMeshBudget. - Dynamic
Mesh Error - Validation or ownership failure while changing a dynamic mesh.
- Dynamic
Mesh Render Error - Failure while rendering a
DynamicMesh2d. - Easing
- Easing curve used to remap normalized tween progress.
- Fill
- Paint used to fill a shape.
- Frame
Budget Resource - Work category constrained by a
FrameBudget. - Frame
Composer Error - Failure while constructing or presenting a heterogeneous frame.
- Frame
Source Kind - Renderer-owned source category used in structured composer errors.
- Glyph
Error - Failure while constructing, updating, or restoring glyph resources.
- Image
Error - Failure while creating, restoring, or updating an RGBA image.
- Image
Sampling - Texture filtering used by a composed image or atlas region.
- Layered
Visualization Error - Failure while drawing a bounded scalar-field and particle composition.
- Logical
Viewport Error - Invalid logical dimensions supplied to
LogicalViewport. - Mesh3d
Error - Rejection reason for retained 3D topology.
- Mesh3d
Render Error - Failure while encoding a depth-tested 3D scene.
- Mesh3d
Resource Error - Resource creation or ownership failure for retained 3D rendering.
- Mesh3d
Style Error - Rejection reason for logical-screen 3D edge presentation.
- Particle
Budget Error - Invalid particle visualization resource budget.
- Particle
Field Error - Failure while creating or updating a
ParticleField2d. - Particle
Field Render Error - Failure while rendering a
ParticleField2d. - Particle
Instance Error - Rejection reason for particle visual state.
- Prepared
Scene Error - Failure while uploading or restoring immutable prepared-scene geometry.
- Prepared
Scene Render Error - Failure to draw geometry prepared by
WgpuRenderer::prepare_scene. - Projection2d
Error - Invalid pseudo-depth projection parameters.
- Pseudo3d
Error - Invalid pseudo-3D visual state or arithmetic.
- Render
Status - Result of attempting to draw a frame.
- Render
Target Error - Failure while creating or composing a
RenderTarget2d. - Render
Target Load - How a target-rendering pass initializes its destination pixels.
- Renderer
Configuration Error - Invalid runtime or initialization configuration for
WgpuRenderer. - Renderer
Coordinate Error - Failure while converting between logical and physical screen coordinates.
- Renderer
Frame Error - Fatal failure while preparing or submitting one frame.
- Renderer
Init Error - Errors that can happen while creating the
wgpurenderer. - Renderer
Present Mode - Presentation behavior for the window surface.
- Renderer
Surface Present Mode - Concrete presentation mode selected from the active Linux surface.
- Renderer
Surface Status - Recoverable or fatal state reported by the presentation surface.
- Scalar
Field Error - Rejection reason for scalar-field construction or mutation.
- Scalar
Field Render Error - Failure while rendering a scalar texture as a heatmap.
- Scalar
Field Sampling - Scalar-field sampling mode used by heatmap rendering.
- Scalar
Field Texture Error - Failure while creating or updating a
ScalarFieldTexture. - Scene3d
Error - Rejection reason for 3D scene visual state.
- Scene
Budget Resource - Work category constrained by a
SceneBudget. - Scene
Error - Reason a command or temporary scene state was rejected.
- Scene
Primitive - Primitive category attached to structured scene validation errors.
- Stroke
Cap2d - Presentation used at an open line or dash endpoint.
- Stroke
Join2d - Presentation used where two visible polyline segments meet.
- Stroke
Style Error - Invalid bounded line-style configuration.
- Stroke
Width Mode2d - Coordinate space used by a line or polyline stroke width.
- Tween
Error - Rejection reason for tween construction, retargeting, or interpolation.
- Unit
Error - 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.