refactor renderer responsable + docs + schema

lib/pipeline_cache.rs

@@ -22,21 +22,26 @@ use std::sync::Arc;
 /// Shader pipeline cache: maps (shader_id, format) keys to compiled RenderPipelines.
 /// Ensures each unique shader+format combination is compiled at most once; subsequent requests return cached instances.
 pub struct PipelineCache {
-    /// Cached pipelines keyed by their shader identifier string.
+    /// Cached pipelines keyed by their shader identifier string. Multiple Materials sharing the same ID share one Arc-wrapped pipeline.
     pipelines: HashMap<String, Arc<wgpu::RenderPipeline>>,
+    /// Maps shader IDs to file paths on disk for WGSL loading in `load_shader()`.
     shader_paths: HashMap<String, String>,
 }
 
 impl PipelineCache {
     /// Creates an empty pipeline cache with no pre-loaded shaders or pipelines.
+    /// Called at application startup before any Material creation. Shader paths must be registered via register_shader() first.
     pub fn new() -> Self {
         Self {
             pipelines: HashMap::new(),
+            // Maps shader IDs to file paths on disk for WGSL loading in load_shader().
+            // When a path exists, it reads from it; otherwise falls back to BASIC_SHADER constant.
             shader_paths: HashMap::new(),
         }
     }
-    /// Enregistre un chemin de shader associé à un ID.
-    /// Renvoie Ok(id) si réussi, ou une erreur si l'ID existe déjà.
+    /// Registers an external WGSL shader file path associated with a given ID.
+    /// Inputs: id (unique key for this shader), path (filesystem path to .wgsl file).
+    /// Returns Ok(id) on success or Err if the ID is already registered. Called during scene setup to register custom shaders.
     pub fn register_shader(&mut self, id: &str, path: &str) -> Result<String, String> {
         if self.shader_paths.contains_key(id) {
             return Err(format!("ID '{}' already exists.", id));
@@ -45,15 +50,14 @@ impl PipelineCache {
         Ok(id.to_string())
     }
 
-    /// Supprime un ID et son chemin associé.
-    /// Renvoie Ok(id) si réussi, ou une erreur si l'ID est inconnu.
+    /// Unregisters a shader by its ID, removing both the path reference and any cached compiled pipeline.
+    /// Inputs: id (the shader identifier to remove).
+    /// Returns Ok(id) on success or Err if the ID does not exist. Called when a shader should be freed from GPU memory.
     pub fn unregister_shader(&mut self, id: &str) -> Result<String, String> {
         if self.shader_paths.remove(id).is_none() {
             return Err(format!("ID '{}' does not exist.", id));
         }
-        // Optionnel : tu pourrais aussi supprimer le pipeline compilé du cache
-        // si tu veux libérer la mémoire GPU immédiatement :
-        self.pipelines.remove(id);
+                // Remove cached pipeline so GPU memory is freed (wgpu drops it automatically)
 
         Ok(id.to_string())
     }