sim-engine 0.1.0

A validated high-performance visualization engine for simulations
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
# Sim;Engine v0.1.0 Documentation

This document is the public guide and engineering reference for the official
Sim;Engine v0.1.0 release. It is divided into two parts:

- [Integration Handbook]#part-i-integration-handbook - how to add the crate,
  construct visual state, choose a rendering path, recover resources, and
  measure performance.
- [Engineering Reference]#part-ii-engineering-reference - how the crate is
  structured, which invariants it enforces, and where its responsibilities
  end.

For exact signatures and error variants, generate the Rust API reference:

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

Sim;Engine v0.1.0 is the first official release and remains pre-1.0. Linux with
Vulkan is its supported release target, and Rust 1.90 is the minimum supported
Rust version.

## Part I: Integration Handbook

### 1. Scope

Sim;Engine renders ready visual state. The host application owns simulation
stepping, physics, mathematical meaning, entities, navigation, plugins, and UI
policy. The engine owns:

- validated 2D commands and visual styles;
- camera transforms, typed coordinate conversion, clipping, and pseudo-depth;
- visual interpolation;
- prepared, dynamic, particle, and scalar-field GPU resources;
- offscreen targets, composition, and bounded trails;
- retained stereometry meshes, depth, and visible or hidden display edges;
- renderer diagnostics, ownership checks, and resource recovery.

Sim;X is the primary consumer and design driver, but no Sim;X domain type is
required by the public API.

The renderer is not globally asynchronous. Adapter/device creation and device
recovery are async. Normal updates and render calls synchronously encode and
submit GPU work, without normally waiting for its completion.

### 2. Installation and features

The default feature set includes the `wgpu` backend:

```toml
[dependencies]
sim-engine = "0.1"
```

Use the CPU-side visual-state APIs without GPU dependencies:

```toml
[dependencies]
sim-engine = { version = "0.1", default-features = false }
```

| Configuration | Provides |
| --- | --- |
| default / `wgpu` | `WgpuRenderer`, GPU resources, targets, composition, particles, heatmaps, and retained 3D drawing |
| `--no-default-features` | scenes, cameras, colors, fields, particles, tweening, 3D math, mesh topology, and styles |

Window creation is deliberately outside the crate. The host may use `winit`,
as the examples do, or another framework that can provide a compatible
`wgpu::SurfaceTarget<'static>`.

`ParticleInstance2d` is part of the renderer-independent core. Hosts can
generate and benchmark particle visual state without compiling `wgpu`.
`ParticleField2d`, GPU upload, culling, and drawing require the renderer.

### 3. Frame model

A normal frame has four host-owned phases:

1. Advance the simulation or application state.
2. Convert that state into bounded Sim;Engine visual state.
3. Update reusable GPU resources that changed.
4. Render and inspect the returned report.

Do not move domain simulation into a scene builder or renderer callback. A
simulation can run on worker threads, then hand a ready visual snapshot to the
thread that owns the renderer.

### 4. Build a 2D scene

```rust
use sim_engine::{
    Camera2d, Color, Fill, LinearGradient, Rect, Scene, ShapeStyle, Vec2,
};

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

    scene.try_circle(
        Vec2::new(24.0, 12.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::filled_with(Fill::LinearGradient(LinearGradient::new(
            Vec2::new(-60.0, 0.0),
            Vec2::new(60.0, 0.0),
            Color::rgb8(86, 195, 255),
            Color::rgb8(255, 190, 94),
        ))),
    )?;

    let camera = Camera2d::new(Vec2::ZERO, 2.0)?;
    Ok((scene, camera))
}
```

Use `try_*` methods when rejection must be observable. Convenience methods such
as `circle`, `rect`, `line`, and `polyline` return `bool`; use them only when
discarding invalid optional decoration is intentional.

| Primitive | Scene methods | Presentation |
| --- | --- | --- |
| Circle | `circle`, `try_circle`, and layer variants | fill, stroke, shadow |
| Rectangle | `rect`, `try_rect`, and layer variants | rounded corners, fill, stroke, shadow |
| Line | `line`, `try_line`, and layer variants | round caps, logical-pixel width |
| Polyline | `polyline`, `try_polyline`, and layer variants | joined segments and round end caps |

