Jérôme Bousquié
87 lines
3.3 KiB
Markdown
87 lines
3.3 KiB
Markdown
# WSG - WGPU Simple Graphics Library
|
|
|
|
WSG is a Rust library that wraps [wgpu](https://github.com/gfx-rs/wgpu) to provide a simple, declarative API for 3D graphics. It abstracts away the complexity of managing GPU resources while exposing low-level primitives for advanced users.
|
|
|
|
|
|
NOTE : the development version is currently unstable and the examples described below may not work as expected.
|
|
|
|
## What it does
|
|
|
|
WSG provides two complementary workflows:
|
|
|
|
### Declarative workflow (recommended)
|
|
|
|
Register your scene's resources and entities before the render loop starts, then iterate them each frame:
|
|
|
|
```rust
|
|
use wsg_lib::{App, AppHandler};
|
|
use wsg_lib::resources::{Mesh, Material, Vertex};
|
|
|
|
struct MyGame { /* ... */ }
|
|
|
|
impl AppHandler for MyGame {
|
|
fn render(&mut self, app: &mut App) {
|
|
// Draw every entity registered in app.scene
|
|
for (_, mesh, material) in app.scene.iter_entities() {
|
|
app.renderer.render(app.context.get_next_frame().view(), mesh, material);
|
|
}
|
|
}
|
|
}
|
|
|
|
#[pollster::main]
|
|
async fn main() -> Result<(), wsg_lib::utils::WsgError> {
|
|
let mut app = AppBuilder::new().build().await?;
|
|
|
|
// Declare resources
|
|
app.cache.register_shader("basic", "assets/shaders/basic_shader.wgsl")?;
|
|
let vertices: [Vertex; 4] = [/* ... */];
|
|
let indices: [u16; 6] = [0, 1, 2, 0, 2, 3];
|
|
let mesh = Mesh::new(app.context.device(), &vertices, Some(&indices));
|
|
let material = Material::new(app.renderer.format(), "basic", &mut app.cache);
|
|
|
|
app.scene.add_mesh("quad", Arc::new(mesh))?;
|
|
app.scene.add_material("mat", Arc::new(material))?;
|
|
app.scene.add_entity("my_quad", "quad", "mat")?;
|
|
|
|
// Run the render loop
|
|
app.run(MyGame {})
|
|
}
|
|
```
|
|
|
|
### Manual workflow
|
|
|
|
For fine-grained control, bypass the Scene facade entirely and manipulate Context, Renderer, and PipelineCache directly through their public APIs.
|
|
|
|
## Architecture overview
|
|
|
|
WSG follows a two-layer architecture:
|
|
|
|
- **Manager layer (Context)** — owns GPU hardware lifecycle (Instance → Surface → Adapter → Device → Queue). Created once at startup.
|
|
- **Executor layer (Renderer)** — orchestrates draw calls per frame by binding Materials + Meshes into RenderPasses. Dynamic, changes each frame.
|
|
|
|
The high-level `App` facade ties everything together, automating window lifecycle, event processing, and frame presentation. Users implement the `AppHandler` trait to inject game logic.
|
|
|
|
## Quick reference
|
|
|
|
| Concept | Type | Responsibility |
|
|
|---------|------|---------------|
|
|
| App | Facade | Window lifecycle + event loop + render automation |
|
|
| AppHandler | Trait | User-defined update/render callbacks |
|
|
| Scene | Struct | Resource depot + entity graph (declarative) |
|
|
| Context | Struct | GPU hardware lifecycle (Manager) |
|
|
| Renderer | Struct | Draw call orchestration (Executor) |
|
|
| Material | Struct | Shader ID → compiled RenderPipeline |
|
|
| Mesh | Struct | Persistent GPU geometry container |
|
|
| Vertex | Struct | CPU-side vertex attribute tuple |
|
|
| PipelineCache | Struct | Shader compilation cache |
|
|
| Frame | Struct | Per-frame RAII wrapper for surface texture + view |
|
|
|
|
## Getting started
|
|
|
|
```bash
|
|
cargo add wsg-lib # Add the dependency
|
|
# Then build your app following the declarative example above
|
|
```
|
|
|
|
For details on the architecture and internal modules, see [ARCHI_APP](docs/ARCHI_APP.md).
|