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.1.0 is the first 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.
§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;
- solid, linear-gradient, and radial-gradient fills;
- logical-pixel strokes, shadows, clipping, and stable layer ordering;
- 2D camera pan, rotation, zoom, fit, and picking;
- fallible tweening and easing;
- streaming, prepared, and dynamic triangle geometry;
- 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, 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.
Translucent section materials, hatching, projected 3D anchors, and 3D picking are not part of v0.1.0.
§Installation
The default feature set includes the wgpu renderer:
[dependencies]
sim-engine = "0.1"Use core visual-state APIs without GPU dependencies:
[dependencies]
sim-engine = { version = "0.1", default-features = false }§Quick Start
use sim_engine::{Camera2d, Color, Rect, Scene, ShapeStyle, Vec2};
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),
),
)?;
Window creation stays in the host. Renderer initialization is asynchronous; steady-state updates and rendering are synchronous submissions:
let options = WgpuRendererOptions::new(
RendererPresentMode::Vsync,
window.scale_factor(),
)?;
let mut renderer = WgpuRenderer::new_with_options(
window.clone(),
width,
height,
options,
).await?;
let report = renderer.render_with_metrics(&scene, &camera)?;§Choose A Rendering Path
| Workload | Preferred API |
|---|---|
| Small changing scene | Scene |
| Static geometry with a moving camera | PreparedScene |
| Frequently changing triangles | DynamicMesh2d |
| Large point or circle population | ParticleField2d |
| Dense scalar grid | ScalarFieldTexture |
| 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 --example stereometry_3d -- --uncapped
cargo run --release --example cylinder_derivation_3d -- --uncapped --benchmark§Verification
The v0.1.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, and the publishable package boundary:
./scripts/linux_release_gate.shThe gate records the exact adapter/backend/driver run in
target/linux-vulkan-adapter.txt; CI publishes the same file as an artifact.
§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 Update Report - CPU-side outcome of one dynamic mesh update.
- Dynamic
Vertex2d - One world-space vertex in a dynamic triangle-list mesh.
- Layer
- Draw layer used to order scene commands.
- Layered
Visualization Options - Validated presentation settings for a scalar field with a particle overlay.
- 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.
- 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 per-field limits that keep particle visualization from starving a host simulation.
- Particle
Statistics - Counts associated with one particle-field update or draw.
- Physical
PerLogical - Positive finite 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.
- Prepared
Scene - Immutable scene geometry tessellated and uploaded once for repeated drawing.
- 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
Command - Draw command with layer and stable insertion order metadata.
- Screen
Clip Rect - Axis-aligned clipping rectangle 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.
- 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 3D 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 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.
- 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
Error - Reason a command or temporary scene state was rejected.
- Scene
Primitive - Primitive category attached to structured scene validation errors.
- Tween
Error - Rejection reason for tween construction, retargeting, or interpolation.
- Unit
Error - Invalid scalar supplied to an explicitly typed rendering unit.
Traits§
- Interpolate
- Value type that can be interpolated by
Tween.