Styles include solid, linear-gradient, and radial-gradient fills; strokes; and
logical-screen shadows. Colors are straight linear RGBA internally.
`Color::rgb8` and `Color::rgba8` convert familiar sRGB bytes to linear light.
`Color::rgb` and `Color::rgba` accept values already in linear space. Render
boundaries require every channel in `0.0..=1.0`; animation may overshoot, but
the host must call `Color::clamp` explicitly before inserting that value.

### 5. Ordering, clipping, and pseudo-depth

2D commands are ordered by `Layer`, then insertion order. Pseudo-depth affects
projection only; it never reorders commands within a layer.

```rust
use sim_engine::{
    Color, LogicalScreenPosition, LogicalScreenVector, ScreenClipRect, Vec2,
};

# fn add_clipped_line(scene: &mut sim_engine::Scene) -> Result<(), Box<dyn std::error::Error>> {
let clip = ScreenClipRect::from_min_size(
    LogicalScreenPosition::new(40.0, 40.0),
    LogicalScreenVector::new(720.0, 420.0),
)?;

scene.with_screen_clip(clip, |scene| {
    scene.line(
        Vec2::new(-1_000.0, 0.0),
        Vec2::new(1_000.0, 0.0),
        2.0,
        Color::WHITE,
    );
})?;
# Ok(())
# }
```

Nested clips are intersected. Each command captures the active clip when it is
inserted, so later state changes cannot alter accepted commands. Clips use
logical pixels and a top-left origin.

`Projection2d` provides lightweight camera-relative tilt/depth presentation.
It is useful for layered 2.5D visuals, but it is not a z-buffer and does not
replace the retained 3D path.

### 6. Coordinates and HiDPI

| Type | Coordinate space |
| --- | --- |
| `Vec2` | caller-defined 2D world/vector value |
| `LogicalScreenPosition` | logical pixels, top-left origin |
| `LogicalScreenVector` | logical-pixel offset or size |
| `LogicalPixels` | positive logical-pixel scalar length |
| `PhysicalScreenPosition` | surface pixels, top-left origin |
| `PhysicalPerLogical` | physical target texels per logical pixel |
| `LogicalViewport` | finite logical viewport dimensions |
| `WorldLength` | positive scalar distance in caller-defined 3D world units |
| `RenderTarget2d` dimensions | physical texture pixels |

Camera zoom is logical pixels per world unit. Stroke widths, screen shadows,
and clips are logical pixels, so monitor scale does not change their intended
visual size. Retained 3D wireframe widths and dash/gap lengths require
`LogicalPixels`; projection near/far distances and orthographic span require
`WorldLength`; `RenderTarget3d::pixels_per_logical` returns
`PhysicalPerLogical`. Their private representations prevent accidental direct
substitution between world, logical, and physical scales.

Convert physical pointer input before picking:

```rust,ignore
let logical_pointer = renderer.physical_to_logical_screen(
    PhysicalScreenPosition::new(pointer_x as f32, pointer_y as f32),
)?;
let world = camera.screen_to_world(
    logical_pointer,
    renderer.logical_viewport()?,
)?;
```

On window changes, update both physical size and scale:

```rust,ignore
renderer.resize_with_scale_factor(width, height, window.scale_factor())?;
```

Zero physical dimensions are ignored because a minimized surface cannot be
configured at zero size. Scale factors that cannot produce a finite logical
viewport are rejected.

### 7. Cameras and motion

`Camera2d` supports finite pan, zoom, rotation, fit-to-bounds, picking, and
zooming about a logical-screen anchor. Forward and inverse conversion methods
are fallible because valid finite inputs can still overflow during arithmetic
or produce a singular projection. Preserve the last valid camera when an
interactive update fails.

`Tween<T>` is fallible for the same reason:

```rust
use std::time::Duration;
use sim_engine::{Easing, Tween};

let mut zoom = Tween::new(1.0)?
    .to(4.0, Duration::from_millis(300), Easing::EaseInOutCubic)?;
let current = zoom.update(Duration::from_millis(16))?;

# let _ = current;
# Ok::<(), sim_engine::TweenError>(())
```

