# 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.

## 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).