Renderer setup, plus some actual early speed numbers

readme.md

@@ -17,10 +17,54 @@ Rendering goes through wgpu. On a machine without a GPU, the same shaders run
 on the CPU through Mesa's lavapipe (`vulkan-swrast` on Arch,
 `mesa-vulkan-drivers` on Debian and Ubuntu).
 
+## Usage
+
+```rust
+use resolved::nalgebra::{UnitQuaternion, Vector3};
+use resolved::radiometry::AU;
+use resolved::{CameraConfig, Mesh, Pose, Renderer, Scene, Target};
+
+# fn main() -> Result<(), resolved::Error> {
+// Setup, once: device, shaders, spectra folded into the camera's channels.
+let mut renderer = Renderer::new(CameraConfig::example(), Default::default())?;
+
+// A model, uploaded once. Usually `Mesh::load(path, &options)` on an STL or glTF.
+let stl = "solid panel
+facet normal 0 0 0
+outer loop
+vertex 0 -1 -1
+vertex 0 1 -1
+vertex 0 0 1
+endloop
+endfacet
+endsolid panel";
+let panel = renderer.load_model(&Mesh::from_stl(&mut std::io::Cursor::new(stl), "panel", &Default::default())?)?;
+
+// Each step: inertial positions in meters, Earth at the origin.
+let target = Vector3::new(7.0e6, 0.0, 0.0);
+let scene = Scene {
+    earth_attitude: UnitQuaternion::identity(),
+    sun: Vector3::new(AU, 0.0, 0.0),
+    moon: Vector3::new(0.0, 3.844e8, 0.0),
+    targets: vec![Target { model: panel, pose: Pose::new(target, UnitQuaternion::identity()) }],
+};
+let observer = Pose::looking_at(target + Vector3::new(20.0, 0.0, 0.0), target, Vector3::z()).unwrap();
+
+let pending = renderer.submit(&scene, &observer)?;
+// ... the simulation's own work for this step overlaps the GPU's here ...
+let frame = pending.wait()?;
+
+// 12-bit DN, channels r, g, b interleaved. The panel faces the Sun and the camera.
+assert!(frame.dn_at(960, 540, 1) > 1000);
+# Ok(())
+# }
+```
+
 ## Status
 
-Early development. Nothing renders yet. The work is tracked as Gitea
-milestones, each split into one issue per change:
+M1 in progress: the library renders Earth, Moon, Sun and targets to DN
+through `Renderer`; the CLI and benchmarks are still to come. The work is
+tracked as Gitea milestones, each split into one issue per change:
 
 | Milestone | Scope |
 |---|---|