Built-in `f32` and `Vec2` interpolation protects extreme finite endpoints from
overflow. A custom `Interpolate` implementation must report valid values
truthfully; invalid initial, target, or intermediate state returns
`TweenError` without partially mutating the tween.

### 8. Initialize and configure the renderer

```rust,ignore
use sim_engine::{RendererPresentMode, WgpuRenderer, WgpuRendererOptions};

let options = WgpuRendererOptions::new(
    RendererPresentMode::Vsync,
    window.scale_factor(),
)?;
let mut renderer = WgpuRenderer::new_with_options(
    window.clone(),
    window.inner_size().width.max(1),
    window.inner_size().height.max(1),
    options,
).await?;
```

`RendererPresentMode::Vsync` requests FIFO. `NoVsync` requests the fastest
advertised non-VSync mode and may fall back to FIFO. Query
`renderer.surface_present_mode()` for the concrete Immediate, Mailbox, FIFO,
or FIFO-relaxed configuration chosen by the surface. This does not guarantee
that a desktop compositor will scan out above the monitor refresh rate.

On Wayland, `Window::pre_present_notify()` installs compositor pacing. Call it
for ordinary VSync presentation. An explicit uncapped diagnostic loop may omit
it when the selected surface mode is Immediate. Mailbox and FIFO still impose
their own back-pressure.

`renderer.wait_for_gpu_idle()` is for bounded benchmarks and controlled
readback. Waiting every interactive frame destroys CPU/GPU overlap.

### 9. Render reports and errors

```rust,ignore
match renderer.render_with_metrics(&scene, &camera) {
    Ok(report) => {
        let status = report.status();
        let metrics = report.metrics();
        let renderer_cpu = metrics.total_cpu();
        let dropped = metrics.tessellation_stats().dropped_command_count();
        record(status, renderer_cpu, dropped);
    }
    Err(error) => handle_render_error(error),
}
```

`RenderStatus::Skipped` is not a drawn frame. A timeout, occlusion, outdated
surface, or zero-sized surface can be transient. `RendererFrameMetrics`
contains CPU wall-clock durations for tessellation, upload, camera-uniform
upload, surface acquisition, encode/submit/present dispatch, and total renderer
work. It does not measure GPU completion or display scanout.

`TessellationStats` distinguishes accepted commands, rendered commands, and
dropped commands. Required visuals should use fallible scene APIs and hosts
should surface a non-zero dropped count in diagnostics.

Error-handling rules:

- `RendererMismatch` indicates a host lifecycle bug.
- Capacity errors require a smaller workload or a different device budget.
- Invalid transforms require corrected visual state; retrying unchanged data
  is not useful.
- Transient skipped surface states can be retried on a later event-loop turn.
- Device/surface loss requires explicit recovery and resource restoration.

### 10. Select a rendering path

| Workload | API | Expected update cost |
| --- | --- | --- |
| Small changing scene | `Scene` + `render_with_metrics` | validate, tessellate, upload every frame |
| Static shapes, moving camera | `PreparedScene` | prepare once, update camera per frame |
| Frequently changing triangles | `DynamicMesh2d` | upload ready triangle data |
| Many circles or points | `ParticleField2d` | cull, budget, compact, instanced draw |
| Dense scalar grid | `ScalarFieldTexture` | texture update and heatmap shader |
| Field plus particle overlay | `render_layered_visualization` | one encoder and one queue submission |
| Stereometry solids | `Mesh3d` + `Scene3d` | retained topology and per-object transforms |

#### Prepared scenes

```rust,ignore
let prepared = renderer.prepare_scene(&scene)?;
let report = renderer.render_prepared_with_metrics(&prepared, &camera)?;
```

Preparation captures geometry, background, clips, draw batches, and a CPU
recovery snapshot. Any geometry, style, order, or clip change requires a new
prepared scene. A prepared resource belongs to the renderer that created it.

#### Dynamic triangle geometry

