ajout material et pipeline_cache

lib/vertex.rs

@@ -1,7 +1,22 @@
+//! # Vertex Module
+//!
+//! Defines `Vertex`, the CPU-side data layout that is sent to the GPU as vertex attribute buffers.
+//! The struct's field order and offsets must exactly match the shader input attributes defined in
+//! PipelineCache::build_pipeline() — any mismatch will corrupt GPU rendering output.
+//!
+//! ## Technical Points
+//! - `#[repr(C)]` ensures fields are laid out contiguously without Rust padding reordering, matching C ABI.
+//! - `bytemuck::Pod + bytemuck::Zeroable` enables safe `cast_slice()` conversion for GPU buffer uploads.
+
+/// Per-vertex attribute tuple: position (3D), texture coordinate (2D), color (RGBA).
+/// Must match the vertex buffer layout in PipelineCache::build_pipeline() byte-for-byte.
 #[repr(C)]
 #[derive(Copy, Clone, Debug, bytemuck::Pod, bytemuck::Zeroable)]
 pub struct Vertex {
+    /// XYZ coordinates of this vertex in world space. Offset: 0 bytes.
     pub position: [f32; 3],
+    /// UV texture coordinates. Offset: 12 bytes (after 3 × f32 = 12 bytes).
     pub uv: [f32; 2],
-    pub color: [f32; 3],
+    /// RGBA color values. Offset: 20 bytes (after 5 × f32 = 20 bytes).
+    pub color: [f32; 4],
 }