WSG - WGPU Simple Graphics Library

WSG is a Rust library that wraps 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:

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

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.