`DynamicVertex2d` stores world position, pseudo-depth, and linear color.
`create_dynamic_mesh` accepts a triangle list whose vertex count is divisible
by three. Full updates replace the list; triangle-aligned range updates reuse
the existing allocation. Update reports expose upload time and reallocation.

Use this path for ready visual triangles, not as a new simulation data model.

### 11. Particles and hard budgets

`ParticleInstance2d` contains world position, logical-pixel radius, color, and
pseudo-depth. `ParticleField2d` retains validated instances and draws selected
particles through one instanced path.

```rust,ignore
use sim_engine::ParticleRenderBudget;

let budget = ParticleRenderBudget::new(
    30_000,          // maximum visible instances
    2 * 1024 * 1024, // maximum GPU instance bytes
    2 * 1024 * 1024, // maximum upload bytes per frame
)?
.with_max_visibility_checks(60_000)?;

let mut particles =
    renderer.create_particle_field_with_budget(&instances, budget)?;
```

When the visibility-check cap is below the retained population, the renderer
samples candidates uniformly rather than pretending that every instance was
classified. Inspect `ParticleStatistics`: submitted, visibility-checked,
visible, culled, budget-limited, dropped, and rendered counts are distinct.

Memory observability is explicit through `cpu_allocation_bytes`,
`gpu_allocation_bytes`, and `recovery_memory_bytes`. Use those limits so
rendering leaves capacity for the simulation itself.

### 12. Scalar fields and color maps

`ScalarField` stores a finite row-major grid. Dimensions must be non-zero and
match the value count. Full replacement and rectangular region updates are
validated atomically.

`ScalarField::filled` performs a fallible reservation under a 256 MiB default
value-buffer budget. Use `filled_with_byte_limit` for a different explicit host
budget, or `ScalarField::new` when the host already owns the allocated values.

```rust,ignore
let field = ScalarField::filled(160, 96, 0.0)?;
let mut texture = renderer.create_scalar_field_texture(field)?;

renderer.update_scalar_field_texture_region(
    &mut texture,
    x,
    y,
    width,
    height,
    &changed_values,
)?;
```

`ColorMap::sample` is piecewise-linear on the CPU. The renderer deliberately
quantizes a color map to a 256-entry RGBA8 lookup texture. Closely spaced stops
or HDR distinctions below that resolution cannot be preserved by the GPU
heatmap path.

Use `ScalarFieldSampling::Nearest` for exact texels and `Linear` for manual,
deterministic bilinear scalar sampling. Value-range endpoints and their
subtraction must be finite.

### 13. Targets, composition, and trails

`RenderTarget2d` dimensions are physical texture pixels. A typical multipass
frame renders an expensive layer into a target, then composes it onto the
surface using `BlendMode::Alpha`, `Additive`, or `Replace`.

Public colors are straight linear RGBA. Offscreen target storage is
premultiplied, and the composition shaders and blend states preserve that
contract. Do not manually premultiply a public `Color`.

`TrailBuffer2d` owns two ping-pong targets. Accumulation reads history from one
target, writes retained history and a fresh source into the other, then swaps
only after successful submission. Source/destination aliasing is rejected.
`clear_trail_buffer` clears both textures.

For a scalar field with a particle overlay, prefer
`render_layered_visualization`. It encodes heatmap, budgeted particles, and
surface composition with one command encoder and one queue submission.

### 14. Retained 3D stereometry

The retained 3D path is intentionally separate from 2D pseudo-depth:

```rust
use sim_engine::{
    Camera3d, LogicalViewport, Projection3d, Transform3d, Vec3, WorldLength,
};

let projection = Projection3d::perspective(
    std::f32::consts::FRAC_PI_3,
    16.0 / 9.0,
    WorldLength::new(0.1)?,
    WorldLength::new(100.0)?,
)?;
let camera = Camera3d::look_at(
    Vec3::new(0.0, 0.0, 5.0)?,
    Vec3::ZERO,
    Vec3::Y,
    projection,
)?;
let world = Transform3d::IDENTITY.transform_point(Vec3::X)?;
let projected = camera.project_world(
    world,
    LogicalViewport::new(1280.0, 720.0)?,
)?;

# let _ = projected;
# Ok::<(), Box<dyn std::error::Error>>(())
```

