doc

docs/user/quickstart.md

@@ -0,0 +1,131 @@
+# Quickstart
+
+Goal: a window showing an object, with the render loop handled by the library. You will only
+write three things: a struct implementing `AppHandler`, your scene declaration in `setup()`,
+and your `main()`.
+
+## Prerequisites
+
+- A recent Rust toolchain (the library is **edition 2024** — run `rustup update` if needed).
+- A windowing environment (X11/Wayland on Linux, or native macOS/Windows).
+- WSG is **not published on crates.io**: it is consumed by file path.
+
+## 1. Dependencies
+
+In your application's `Cargo.toml`:
+
+```toml
+[dependencies]
+wsg-lib = { path = "/path/to/wsg/lib" }
+pollster = { version = "1", features = ["macro"] }   # for #[pollster::main] (AppBuilder is async)
+```
+
+## 2. The minimal application
+
+This snippet is the [`simple`](../../lib/examples/simple.rs) example from the repo, almost
+verbatim: a flat two-tone quad, rendered automatically every frame.
+
+```rust
+use wsg_lib::app::AppBuilder;
+use wsg_lib::resources::Geometry;
+use wsg_lib::utils::WsgError;
+use wsg_lib::AppHandler;
+
+struct MyQuad;
+
+impl AppHandler for MyQuad {
+    fn setup(&mut self, app: &mut wsg_lib::App) {
+        // Flat 2D: the `standard` shader in unlit mode returns the vertex color as-is.
+        app.renderer_mut().set_unlit(true);
+        app.scene
+            .register_shader("standard", wsg_lib::utils::STANDARD_SHADER_PATH)
+            .unwrap();
+
+        let geometry = Geometry::new(vec![
+            [-0.5,  0.5, 0.0],
+            [ 0.5,  0.5, 0.0],
+            [ 0.5, -0.5, 0.0],
+            [-0.5, -0.5, 0.0],
+        ])
+        .with_normals(vec![[0.0, 0.0, 1.0]; 4])
+        .with_colors(vec![
+            [1.0, 0.0, 0.0, 1.0], // red
+            [0.0, 1.0, 0.0, 1.0], // green
+            [0.0, 0.0, 1.0, 1.0], // blue
+            [1.0, 1.0, 0.0, 1.0], // yellow
+        ])
+        .with_indices(vec![0, 1, 2, 0, 2, 3]);
+
+        // `None`: the scene injects its default material (`standard`) at render time.
+        app.scene.create_mesh("quad_mesh", geometry, None).unwrap();
+        app.scene.add_entity("quad", "quad_mesh").unwrap();
+    }
+}
+
+#[pollster::main]
+async fn main() -> Result<(), WsgError> {
+    let app = AppBuilder::new().title("WSG Simple").build().await?;
+    app.run(MyQuad)
+}
+```
+
+Note: **no `wgpu` or `winit` imports** — the `App` facade encapsulates them entirely.
+
+## 3. What the library does for you
+
+The full lifecycle, as driven by `App::run` (technical details in
+[FRAME_LOOP](../tech/FRAME_LOOP.md)):
+
+```
+AppBuilder::build()          creates the event loop
+        │
+App::run(handler)            starts the loop
+        │
+resumed (winit)              window + GPU (Instance/Surface/Adapter/Device/Queue) + Renderer
+        │
+handler.setup(&mut app)      ← you declare the scene here (once, GPU ready)
+        │
+        ▼  per frame, in a loop:
+        input.begin_frame()   current frame's keyboard/mouse state
+handler.update(&mut app)      ← your logic (motion, input, …)
+        input.end_frame()
+handler.render(app, frame)    ← default: app.render_scene(frame.view())
+        │                       (the whole scene is drawn automatically, one pass per frame)
+        └─ present → next frame
+```
+
+So you implement:
+
+| Hook | When | Role | Default |
+|------|-------|------|---------|
+| `setup(&mut self, app)` | once, GPU ready | declare shaders, materials, textures, meshes, entities, lights, camera | empty |
+| `update(&mut self, app)` | every frame, before render | animate: transforms, input, lights… | empty |
+| `render(&mut self, app, frame)` | every frame, after update | **default**: draws the whole scene; override for custom rendering | `app.render_scene(frame.view())` |
+
+Golden rule: **mutate the scene in `update()`** (and `setup()`), only read it in `render()`
+(model detailed in [ARCHI_RENDU](../tech/ARCHI_RENDU.md)).
+
+## 4. Running it
+
+From the WSG repo root (the examples live in `lib/examples/`):
+
+| Command | What you see |
+|----------|--------------|
+| `cargo run -p wsg-lib --example simple` | the quad above (flat 2D, unlit) |
+| `cargo run -p wsg-lib --example cube` | a textured, lit, spinning cube (3D) |
+| `cargo run -p wsg-lib --example demo` | the full showcase: 6 primitives + lights + shadows + orbital camera |
+
+For your own application: create a crate, add the §1 dependency, paste the §2 code into
+`src/main.rs`, and `cargo run`.
+
+## 5. Where to go next
+
+- Want a 3D object? → [Meshes](meshes.md)
+- Want to change the look / add a texture? → [Materials & textures](materials.md)
+- Want lights? → [Lights](lights.md)
+- Want to see everything at once? → the `demo` example ([Examples](examples.md))
+
+## Links
+
+- [User README](README.md) · [Meshes](meshes.md) · [Examples](examples.md)
+- [Root README](../../README.md) · [FRAME_LOOP](../tech/FRAME_LOOP.md) · [ARCHI_APP](../tech/ARCHI_APP.md)