Jérôme Bousquié
132 lines
4.7 KiB
Markdown
132 lines
4.7 KiB
Markdown
# 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)
|