Build immutable topology once, retain it on the GPU, and update only object
transforms during animation:

```rust,ignore
let topology = Mesh3d::with_display_edges(vertices, triangles, edges)?;
let retained = renderer.create_mesh3d(topology)?;
let logical_viewport = LogicalViewport::new(logical_width, logical_height)?;
let target = renderer.create_render_target3d(width, height, logical_viewport)?;

let wireframe = WireframeStyle3d::visible(
    Color::WHITE,
    LogicalPixels::new(2.0)?,
)?
.with_hidden(
    Color::rgb(0.45, 0.55, 0.70),
    LogicalPixels::new(1.25)?,
    LogicalPixels::new(7.0)?,
    LogicalPixels::new(5.0)?,
)?;
let style = MeshStyle3d::surface(SurfaceStyle3d::opaque(surface_color)?)
    .with_wireframe(wireframe);
let mut scene = Scene3d::new(Color::BLACK)?;
let object = scene.try_push(&retained, Transform3d::IDENTITY, style)?;

scene.set_transform(object, next_transform)?;
let report = renderer.render_scene3d_to_target(&target, &scene, camera)?;
renderer.compose_render_target(
    target.color_target(),
    BlendMode::Replace,
    1.0,
    Color::BLACK,
)?;
```

Triangle indices define optional surfaces. Explicit `MeshEdge3d` values define
only mathematical display edges, so triangulation diagonals need not appear.
Edge-only meshes are valid. `Object3dId` is a stable opaque handle carrying
private scene provenance. A handle from another `Scene3d` returns
`ObjectNotFound` even when both objects have the same local numeric value.
`Scene3d::set_visible` hides an object without releasing retained topology.

Opaque surfaces write `Depth32Float`. Edge classification is conservative:
fragments occluded beyond a two-implementation-depth-unit tolerance receive a
logical-pixel dash pattern, while coplanar and sub-depth-resolution separations
resolve visible and solid. Host insertion order does not decide 3D visibility.

Every `RenderTarget3d` declares both physical texture dimensions and the
logical viewport represented by those texels. Their aspect ratios must match,
and the camera projection aspect must match the target logical aspect. This
keeps edge width stable for native, downsampled, and supersampled targets.

Display-edge segments are homogeneously clipped against all six frustum planes
before shader perspective division and screen-space expansion. A partially
visible edge is shortened; a fully clipped edge emits no fragments without
rejecting the rest of the frame.

Current 3D scope is deliberately focused: opaque surfaces, retained transforms,
hardware depth, solid visible edges, and dashed hidden edges. Translucent or
hatched sections, projected label anchors, text, and 3D picking are not in this
release.

### 15. Recovery

`recover_device_and_surface().await` replaces the device, queue, pipelines,
transient buffers, and renderer identity while reusing the surface. External
resources from the previous identity are rejected until restored.

| Resource | Restore method | Result |
| --- | --- | --- |
| `PreparedScene` | `restore_prepared_scene` | exact retained geometry |
| `DynamicMesh2d` | `restore_dynamic_mesh` | exact retained vertices/capacity |
| `ParticleField2d` | `restore_particle_field` | exact instances and budget |
| `ScalarFieldTexture` | `restore_scalar_field_texture` | exact scalar grid |
| `RenderTarget2d` | `restore_render_target` | empty target; redraw required |
| `TrailBuffer2d` | `restore_trail_buffer` | empty history; redraw required |
| `RetainedMesh3d` | `restore_mesh3d` | exact topology and display edges |
| `Scene3d` | `restore_scene3d` | stable IDs plus exact transform/style/visibility; shared meshes uploaded once |
| `RenderTarget3d` | `restore_render_target3d` | empty color/depth; redraw required |

For a retained 3D scene, restore the scene and target after device recovery:

```rust,ignore
renderer.recover_device_and_surface().await?;
let scene_report = renderer.restore_scene3d(&mut scene)?;
target = renderer.restore_render_target3d(&target)?;

// Previously stored Object3dId values remain valid in `scene`.
scene.set_visible(selected_object, true)?;
```

