suppression contradictions

README.md

@@ -11,7 +11,7 @@ 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:
+Register your scene's resources and entities once at startup, then let WSG handle rendering each frame via a GPU-Driven pipeline (Compute Pass → Render Pass):
 
 ```rust
 use wsg_lib::{App, AppHandler};
@@ -20,11 +20,13 @@ use wsg_lib::resources::{Mesh, Material, Vertex};
 struct MyGame { /* ... */ }
 
 impl AppHandler for MyGame {
+    fn update(&mut self, _app: &mut App) {
+        // Modify scene state (transformations, entities) — only place allowed for mutations
+    }
+
     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);
-        }
+        // WSG automatically runs Compute Pass → Render Pass on the current scene.
+        // No manual iteration needed — draw_indexed_indirect handles everything.
     }
 }
 
@@ -32,7 +34,7 @@ impl AppHandler for MyGame {
 async fn main() -> Result<(), wsg_lib::utils::WsgError> {
     let mut app = AppBuilder::new().build().await?;
 
-    // Declare resources
+    // Declare resources (once, before the render loop)
     app.cache.register_shader("basic", "assets/shaders/basic_shader.wgsl")?;
     let vertices: [Vertex; 4] = [/* ... */];
     let indices: [u16; 6] = [0, 1, 2, 0, 2, 3];
@@ -43,7 +45,7 @@ async fn main() -> Result<(), wsg_lib::utils::WsgError> {
     app.scene.add_material("mat", Arc::new(material))?;
     app.scene.add_entity("my_quad", "quad", "mat")?;
 
-    // Run the render loop
+    // Run the render loop — WSG handles Compute Pass + Render Pass each frame
     app.run(MyGame {})
 }
 ```
@@ -54,10 +56,10 @@ For fine-grained control, bypass the Scene facade entirely and manipulate Contex
 
 ## Architecture overview
 
-WSG follows a two-layer architecture:
+WSG follows a GPU-Driven 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.
+- **Executor layer (Renderer)** — orchestrates a two-pass pipeline per frame: Compute Pass (World Matrix calculation + Frustum Culling → Indirect Draw Buffer) then Render Pass (`draw_indexed_indirect`). 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.
 
@@ -69,7 +71,7 @@ The high-level `App` facade ties everything together, automating window lifecycl
 | 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) |
+| Renderer | Struct | Two-pass pipeline: Compute + Render |
 | Material | Struct | Shader ID → compiled RenderPipeline |
 | Mesh | Struct | Persistent GPU geometry container |
 | Vertex | Struct | CPU-side vertex attribute tuple |