[update] documentation to reflect new changes to the render context.

Author: vmarcella

docs/feature_roadmap_and_snippets.md

@@ -1,3 +1,20 @@
+---
+title: "Lambda RS: Immediate Feature Ideas and Example APIs"
+document_id: "feature-roadmap-snippets-2025-09-24"
+status: "living"
+created: "2025-09-24T00:00:00Z"
+last_updated: "2025-12-15T00:00:00Z"
+version: "0.2.0"
+engine_workspace_version: "2023.1.30"
+wgpu_version: "26.0.1"
+shader_backend_default: "naga"
+winit_version: "0.29.10"
+repo_commit: "71256389b9efe247a59aabffe9de58147b30669d"
+owners: ["lambda-sh"]
+reviewers: ["engine", "rendering"]
+tags: ["roadmap", "features", "api-design", "rendering"]
+---
+
 # Lambda RS: Immediate Feature Ideas + Example APIs
 
 This document proposes high‑impact features to add next to the Lambda RS
@@ -23,27 +40,34 @@ use lambda::render::{
 // Layout: set(0) has a uniform buffer at binding(0)
 let layout = BindGroupLayoutBuilder::new()
   .with_uniform(binding = 0, visibility = PipelineStage::VERTEX)
-  .build(&mut rc);
+  .build(rc.gpu());
 
 // Create and upload a uniform buffer
 let ubo = BufferBuilder::new()
   .with_length(std::mem::size_of::<Globals>())
   .with_usage(Usage::UNIFORM)
   .with_properties(Properties::CPU_VISIBLE)
   .with_label("globals")
-  .build(&mut rc, vec![initial_globals])?;
+  .build(rc.gpu(), vec![initial_globals])?;
 
 // Bind group that points the layout(0)@binding(0) to our UBO
 let group0 = BindGroupBuilder::new()
   .with_layout(&layout)
   .with_uniform(binding = 0, &ubo)
-  .build(&mut rc);
+  .build(rc.gpu());
 
 // Pipeline accepts optional bind group layouts
 let pipe = RenderPipelineBuilder::new()
   .with_layouts(&[&layout])
   .with_buffer(vbo, attributes)
-  .build(&mut rc, &pass, &vs, Some(&fs));
+  .build(
+    rc.gpu(),
+    rc.surface_format(),
+    rc.depth_format(),
+    &pass,
+    &vs,
+    Some(&fs),
+  );
 
 // Commands inside a render pass
 RC::SetPipeline { pipeline: pipe_id },
@@ -64,25 +88,25 @@ let texture = TextureBuilder::new_2d(TextureFormat::Rgba8UnormSrgb)
   .with_size(512, 512)
   .with_data(&pixels)
   .with_label("albedo")
-  .build(&mut rc);
+  .build(rc.gpu());
 
 let sampler = SamplerBuilder::new()
   .linear_clamp()
-  .build(&mut rc);
+  .build(rc.gpu());
 
 // Layout: binding(0) uniform buffer, binding(1) sampled texture, binding(2) sampler
 let layout = BindGroupLayoutBuilder::new()
   .with_uniform(0, PipelineStage::VERTEX | PipelineStage::FRAGMENT)
   .with_sampled_texture(1)
   .with_sampler(2)
-  .build(&mut rc);
+  .build(rc.gpu());
 
 let group = BindGroupBuilder::new()
   .with_layout(&layout)
   .with_uniform(0, &ubo)
   .with_texture(1, &texture)
   .with_sampler(2, &sampler)
-  .build(&mut rc);
+  .build(rc.gpu());
 
 RC::BindGroup { set: 0, group: group_id, offsets: &[] },
 ```
@@ -105,12 +129,23 @@ let pass = RenderPassBuilder::new()
      depth_compare = wgpu::CompareFunction::Less,
   )
   .with_msaa(samples = 4)
-  .build(&rc);
+  .build(
+    rc.gpu(),
+    rc.surface_format(),
+    rc.depth_format(),
+  );
 
 let pipe = RenderPipelineBuilder::new()
   .with_msaa(samples = 4)
   .with_depth_format(wgpu::TextureFormat::Depth32Float)
-  .build(&mut rc, &pass, &vs, Some(&fs));
+  .build(
+    rc.gpu(),
+    rc.surface_format(),
+    rc.depth_format(),
+    &pass,
+    &vs,
+    Some(&fs),
+  );
 ```
 
 ## 4) Indexed Draw + Multiple Vertex Buffers
@@ -140,13 +175,21 @@ let offscreen = RenderTargetBuilder::new()
   .with_color(TextureFormat::Rgba8UnormSrgb, width, height)
   .with_depth(TextureFormat::Depth32Float)
   .with_label("offscreen")
-  .build(&mut rc);
+  .build(rc.gpu());
 
 // Pass 1: draw scene into `offscreen`
-let p1 = RenderPassBuilder::new().with_target(&offscreen).build(&rc);
+let p1 = RenderPassBuilder::new().with_target(&offscreen).build(
+  rc.gpu(),
+  rc.surface_format(),
+  rc.depth_format(),
+);
 
 // Pass 2: sample offscreen color into swapchain
-let p2 = RenderPassBuilder::new().build(&rc);
+let p2 = RenderPassBuilder::new().build(
+  rc.gpu(),
+  rc.surface_format(),
+  rc.depth_format(),
+);
 
 // Commands
 RC::BeginRenderPass { render_pass: p1_id, viewport },
@@ -246,4 +289,3 @@ These proposals aim to keep Lambda’s surface area small while unlocking common
 workflows (texturing, uniforms, depth/MSAA, compute, multipass). I can begin
 implementing any of them next; uniform buffers/bind groups and depth/MSAA are
 usually the quickest wins for examples and demos.
-

docs/game_roadmap_and_prototype.md

@@ -3,13 +3,13 @@ title: "Lambda RS: Gaps, Roadmap, and Prototype Plan"
 document_id: "game-roadmap-2025-09-24"
 status: "living"
 created: "2025-09-24T05:09:25Z"
-last_updated: "2025-09-26T19:37:55Z"
-version: "0.2.0"
+last_updated: "2025-12-15T00:00:00Z"
+version: "0.3.0"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"
 shader_backend_default: "naga"
 winit_version: "0.29.10"
-repo_commit: "2e7a3abcf60a780fa6bf089ca8a6f4124e60f660"
+repo_commit: "71256389b9efe247a59aabffe9de58147b30669d"
 owners: ["lambda-sh"]
 reviewers: ["engine", "rendering"]
 tags: ["roadmap","games","2d","3d","desktop"]
@@ -53,22 +53,29 @@ Bind groups and uniforms (value: larger, structured GPU data; portable across ad
 // Layout with one uniform buffer at set(0) binding(0)
 let layout = BindGroupLayoutBuilder::new()
   .with_uniform(0, PipelineStage::VERTEX)
-  .build(&mut rc);
+  .build(rc.gpu());
 
 let ubo = BufferBuilder::new()
   .with_length(std::mem::size_of::<Globals>())
   .with_usage(Usage::UNIFORM)
   .with_properties(Properties::CPU_VISIBLE)
-  .build(&mut rc, vec![initial_globals])?;
+  .build(rc.gpu(), vec![initial_globals])?;
 
 let group = BindGroupBuilder::new(&layout)
   .with_uniform(0, &ubo)
-  .build(&mut rc);
+  .build(rc.gpu());
 
 let pipe = RenderPipelineBuilder::new()
   .with_layouts(&[&layout])
   .with_buffer(vbo, attrs)
-  .build(&mut rc, &pass, &vs, Some(&fs));
+  .build(
+    rc.gpu(),
+    rc.surface_format(),
+    rc.depth_format(),
+    &pass,
+    &vs,
+    Some(&fs),
+  );
 
 // Commands inside a pass
 RC::SetPipeline { pipeline: pipe_id };
@@ -85,17 +92,17 @@ Textures and samplers (value: sprites, materials, UI images; sRGB correctness):
 let tex = TextureBuilder::new_2d(TextureFormat::Rgba8UnormSrgb)
   .with_size(w, h)
   .with_data(&pixels)
-  .build(&mut rc);
-let samp = SamplerBuilder::linear_clamp().build(&mut rc);
+  .build(rc.gpu());
+let samp = SamplerBuilder::linear_clamp().build(rc.gpu());
 
 let tex_layout = BindGroupLayoutBuilder::new()
   .with_sampled_texture(0)
   .with_sampler(1)
-  .build(&mut rc);
+  .build(rc.gpu());
 let tex_group = BindGroupBuilder::new(&tex_layout)
   .with_texture(0, &tex)
   .with_sampler(1, &samp)
-  .build(&mut rc);
+  .build(rc.gpu());
 
 // In fragment shader, sample with: sampler2D + UVs; ensure vertex inputs provide UVs.
 // Upload path should convert source assets to sRGB formats when appropriate.
@@ -128,11 +135,22 @@ let pass = RenderPassBuilder::new()
   .with_clear_color(wgpu::Color::BLACK)
   .with_depth_stencil(wgpu::TextureFormat::Depth32Float, 1.0, true, wgpu::CompareFunction::Less)
   .with_msaa(4)
-  .build(&rc);
+  .build(
+    rc.gpu(),
+    rc.surface_format(),
+    rc.depth_format(),
+  );
 
 let pipe = RenderPipelineBuilder::new()
   .with_depth_format(wgpu::TextureFormat::Depth32Float)
-  .build(&mut rc, &pass, &vs, Some(&fs));
+  .build(
+    rc.gpu(),
+    rc.surface_format(),
+    rc.depth_format(),
+    &pass,
+    &vs,
+    Some(&fs),
+  );
 ```
 
 Notes
@@ -144,10 +162,18 @@ Offscreen render targets (value: post‑processing, shadow maps, UI composition,
 let offscreen = RenderTargetBuilder::new()
   .with_color(TextureFormat::Rgba8UnormSrgb, width, height)
   .with_depth(TextureFormat::Depth32Float)
-  .build(&mut rc);
-
-let pass1 = RenderPassBuilder::new().with_target(&offscreen).build(&rc);
-let pass2 = RenderPassBuilder::new().build(&rc); // backbuffer
+  .build(rc.gpu());
+
+let pass1 = RenderPassBuilder::new().with_target(&offscreen).build(
+  rc.gpu(),
+  rc.surface_format(),
+  rc.depth_format(),
+);
+let pass2 = RenderPassBuilder::new().build(
+  rc.gpu(),
+  rc.surface_format(),
+  rc.depth_format(),
+); // backbuffer
 
 // Pass 1: draw scene
 RC::BeginRenderPass { render_pass: pass1_id, viewport };

docs/rendering.md

@@ -1,3 +1,20 @@
+---
+title: "Lambda RS Rendering Guide"
+document_id: "rendering-guide-2025-09-24"
+status: "living"
+created: "2025-09-24T00:00:00Z"
+last_updated: "2025-12-15T00:00:00Z"
+version: "0.2.0"
+engine_workspace_version: "2023.1.30"
+wgpu_version: "26.0.1"
+shader_backend_default: "naga"
+winit_version: "0.29.10"
+repo_commit: "71256389b9efe247a59aabffe9de58147b30669d"
+owners: ["lambda-sh"]
+reviewers: ["engine", "rendering"]
+tags: ["guide", "rendering", "wgpu", "shaders", "pipelines"]
+---
+
 # Lambda RS Rendering Guide (wgpu backend)
 
 This guide shows how to build windows, compile shaders, create pipelines,
@@ -117,7 +134,11 @@ use lambda_platform::wgpu::types as wgpu;
 
 let pass = RenderPassBuilder::new()
   .with_clear_color(wgpu::Color { r: 0.02, g: 0.02, b: 0.06, a: 1.0 })
-  .build(&render_context);
+  .build(
+    render_context.gpu(),
+    render_context.surface_format(),
+    render_context.depth_format(),
+  );
 ```
 
 ## Vertex Data: Mesh and Buffer
@@ -212,4 +233,3 @@ if let Events::Window { event: WindowEvent::Resize { width, height }, .. } = e {
   the feature flag `with-shaderc`.
 - All examples live under `crates/lambda-rs/examples/` and are runnable via:
   `cargo run -p lambda-rs --example <name>`
-

docs/specs/depth-stencil-msaa.md

@@ -3,13 +3,13 @@ title: "Depth/Stencil and Multi-Sample Rendering"
 document_id: "depth-stencil-msaa-2025-11-11"
 status: "draft"
 created: "2025-11-11T00:00:00Z"
-last_updated: "2025-11-21T22:00:00Z"
-version: "0.4.1"
+last_updated: "2025-12-15T00:00:00Z"
+version: "0.5.0"
 engine_workspace_version: "2023.1.30"
 wgpu_version: "26.0.1"
 shader_backend_default: "naga"
 winit_version: "0.29.10"
-repo_commit: "415167f4238c21debb385eef1192e2da7476c586"
+repo_commit: "71256389b9efe247a59aabffe9de58147b30669d"
 owners: ["lambda-sh"]
 reviewers: ["engine", "rendering"]
 tags: ["spec", "rendering", "depth", "stencil", "msaa"]
@@ -94,13 +94,24 @@ App Code
       .with_clear_color([0.0, 0.0, 0.0, 1.0])
       .with_depth_clear(1.0)
       .with_multi_sample(4)
-      .build(&render_context);
+      .build(
+        render_context.gpu(),
+        render_context.surface_format(),
+        render_context.depth_format(),
+      );
 
     let pipeline = RenderPipelineBuilder::new()
       .with_multi_sample(4)
       .with_depth_format(DepthFormat::Depth32Float)
       .with_depth_compare(CompareFunction::Less)
-      .build(&mut render_context, &pass, &vertex_shader, Some(&fragment_shader));
+      .build(
+        render_context.gpu(),
+        render_context.surface_format(),
+        render_context.depth_format(),
+        &pass,
+        &vertex_shader,
+        Some(&fragment_shader),
+      );
     ```
 - Behavior
   - Defaults
@@ -243,6 +254,7 @@ Always-on safeguards (release and debug)
   defaults (no depth, no multi-sampling) unless explicitly configured.
 
 ## Changelog
+- 2025-12-15 (v0.5.0) — Update example code to use `render_context.gpu()` and add `surface_format`/`depth_format` parameters to `RenderPassBuilder` and `RenderPipelineBuilder`.
 - 2025-11-21 (v0.4.1) — Clarify depth attachment and clear behavior for
   stencil-only passes; align specification with engine behavior that preserves
   depth when only stencil operations are configured.