wsg/README.md

WSG — WGPU Simple Graphics Library

WSG (WGPU Simple Graphics) est une bibliothèque Rust qui wrap wgpu et winit pour dessiner en 3D sans toucher wgpu directement.

Ce que vous obtenez

• Une fenêtre 3D en ~30 lignes — pas de wgpu, pas de winit dans votre code
• Éclairage Phong (directional, point, spot) + ombres portées (shadow mapping)
• HDR + Tone Mapping (ACES Filmic / Reinhard) — opt-in, zéro coût si désactivé
• Pipeline GPU-driven — world matrices + frustum culling sur le GPU, indirect draws
• LOD (Level of Detail) — dégradation automatique de la géométrie selon la distance
• Primitives procédurales — cube, sphère, cylindre, cône, tore, plan
• Import de fichiers — parser OBJ intégré (glTF en cours)
• Caméra orbitale + input unifié (clavier/souris)
• LOD, culling, HDR, ombres : tout est opt-in — ce que vous n'activez pas ne coûte rien

Forces

Force	Détail
Zéro wgpu dans votre code	L'API déclarative (AppBuilder + AppHandler) encapsule tout
Opt-in = zéro coût	Un effet non activé n'alloue rien, n'exécute rien
Features Cargo	Ne compilez que les primitives/import dont vous avez besoin
Un seul shader	Le standard shader (Phong) couvre 90 % des cas ; mode unlit pour la 2D
GPU-driven	Le CPU envoie des transforms, le GPU fait le reste (matrices, culling, draws)

Quickstart

use wsg_lib::prelude::*;
use wsg_lib::app::AppBuilder;
use wsg_lib::utils::WsgError;

struct MaScene;

impl AppHandler for MaScene {
    fn setup(&mut self, app: &mut wsg_lib::App) {
        app.scene
            .register_shader("standard", wsg_lib::utils::STANDARD_SHADER_PATH)
            .unwrap();
        app.scene
            .create_material("mat", "standard", None)
            .unwrap();

        // Un cube lit par Phong, posé au-dessus d'un plan
        app.scene
            .create_mesh("cube", cube(1.0), Some("mat"))
            .unwrap();
        app.scene
            .add_entity("my_cube", "cube")
            .unwrap();

        app.scene
            .create_mesh("ground", plane(10.0, 10.0, 1, 1), Some("mat"))
            .unwrap();
        app.scene
            .add_entity("floor", "ground")
            .unwrap();
    }
}

fn main() -> Result<(), WsgError> {
    let mut app = AppBuilder::new()
        .title("Ma scène WSG")
        .with_hdr(ToneMapper::Aces)  // optionnel : HDR + tone mapping
        .build()?;
    app.run(MaScene);
    Ok(())
}

[dependencies]
wsg-lib = { path = "../lib" }
pollster = { version = "1", features = ["macro"] }

cargo run --example demo   # le showcase complet (6 primitives, 3 lumières, ombres, HDR)

Fonctionnalités

Catégorie	Ce qui est disponible
Géométrie	6 primitives procédurales + import OBJ + Geometry custom
Rendu	Phong (lit), unlit (2D flat), HDR + tone mapping (ACES/Reinhard)
Lumières	Directional, point, spot (8 max) + ambient
Ombres	Shadow mapping (directional/spot), slope-scaled bias, PCF
LOD	Décimation quadric auto, hystérésis, 1 buffer multi-niveaux
GPU-driven	Compute pass (matrices + culling) → indirect draws
Caméra	Orbitale (drag/zoom/reset) + presets (front/side/top)
Input	Clavier (pressed/held/released), souris (delta, scroll, boutons)
Textures	RGBA8 (de bytes, de fichier, placeholder blanc)

Documentation

Où	Quoi
docs/user/	Guide utilisateur (EN) — comment utiliser l'API, pas à pas
docs/tech/	Architecture interne (FR) — décisions, specs, cibles
docs/ROADMAP.md	Feuille de route (phases 1-5 ✅, phase 6 en cours)
docs/PLAN.md	Livre de recette (historique des étapes)
cargo doc -p wsg-lib --no-deps	Référence API (rustdoc, 100 % couvert)

Exemples

Exemple	Ce qu'il montre
demo	Le showcase : 6 primitives, 3 lumières, ombres, HDR, LOD, caméra orbitale
cube	MVP 3D : un cube lit par Phong, texture checkerboard
simple	Minimal : un quad coloré en mode unlit (2D)
shadow_test	Ombres portées isolées
spot_test	Spotlight isolé
import	Import de fichier OBJ (feature import-obj)
manual	Workflow low-level (Context/Renderer/PipelineCache, sans App)

Features Cargo

# Default : toutes les primitives
wsg-lib = { path = "../lib" }

# Minimal : juste le cube
wsg-lib = { path = "../lib", default-features = false, features = ["prim-cube"] }

# Avec import OBJ
wsg-lib = { path = "../lib", features = ["import-obj"] }

Feature	Active
prim-cube, prim-plane, prim-sphere, prim-cylinder, prim-cone, prim-torus	Primitives
all-prims (default)	Les 6 primitives
import-obj	Parser Wavefront OBJ
import-gltf	glTF (stub)

Build

cargo build --workspace          # tout
cargo test --workspace           # 116 tests
cargo check --all-targets        # vérification rapide
cargo run -p wsg-lib --example demo   # lancer le showcase

Projet

• Langage : Rust 2024
• Dépendances : wgpu 30, winit 0.30, glam (math)
• Pas publié sur crates.io (dépendance par path)
• Status : MVP complet (phases 1-5 ✅), post-MVP en cours (phase 6)

---

Documentation détaillée (architecture, status, API reference, workflow manuel) : README_DETAILS.md