`restore_scene3d` is atomic at the scene boundary. It recreates every distinct
stale mesh once and commits replacements only after all uploads succeed, while
preserving object IDs, order, transforms, styles, visibility, and next-ID state.

CPU-retained resources can recreate their exact content. GPU-only targets and
history cannot reconstruct prior pixels. Recovery is exceptional; it is not a
normal quality or adapter switch. Previous logical devices enter a bounded
quarantine because immediate teardown crashes some native Linux drivers. The
default limit is four and can be configured from one through eight. Once full,
recovery returns `RecoveryLimitReached` before creating another device; inspect
`quarantined_device_count` and `remaining_device_recoveries` in diagnostics.

### 16. Performance guidance

- Prepare static scenes once.
- Use dynamic meshes for ready changing triangles.
- Use particle instancing for large point/circle populations.
- Put dense scalar fields in textures and update dirty regions only.
- Render expensive fields below surface resolution when quality permits.
- Stagger visualization cadence independently of simulation and presentation.
- Fuse common field/particle passes.
- Set hard particle memory, upload, visibility-check, and draw budgets.
- Benchmark release builds without VSync and record the concrete present mode.
- Report surface acquisition separately from renderer CPU time.

A display-limited frame rate is not renderer throughput. Surface acquisition
can wait for FIFO or compositor pacing while renderer CPU work remains small.
The current public metrics do not include GPU timestamp queries.

### 17. Examples

```bash
# Basic renderer integration
cargo run --release --example demo

# Menu with Fluid, Gas, Wave, and edge-case workloads
cargo run --release --example ui_demo -- --uncapped

# Bounded star-remnant gas/particle workload
cargo run --release --example star_remnant_stress -- --benchmark

# CPU-only particle-state baseline
cargo run --release --no-default-features --example particle_cpu_benchmark

# Independently rotating cube and octahedron with hidden edges
cargo run --release --example stereometry_3d -- --uncapped

# Animated cylinder volume and surface-area derivation
cargo run --release --example cylinder_derivation_3d -- --uncapped --benchmark
```

Interactive controls and benchmark flags are printed by each example at
startup.

## Part II: Engineering Reference

### 18. Architectural role

The public boundary is validated visual state:

```text
host domain/UI state
    -> bounded visual snapshot
    -> Scene / particles / scalar fields / meshes
    -> WgpuRenderer and GPU passes
    -> Linux presentation surface
    -> status, metrics, and diagnostics back to the host
```

The host decides what a particle, field, cube, or section means. Sim;Engine
decides how ready visual data is validated, transformed, clipped, uploaded,
composed, drawn, measured, and recovered.

### 19. Module map

| Module | Responsibility |
| --- | --- |
| `math.rs` | checked 2D vectors and rectangles |
| `color.rs` | linear color, sRGB byte conversion, palette |
| `easing.rs`, `tween.rs` | fallible visual interpolation |
| `camera.rs` | 2D camera, pseudo-depth, typed screen spaces |
| `scene.rs` | validated ordered 2D command stream and styles |
| `field.rs` | finite scalar grid and CPU color-map contracts |
| `particle.rs` | renderer-independent particle visual state |
| `pseudo3d.rs` | checked 3D math, transforms, and CPU projection |
| `mesh3d.rs` | retained topology and edge/style contracts |
| `renderer/config.rs` | surface mode, DPI, renderer options, recovery setup |
| `renderer/tessellation.rs` | 2D scene command to triangle conversion |
| `renderer/visualization.rs` | fused scientific visualization path |
| `renderer/mesh3d.rs` | retained mesh resources and depth/edge passes |
| `renderer/primitive.wgsl` | 2D, particle, heatmap, and composition shaders |
| `renderer/mesh3d.wgsl` | 3D projection and screen-space edge expansion |

The entire renderer module is behind the `wgpu` feature. CPU-side contracts
remain testable without it.

### 20. Coordinate and projection model

The 2D transform is conceptually:

```text
world position + pseudo-depth
    -> camera-relative projection
    -> logical screen pixels
    -> physical scissor/texture pixels where required
    -> normalized device coordinates
```

