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.

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

WorkloadPreferred API
Small changing sceneScene
Static geometry with a moving cameraPreparedScene
Frequently changing trianglesDynamicMesh2d
Large point or circle populationParticleField2d
Dense scalar gridScalarFieldTexture
Bounded gas plus particle overlayrender_layered_visualization
Stereometry solids and hidden edgesMesh3d 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.sh

The 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.0 range.
ColorMap
A piecewise-linear map from normalized scalar values to linear RGBA colors.
ColorStop
One normalized color-map control point.
DynamicMesh2d
Mutable GPU triangle-list geometry for high-frequency simulation visuals.
DynamicMeshUpdateReport
CPU-side outcome of one dynamic mesh update.
DynamicVertex2d
One world-space vertex in a dynamic triangle-list mesh.
Layer
Draw layer used to order scene commands.
LayeredVisualizationOptions
Validated presentation settings for a scalar field with a particle overlay.
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.
Mesh3d
Immutable validated topology for retained stereometry rendering.
Mesh3dInstance
One retained mesh reference plus its independent model transform and style.
Mesh3dRenderReport
CPU-side result of one depth-tested offscreen 3D draw.
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 per-field limits that keep particle visualization from starving a host simulation.
ParticleStatistics
Counts associated with one particle-field update or draw.
PhysicalPerLogical
Positive finite 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.
PreparedScene
Immutable scene geometry tessellated and uploaded once for repeated drawing.
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.
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.
RendererFrameMetrics
CPU-side durations measured while preparing and submitting one renderer 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.
Scene3dRestoreReport
Result of atomically migrating a retained 3D scene to the active renderer device.
SceneCommand
Draw command with layer and stable insertion order metadata.
ScreenClipRect
Axis-aligned clipping rectangle in logical screen pixels.
Shadow
Simple screen-space shadow used by the first renderer slice.
ShapeStyle
Fill, stroke, and shadow styling for solid primitives.
Stroke
Stroke color and width for lines and shape outlines.
SurfaceStyle3d
Surface material for one retained 3D instance.
TessellationStats
Outcome of converting accepted scene commands into GPU vertices.
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 3D 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.
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.
LayeredVisualizationError
Failure while drawing a bounded scalar-field and particle composition.
LogicalViewportError
Invalid logical dimensions supplied to LogicalViewport.
Mesh3dError
Rejection reason for retained 3D topology.
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.
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.
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.
Scene3dError
Rejection reason for 3D scene visual state.
SceneError
Reason a command or temporary scene state was rejected.
ScenePrimitive
Primitive category attached to structured scene validation errors.
TweenError
Rejection reason for tween construction, retargeting, or interpolation.
UnitError
Invalid scalar supplied to an explicitly typed rendering unit.

Traits§

Interpolate
Value type that can be interpolated by Tween.