doc

lib/src/shaders/README.md

@@ -4,18 +4,25 @@
 
 Contains WGSL shader source files used by the PipelineCache module. These are loaded at runtime from disk when referenced by their registered ID in PipelineCache.register_shader(). If a file is missing, PipelineCache falls back to the embedded BASIC_SHADER constant defined in utils::conf.
 
+## Files
+
 | File | Purpose |
 |------|---------|
-| **basic_shader.wgsl** | Default vertex/fragment shader pair (vs_main / fs_main entry points) with position, normal, UV, and color attributes matching the Vertex struct layout. |
+| **basic_shader.wgsl** | Default vertex/fragment shader pair (vs_main / fs_main entry points) with position, uv, and color attributes. |
 
-## Shader Contract
+## Shader Contract (basic_shader.wgsl)
 
-The WGSL shader must define:
+The WGSL shader defines:
 
-- `@vertex fn vs_main() -> @builtin(position) vec4<f32>` — vertex entry point
-- `@fragment fn fs_main() -> @location(0) vec4<f32>` — fragment entry point writing RGBA output
-- Vertex input attributes matching the 56-byte stride of resources::Vertex:
-  - `@location(0)` → position `[f32; 3]` (offset 0)
-  - `@location(1)` → normal `[f32; 3]` (offset 12)
-  - `@location(2)` → uv `[f32; 2]` (offset 24)
-  - `@location(3)` → color `[f32; 4]` (offset 32)
+- `@vertex fn vs_main(model: VertexInput) -> VertexOutput` — vertex entry point
+- `@fragment fn fs_main(in: VertexOutput) -> @location(0) vec4<f32>` — fragment entry point writing RGBA output
+
+### Vertex Input Layout
+
+| Location | Attribute | Type | Offset (bytes) |
+|----------|-----------|------|----------------|
+| 0 | position | vec3<f32> | 0 |
+| 1 | uv | vec2<f32> | 12 |
+| 2 | color | vec3<f32> | 24 |
+
+**Note**: This shader uses a 39-byte vertex stride (3+2+3 floats). It does NOT include normal data or alpha channel interpolation — it outputs fully opaque geometry with per-vertex color passthrough. This differs from the full `Vertex` struct layout (56 bytes with normal + alpha) defined in resources::Vertex; if a full shader matching the Vertex struct is needed, extend this shader accordingly.

lib/src/shaders/basic_shader.wgsl

@@ -1,4 +1,22 @@
 //! # Basic Shader Module
+//!
+//! Default vertex/fragment shader pair used by PipelineCache when no external .wgsl file is found.
+//! This shader implements a simple unlit rendering path: passes through position and color attributes
+//! from VertexInput to fragment output, producing flat-colored geometry without lighting calculations.
+//!
+//! ## Shader Contract
+//! Must define entry points matching PipelineCache::build_pipeline():
+//! - @vertex fn vs_main(model: VertexInput) -> VertexOutput
+//!   - model.position → @location(0), vec3<f32>, offset 0 bytes in vertex buffer
+//!   - model.uv → @location(1), vec2<f32>, offset 12 bytes in vertex buffer
+//!   - model.color → @location(2), vec3<f32>, offset 24 bytes in vertex buffer
+//! - @fragment fn fs_main(in: VertexOutput) -> @location(0) vec4<f32>
+//!   - Writes RGBA output where alpha is hardcoded to 1.0 (fully opaque).
+//!
+//! ## Technical Notes
+//! - No normal or UV interpolation — this is an unlit shader that directly outputs the per-vertex color.
+//! - The clip_position is computed as vec4<f32>(position, 1.0), assuming position is already in NDC space.
+
 struct VertexInput {
     @location(0) position: vec3<f32>,
     @location(1) uv: vec2<f32>,