The vertex shader receives compact camera rows mapping relative world X/Y and
scalar depth into logical screen X/Y. CPU validation checks geometry extents
against the same arithmetic envelope before submission. Lines retain
logical-pixel width by carrying a screen-extrusion direction separately from
world position.

The retained 3D transform is explicit:

```text
model point
    -> Transform3d
    -> Camera3d view basis
    -> Projection3d clip coordinates
    -> normalized depth and logical-screen position
```

The 3D convention is right-handed with positive Y up. Cameras look along local
negative Z; exposed view depth is positive distance forward. Large finite
vector operations use wider intermediates before checked `f32` output.

### 21. Color and alpha model

- Public `Color` is straight linear RGBA.
- Byte constructors decode sRGB to linear light.
- Render-bound colors require every channel in `0.0..=1.0`.
- Scene vertices remain linear through tessellation.
- Surface formats apply their configured output conversion.
- Offscreen target storage is premultiplied alpha.
- Composition shaders and blend states preserve that premultiplied storage.
- `Color::clamp` is explicit sanitization, not implicit scene validation.
- GPU color maps are deliberately quantized to 256 RGBA8 samples.

### 22. Scene and tessellation invariants

`Scene` owns a validated background, an ordered command list, temporary clip
and pseudo-depth state, and monotonically increasing insertion order. Accepted
commands capture immutable primitive/style data plus layer, insertion order,
depth, and optional clip.

Insertion checks source finiteness, drawability, styles, derived bounds,
gradient arithmetic, and operations that can overflow despite finite inputs.
Fallible methods preserve rejection reasons. Sorting is stable by layer and
never depends on pseudo-depth.

The general scene path tessellates on the CPU:

- circles become triangle fans;
- rectangles become fans or rounded sectors;
- lines become screen-extruded strips with round caps;
- polylines share joins and emit only two end caps;
- gradients are sampled at generated vertices;
- shadows generate separate offset geometry.

If late tessellation still cannot emit an accepted optional command, that loss
is visible in `TessellationStats` rather than hidden behind a successful frame.

### 23. Renderer lifecycle and ownership

`WgpuRenderer` owns one surface, adapter, logical device, queue, surface
configuration, pipelines, uniforms, transient scene buffers, optional MSAA
target, and cached lookup resources.

Renderer-owned external resources store the identity of the logical device
that created them. Every operation checks that identity before touching GPU
handles. Cross-renderer use therefore becomes a structured error before wgpu
validation. `Object3dId` similarly carries private scene provenance.

Capacity-bearing APIs validate integer arithmetic, host byte budgets, and active
device buffer or texture limits before allocation. Mutating fallible methods
validate first and replace retained state only after all checks pass.

### 24. GPU path internals

#### Streaming scenes

The renderer clears reusable CPU storage, tessellates commands, validates
camera/geometry arithmetic, grows a transient vertex buffer when required,
uploads vertices, acquires the surface, encodes clipped batches, submits, and
presents.

#### Prepared scenes

Preparation creates an immutable dedicated GPU buffer and retains a CPU vertex
snapshot for recovery. Rendering reuses geometry and only updates camera state.

#### Dynamic meshes

The resource retains a CPU copy and capacity-managed triangle buffer. Full
updates grow amortized capacity; aligned range updates reuse it. Geometry
extents are recomputed after mutation.

#### Particle fields

All validated instances stay on the CPU. Rendering tests circle/viewport
intersection, uniformly samples candidates when visibility checks are capped,
compacts the selected list, performs one upload, and issues one instanced draw.
GPU allocation and upload are proportional to the budget rather than the full
host population.

#### Scalar fields

The renderer stores an `R32Float` texture plus a retained CPU grid. Full and
rectangular updates are validated before queue writes. Heatmap shaders map a
finite value range through a cached lookup texture.

#### Retained 3D

Immutable vertex/index/edge topology is mirrored into GPU buffers and retained
on the CPU for recovery. Scene objects store scene-provenance IDs and
independent model transforms. Opaque surfaces populate color and depth. Display
edges are homogeneously clipped, conservatively classified against depth,
rendered dashed when hidden beyond the coplanar tolerance, and rendered solid
when visible. Edge expansion uses the target's logical-to-physical ratio rather
than the window DPI.

