# Phase 7-2: SSGI Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** SSAO + Color Bleeding 기반 SSGI로 간접광과 앰비언트 오클루전 추가 **Architecture:** `voltex_renderer`에 ssgi.rs(리소스+커널 생성) + ssgi_shader.wgsl(SSGI 풀스크린 패스) 추가. 기존 deferred_lighting.wgsl의 Shadow+IBL 바인드 그룹에 SSGI 출력 텍스처를 추가하여 ambient에 적용. **Tech Stack:** Rust, wgpu 28.0, WGSL **Spec:** `docs/superpowers/specs/2026-03-25-phase7-2-ssgi.md` --- ## File Structure - `crates/voltex_renderer/src/ssgi.rs` — SsgiResources, SsgiUniform, 커널/노이즈 생성 (Create) - `crates/voltex_renderer/src/ssgi_shader.wgsl` — SSGI 풀스크린 셰이더 (Create) - `crates/voltex_renderer/src/deferred_pipeline.rs` — SSGI 파이프라인 + 바인드 그룹 레이아웃 추가 (Modify) - `crates/voltex_renderer/src/deferred_lighting.wgsl` — SSGI 텍스처 읽어서 ambient 적용 (Modify) - `crates/voltex_renderer/src/lib.rs` — ssgi 모듈 등록 (Modify) - `examples/deferred_demo/src/main.rs` — SSGI 패스 통합 (Modify) --- ## Task 1: SsgiResources + 커널/노이즈 생성 **Files:** - Create: `crates/voltex_renderer/src/ssgi.rs` - Modify: `crates/voltex_renderer/src/lib.rs` - [ ] **Step 1: ssgi.rs 작성** ```rust // crates/voltex_renderer/src/ssgi.rs use bytemuck::{Pod, Zeroable}; use wgpu::util::DeviceExt; pub const SSGI_OUTPUT_FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Rgba16Float; pub const SSGI_KERNEL_SIZE: usize = 64; #[repr(C)] #[derive(Copy, Clone, Debug, Pod, Zeroable)] pub struct SsgiUniform { pub projection: [f32; 16], pub view: [f32; 16], pub radius: f32, pub bias: f32, pub intensity: f32, pub indirect_strength: f32, } impl Default for SsgiUniform { fn default() -> Self { Self { projection: [0.0; 16], view: [0.0; 16], radius: 0.5, bias: 0.025, intensity: 1.5, indirect_strength: 0.5, } } } pub struct SsgiResources { pub output_view: wgpu::TextureView, pub kernel_buffer: wgpu::Buffer, pub noise_view: wgpu::TextureView, pub noise_sampler: wgpu::Sampler, pub uniform_buffer: wgpu::Buffer, pub width: u32, pub height: u32, } impl SsgiResources { pub fn new(device: &wgpu::Device, queue: &wgpu::Queue, width: u32, height: u32) -> Self { let output_view = create_ssgi_output(device, width, height); let kernel_data = generate_kernel(SSGI_KERNEL_SIZE); let kernel_buffer = device.create_buffer_init(&wgpu::util::BufferInitDescriptor { label: Some("SSGI Kernel"), contents: bytemuck::cast_slice(&kernel_data), usage: wgpu::BufferUsages::UNIFORM, }); let noise_view = create_noise_texture(device, queue); let noise_sampler = device.create_sampler(&wgpu::SamplerDescriptor { label: Some("SSGI Noise Sampler"), address_mode_u: wgpu::AddressMode::Repeat, address_mode_v: wgpu::AddressMode::Repeat, mag_filter: wgpu::FilterMode::Nearest, min_filter: wgpu::FilterMode::Nearest, ..Default::default() }); let uniform_buffer = device.create_buffer_init(&wgpu::util::BufferInitDescriptor { label: Some("SSGI Uniform"), contents: bytemuck::bytes_of(&SsgiUniform::default()), usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST, }); Self { output_view, kernel_buffer, noise_view, noise_sampler, uniform_buffer, width, height } } pub fn resize(&mut self, device: &wgpu::Device, width: u32, height: u32) { self.output_view = create_ssgi_output(device, width, height); self.width = width; self.height = height; } } fn create_ssgi_output(device: &wgpu::Device, w: u32, h: u32) -> wgpu::TextureView { let tex = device.create_texture(&wgpu::TextureDescriptor { label: Some("SSGI Output"), size: wgpu::Extent3d { width: w, height: h, depth_or_array_layers: 1 }, mip_level_count: 1, sample_count: 1, dimension: wgpu::TextureDimension::D2, format: SSGI_OUTPUT_FORMAT, usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::TEXTURE_BINDING, view_formats: &[], }); tex.create_view(&wgpu::TextureViewDescriptor::default()) } /// Generate hemisphere sample kernel for SSAO/SSGI. /// Samples are distributed in a hemisphere (z >= 0) with more samples near center. pub fn generate_kernel(count: usize) -> Vec<[f32; 4]> { let mut kernel = Vec::with_capacity(count); for i in 0..count { // Pseudo-random using simple hash let fi = i as f32; let x = pseudo_random(i * 2) * 2.0 - 1.0; let y = pseudo_random(i * 2 + 1) * 2.0 - 1.0; let z = pseudo_random(i * 3 + 7).max(0.05); // hemisphere, z > 0 let len = (x * x + y * y + z * z).sqrt(); let (nx, ny, nz) = (x / len, y / len, z / len); // Scale: more samples near center let mut scale = fi / count as f32; scale = 0.1 + scale * scale * 0.9; // lerp(0.1, 1.0, scale^2) kernel.push([nx * scale, ny * scale, nz * scale, 0.0]); } kernel } /// Generate 4x4 noise texture data (random tangent-space rotation vectors). pub fn generate_noise_data() -> Vec<[f32; 4]> { let mut noise = Vec::with_capacity(16); for i in 0..16 { let x = pseudo_random(i * 5 + 13) * 2.0 - 1.0; let y = pseudo_random(i * 7 + 17) * 2.0 - 1.0; let len = (x * x + y * y).sqrt().max(0.001); noise.push([x / len, y / len, 0.0, 0.0]); } noise } fn create_noise_texture(device: &wgpu::Device, queue: &wgpu::Queue) -> wgpu::TextureView { let data = generate_noise_data(); let bytes: Vec = data.iter().flat_map(|v| { v.iter().flat_map(|f| f.to_le_bytes()) }).collect(); let tex = device.create_texture(&wgpu::TextureDescriptor { label: Some("SSGI Noise"), size: wgpu::Extent3d { width: 4, height: 4, depth_or_array_layers: 1 }, mip_level_count: 1, sample_count: 1, dimension: wgpu::TextureDimension::D2, format: wgpu::TextureFormat::Rgba32Float, usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST, view_formats: &[], }); queue.write_texture( wgpu::TexelCopyTextureInfo { texture: &tex, mip_level: 0, origin: wgpu::Origin3d::ZERO, aspect: wgpu::TextureAspect::All }, &bytes, wgpu::TexelCopyBufferLayout { offset: 0, bytes_per_row: Some(4 * 16), rows_per_image: None }, wgpu::Extent3d { width: 4, height: 4, depth_or_array_layers: 1 }, ); tex.create_view(&wgpu::TextureViewDescriptor::default()) } /// Simple deterministic pseudo-random [0, 1) from integer seed. fn pseudo_random(seed: usize) -> f32 { let n = seed.wrapping_mul(0x5DEECE66D).wrapping_add(0xB) & 0xFFFFFF; n as f32 / 0xFFFFFF as f32 } #[cfg(test)] mod tests { use super::*; #[test] fn test_kernel_hemisphere() { let kernel = generate_kernel(64); assert_eq!(kernel.len(), 64); for k in &kernel { assert!(k[2] >= 0.0, "kernel z must be >= 0 (hemisphere), got {}", k[2]); let len = (k[0] * k[0] + k[1] * k[1] + k[2] * k[2]).sqrt(); assert!(len <= 1.01, "kernel sample must be within unit hemisphere, len={}", len); } } #[test] fn test_noise_data() { let noise = generate_noise_data(); assert_eq!(noise.len(), 16); for n in &noise { assert!((n[2]).abs() < 1e-5, "noise z should be 0"); let len = (n[0] * n[0] + n[1] * n[1]).sqrt(); assert!((len - 1.0).abs() < 0.1, "noise vector should be roughly unit length, got {}", len); } } #[test] fn test_ssgi_uniform_default() { let u = SsgiUniform::default(); assert!((u.radius - 0.5).abs() < 1e-5); assert!((u.bias - 0.025).abs() < 1e-5); } } ``` - [ ] **Step 2: lib.rs에 ssgi 모듈 등록** ```rust pub mod ssgi; pub use ssgi::{SsgiResources, SsgiUniform, SSGI_OUTPUT_FORMAT}; ``` - [ ] **Step 3: 빌드 + 테스트** Run: `cargo test -p voltex_renderer` Expected: 기존 20 + 3 = 23 PASS - [ ] **Step 4: 커밋** ```bash git add crates/voltex_renderer/src/ssgi.rs crates/voltex_renderer/src/lib.rs git commit -m "feat(renderer): add SSGI resources with hemisphere kernel and noise texture" ``` --- ## Task 2: SSGI 셰이더 + 파이프라인 **Files:** - Create: `crates/voltex_renderer/src/ssgi_shader.wgsl` - Modify: `crates/voltex_renderer/src/deferred_pipeline.rs` - [ ] **Step 1: ssgi_shader.wgsl 작성** ```wgsl // SSGI pass: screen-space ambient occlusion + color bleeding // Reads G-Buffer position/normal/albedo, outputs AO + indirect color // Group 0: G-Buffer (same layout as lighting pass) @group(0) @binding(0) var t_position: texture_2d; @group(0) @binding(1) var t_normal: texture_2d; @group(0) @binding(2) var t_albedo: texture_2d; @group(0) @binding(3) var s_gbuffer: sampler; // Group 1: SSGI data struct SsgiUniform { projection: mat4x4, view: mat4x4, radius: f32, bias: f32, intensity: f32, indirect_strength: f32, }; struct SsgiKernel { samples: array, 64>, }; @group(1) @binding(0) var ssgi: SsgiUniform; @group(1) @binding(1) var kernel: SsgiKernel; @group(1) @binding(2) var t_noise: texture_2d; @group(1) @binding(3) var s_noise: sampler; struct VertexOutput { @builtin(position) clip_position: vec4, @location(0) uv: vec2, }; @vertex fn vs_main(@location(0) position: vec2) -> VertexOutput { var out: VertexOutput; out.clip_position = vec4(position, 0.0, 1.0); out.uv = vec2(position.x * 0.5 + 0.5, 1.0 - (position.y * 0.5 + 0.5)); return out; } @fragment fn fs_main(in: VertexOutput) -> @location(0) vec4 { let uv = in.uv; let world_pos = textureSample(t_position, s_gbuffer, uv).xyz; // Skip background if dot(world_pos, world_pos) < 0.001 { return vec4(1.0, 0.0, 0.0, 0.0); // AO=1 (no occlusion), indirect=0 } let world_normal = normalize(textureSample(t_normal, s_gbuffer, uv).xyz * 2.0 - 1.0); // Transform to view space let view_pos = (ssgi.view * vec4(world_pos, 1.0)).xyz; let view_normal = normalize((ssgi.view * vec4(world_normal, 0.0)).xyz); // Random rotation from noise texture (4x4 tiling) let tex_dims = textureDimensions(t_position); let noise_scale = vec2(f32(tex_dims.x) / 4.0, f32(tex_dims.y) / 4.0); let random_vec = textureSample(t_noise, s_noise, uv * noise_scale).xyz; // Construct TBN in view space using Gram-Schmidt let tangent = normalize(random_vec - view_normal * dot(random_vec, view_normal)); let bitangent = cross(view_normal, tangent); let TBN = mat3x3(tangent, bitangent, view_normal); var occlusion = 0.0; var indirect = vec3(0.0); for (var i = 0u; i < 64u; i++) { // Sample position in view space let sample_offset = TBN * kernel.samples[i].xyz; let sample_view_pos = view_pos + sample_offset * ssgi.radius; // Project to screen UV let clip = ssgi.projection * vec4(sample_view_pos, 1.0); var screen_uv = clip.xy / clip.w * 0.5 + 0.5; screen_uv.y = 1.0 - screen_uv.y; // Clamp to valid range screen_uv = clamp(screen_uv, vec2(0.001), vec2(0.999)); // Read actual position at that screen location let actual_world_pos = textureSample(t_position, s_gbuffer, screen_uv).xyz; let actual_view_pos = (ssgi.view * vec4(actual_world_pos, 1.0)).xyz; // Occlusion: is the actual geometry closer to camera than our sample? let depth_diff = sample_view_pos.z - actual_view_pos.z; let range_check = smoothstep(0.0, 1.0, ssgi.radius / (abs(view_pos.z - actual_view_pos.z) + 0.001)); if depth_diff > ssgi.bias && depth_diff < ssgi.radius { occlusion += range_check; // Color bleeding: sample albedo at occluder position let sample_albedo = textureSample(t_albedo, s_gbuffer, screen_uv).rgb; indirect += sample_albedo * range_check; } } let ao = clamp(1.0 - (occlusion / 64.0) * ssgi.intensity, 0.0, 1.0); indirect = indirect / 64.0 * ssgi.indirect_strength; return vec4(ao, indirect); } ``` - [ ] **Step 2: deferred_pipeline.rs에 SSGI 파이프라인 함수 추가** Add to deferred_pipeline.rs: ```rust use crate::ssgi::SSGI_OUTPUT_FORMAT; /// SSGI pass: reads G-Buffer (group 0) + SSGI data (group 1) pub fn ssgi_gbuffer_bind_group_layout(device: &wgpu::Device) -> wgpu::BindGroupLayout { device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor { label: Some("SSGI GBuffer BGL"), entries: &[ // position (non-filterable) wgpu::BindGroupLayoutEntry { binding: 0, visibility: wgpu::ShaderStages::FRAGMENT, ty: wgpu::BindingType::Texture { sample_type: wgpu::TextureSampleType::Float { filterable: false }, view_dimension: wgpu::TextureViewDimension::D2, multisampled: false, }, count: None, }, // normal (filterable) wgpu::BindGroupLayoutEntry { binding: 1, visibility: wgpu::ShaderStages::FRAGMENT, ty: wgpu::BindingType::Texture { sample_type: wgpu::TextureSampleType::Float { filterable: true }, view_dimension: wgpu::TextureViewDimension::D2, multisampled: false, }, count: None, }, // albedo (filterable) wgpu::BindGroupLayoutEntry { binding: 2, visibility: wgpu::ShaderStages::FRAGMENT, ty: wgpu::BindingType::Texture { sample_type: wgpu::TextureSampleType::Float { filterable: true }, view_dimension: wgpu::TextureViewDimension::D2, multisampled: false, }, count: None, }, // sampler (non-filtering for position) wgpu::BindGroupLayoutEntry { binding: 3, visibility: wgpu::ShaderStages::FRAGMENT, ty: wgpu::BindingType::Sampler(wgpu::SamplerBindingType::NonFiltering), count: None, }, ], }) } pub fn ssgi_data_bind_group_layout(device: &wgpu::Device) -> wgpu::BindGroupLayout { device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor { label: Some("SSGI Data BGL"), entries: &[ // SsgiUniform wgpu::BindGroupLayoutEntry { binding: 0, visibility: wgpu::ShaderStages::FRAGMENT, ty: wgpu::BindingType::Buffer { ty: wgpu::BufferBindingType::Uniform, has_dynamic_offset: false, min_binding_size: None, }, count: None, }, // kernel (uniform buffer, 64 * vec4 = 1024 bytes) wgpu::BindGroupLayoutEntry { binding: 1, visibility: wgpu::ShaderStages::FRAGMENT, ty: wgpu::BindingType::Buffer { ty: wgpu::BufferBindingType::Uniform, has_dynamic_offset: false, min_binding_size: None, }, count: None, }, // noise texture (non-filterable, Rgba32Float) wgpu::BindGroupLayoutEntry { binding: 2, visibility: wgpu::ShaderStages::FRAGMENT, ty: wgpu::BindingType::Texture { sample_type: wgpu::TextureSampleType::Float { filterable: false }, view_dimension: wgpu::TextureViewDimension::D2, multisampled: false, }, count: None, }, // noise sampler wgpu::BindGroupLayoutEntry { binding: 3, visibility: wgpu::ShaderStages::FRAGMENT, ty: wgpu::BindingType::Sampler(wgpu::SamplerBindingType::NonFiltering), count: None, }, ], }) } pub fn create_ssgi_pipeline( device: &wgpu::Device, gbuffer_layout: &wgpu::BindGroupLayout, data_layout: &wgpu::BindGroupLayout, ) -> wgpu::RenderPipeline { let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor { label: Some("SSGI Shader"), source: wgpu::ShaderSource::Wgsl(include_str!("ssgi_shader.wgsl").into()), }); let layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor { label: Some("SSGI Pipeline Layout"), bind_group_layouts: &[gbuffer_layout, data_layout], immediate_size: 0, }); device.create_render_pipeline(&wgpu::RenderPipelineDescriptor { label: Some("SSGI Pipeline"), layout: Some(&layout), vertex: wgpu::VertexState { module: &shader, entry_point: Some("vs_main"), buffers: &[FullscreenVertex::LAYOUT], compilation_options: wgpu::PipelineCompilationOptions::default(), }, fragment: Some(wgpu::FragmentState { module: &shader, entry_point: Some("fs_main"), targets: &[Some(wgpu::ColorTargetState { format: SSGI_OUTPUT_FORMAT, blend: None, write_mask: wgpu::ColorWrites::ALL, })], compilation_options: wgpu::PipelineCompilationOptions::default(), }), primitive: wgpu::PrimitiveState { topology: wgpu::PrimitiveTopology::TriangleList, ..Default::default() }, depth_stencil: None, multisample: wgpu::MultisampleState::default(), multiview_mask: None, cache: None, }) } ``` - [ ] **Step 3: 빌드 확인** Run: `cargo build -p voltex_renderer` Expected: 컴파일 성공 - [ ] **Step 4: 커밋** ```bash git add crates/voltex_renderer/src/ssgi_shader.wgsl crates/voltex_renderer/src/deferred_pipeline.rs git commit -m "feat(renderer): add SSGI shader and pipeline for screen-space GI" ``` --- ## Task 3: Lighting Pass에 SSGI 통합 **Files:** - Modify: `crates/voltex_renderer/src/deferred_lighting.wgsl` - Modify: `crates/voltex_renderer/src/deferred_pipeline.rs` - [ ] **Step 1: lighting_shadow_bind_group_layout에 SSGI binding 추가** 현재 `lighting_shadow_bind_group_layout`에 binding 0-4 (shadow+IBL). 여기에 추가: ```rust // binding 5: SSGI output texture wgpu::BindGroupLayoutEntry { binding: 5, visibility: wgpu::ShaderStages::FRAGMENT, ty: wgpu::BindingType::Texture { sample_type: wgpu::TextureSampleType::Float { filterable: true }, view_dimension: wgpu::TextureViewDimension::D2, multisampled: false, }, count: None, }, // binding 6: SSGI sampler wgpu::BindGroupLayoutEntry { binding: 6, visibility: wgpu::ShaderStages::FRAGMENT, ty: wgpu::BindingType::Sampler(wgpu::SamplerBindingType::Filtering), count: None, }, ``` - [ ] **Step 2: deferred_lighting.wgsl에 SSGI 바인딩 + 적용 추가** Group 2에 추가: ```wgsl @group(2) @binding(5) var t_ssgi: texture_2d; @group(2) @binding(6) var s_ssgi: sampler; ``` Fragment shader에서 ambient 계산 부분 변경: ```wgsl // 기존: let ambient = (diffuse_ibl + specular_ibl) * ao; // 변경: let ssgi_data = textureSample(t_ssgi, s_ssgi, uv); let ssgi_ao = ssgi_data.r; let ssgi_indirect = ssgi_data.gba; let ambient = (diffuse_ibl + specular_ibl) * ao * ssgi_ao + ssgi_indirect; ``` - [ ] **Step 3: 빌드 확인** Run: `cargo build -p voltex_renderer` Expected: 컴파일 성공 - [ ] **Step 4: 커밋** ```bash git add crates/voltex_renderer/src/deferred_lighting.wgsl crates/voltex_renderer/src/deferred_pipeline.rs git commit -m "feat(renderer): integrate SSGI output into deferred lighting pass" ``` --- ## Task 4: deferred_demo에 SSGI 패스 통합 **Files:** - Modify: `examples/deferred_demo/src/main.rs` NOTE: 이 태스크는 기존 deferred_demo를 확장하여 3-pass 렌더링으로 변경합니다. 변경사항: 1. `SsgiResources::new()` 호출하여 SSGI 리소스 생성 2. SSGI 파이프라인 + 바인드 그룹 레이아웃 생성 3. SSGI 바인드 그룹 2개 생성 (G-Buffer + SSGI data) 4. 기존 Shadow+IBL 바인드 그룹에 SSGI output texture + sampler 추가 (binding 5,6) 5. 렌더 루프에 SSGI 패스 삽입 (Pass 2: SSGI, 기존 Lighting은 Pass 3으로) 6. 매 프레임 SsgiUniform 업데이트 (view, projection 행렬) 7. 리사이즈 시 SSGI 리소스 + 바인드 그룹 재생성 이 태스크는 deferred_demo의 전체 구조를 이해해야 하므로 opus 모델로 실행. - [ ] **Step 1: deferred_demo 수정** Read the current `examples/deferred_demo/src/main.rs` first, then add SSGI integration. - [ ] **Step 2: 빌드 확인** Run: `cargo build --bin deferred_demo` Expected: 컴파일 성공 - [ ] **Step 3: 커밋** ```bash git add examples/deferred_demo/src/main.rs git commit -m "feat(renderer): add SSGI pass to deferred_demo (AO + color bleeding)" ``` --- ## Task 5: 문서 업데이트 **Files:** - Modify: `docs/STATUS.md` - Modify: `docs/DEFERRED.md` - [ ] **Step 1: STATUS.md에 Phase 7-2 추가** Phase 7-1 아래에: ```markdown ### Phase 7-2: SSGI (Screen-Space Global Illumination) - voltex_renderer: SsgiResources (hemisphere kernel, 4x4 noise, output texture) - voltex_renderer: SSGI shader (SSAO + color bleeding in one pass) - voltex_renderer: SSGI pipeline + bind group layouts - voltex_renderer: Lighting pass SSGI integration (ambient * ssgi_ao + indirect) - deferred_demo updated with 3-pass rendering (GBuffer → SSGI → Lighting) ``` 테스트 수 업데이트 (voltex_renderer: 23). - [ ] **Step 2: DEFERRED.md에 Phase 7-2 미뤄진 항목** ```markdown ## Phase 7-2 - **Bilateral Blur** — SSGI 노이즈 제거 블러 미구현. 4x4 노이즈 타일링만. - **반해상도 렌더링** — 풀 해상도에서 SSGI 실행. 성능 최적화 미적용. - **Temporal Accumulation** — 프레임 간 누적 미구현. 매 프레임 독립 계산. - **Light Probes** — 베이크 기반 GI 미구현. ``` - [ ] **Step 3: 커밋** ```bash git add docs/STATUS.md docs/DEFERRED.md git commit -m "docs: add Phase 7-2 SSGI status and deferred items" ```