Mesh upload preflights vertex, index, and edge counts, checked byte sizes,
draw-count representation, and the active device's `max_buffer_size` before
allocating conversion staging memory. Staging vectors use fallible reservation
and report `HostAllocationFailed`. GPU buffer creation still follows wgpu's
device-error model and is not presented as a catchable system-OOM boundary.

### 25. Validation philosophy

The nearest public boundary rejects:

- NaN and infinity;
- prohibited zero or negative dimensions, radii, zoom, and scale;
- derived overflow from otherwise finite inputs;
- invalid gradient or value-range arithmetic;
- non-normalized render-bound colors;
- filled scalar allocations beyond the active host byte budget;
- allocation beyond active device limits;
- resource/renderer identity mismatch;
- update regions outside retained state;
- invalid opacity and composition aliasing;
- unsafe camera, near-plane, perspective-divide, or edge-style arithmetic.

This is a behavioral contract: an error should identify invalid required
visual state before it silently becomes different pixels.

### 26. Async and threading

The renderer is designed to be owned by the host render/event-loop thread.
Initialization and recovery are async because adapter and device requests are
async. Ordinary resource mutations and drawing are synchronous submissions.

The engine does not create a simulation scheduler or background render thread.
Async simulation is useful only when snapshot and synchronization cost is
smaller than the work it overlaps. Making individual scene mutations async
would add coordination overhead without improving GPU submission.

### 27. API stability policy

Sim;Engine is pre-1.0. Minor versions may contain intentional source-breaking
changes while real consumers exercise the contracts. Such changes must be
listed in `CHANGELOG.md` with migration guidance.

Patch releases preserve these behavioral contracts:

- invalid or overflowing required input is rejected structurally;
- coordinate spaces are not silently interchanged;
- pseudo-depth does not reorder a 2D layer;
- public colors are straight linear RGBA and target alpha is premultiplied;
- GPU resources reject foreign renderer identities;
- recovery behavior and retained snapshots match their documentation;
- failed updates do not partially mutate retained state;
- the crate accepts visual state and does not own application domain rules.

Public fields are avoided so validation, units, transforms, and future
representation changes remain evolvable. New public paths need a real consumer,
boundary validation, core and GPU tests where applicable, memory accounting,
recovery behavior, and a valid no-default-features build.

The project will not claim 1.0 until its supported platform/backend matrix,
recovery behavior, performance budgets, public documentation, and release
automation are repeatable.

### 28. Known boundaries

- Linux with Vulkan is the only release-gated platform/backend contract.
- A Vulkan adapter is supported for 0.1 only when the mandatory semantic
  fixture passes on that concrete adapter/driver. CI records Mesa software
  evidence and the v0.1.0 release evidence records Intel Mesa; untested
  AMD/NVIDIA drivers are not silently certified by those results.
- The crate is pre-1.0.
- Text shaping and glyph caching are not implemented.
- Retained 3D supports opaque surfaces and depth-classified edges, not section
  materials, projected anchors, labels, or picking.
- Renderer timing is CPU-side; public GPU timestamps are not available.
- Independent multi-window recovery is not yet proven.
- Render-target and trail pixels cannot be reconstructed after device loss.

### 29. Verification and contribution gate

The complete local Linux release gate is:

```bash
./scripts/linux_release_gate.sh
```

It checks formatting, Rust 1.90 compatibility, all targets with and without
default features, strict clippy, doctests, warning-free rustdoc, a mandatory
Vulkan semantic GPU readback fixture with backend assertion, `git diff --check`,
and the offline package boundary. The GPU step writes
`target/linux-vulkan-adapter.txt`; CI publishes the same manifest as the
`linux-vulkan-adapter` artifact. The manifest names backend, adapter type,
vendor/device IDs, driver, and driver version for the exact semantic run.

The gate must run from a clean worktree. Hardware performance or recovery
claims must additionally name the Linux adapter, backend, driver, workload,
present mode, and measurement method.