22 KiB
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 작성
// 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<u8> = 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 모듈 등록
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: 커밋
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 작성
// 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<f32>;
@group(0) @binding(1) var t_normal: texture_2d<f32>;
@group(0) @binding(2) var t_albedo: texture_2d<f32>;
@group(0) @binding(3) var s_gbuffer: sampler;
// Group 1: SSGI data
struct SsgiUniform {
projection: mat4x4<f32>,
view: mat4x4<f32>,
radius: f32,
bias: f32,
intensity: f32,
indirect_strength: f32,
};
struct SsgiKernel {
samples: array<vec4<f32>, 64>,
};
@group(1) @binding(0) var<uniform> ssgi: SsgiUniform;
@group(1) @binding(1) var<uniform> kernel: SsgiKernel;
@group(1) @binding(2) var t_noise: texture_2d<f32>;
@group(1) @binding(3) var s_noise: sampler;
struct VertexOutput {
@builtin(position) clip_position: vec4<f32>,
@location(0) uv: vec2<f32>,
};
@vertex
fn vs_main(@location(0) position: vec2<f32>) -> VertexOutput {
var out: VertexOutput;
out.clip_position = vec4<f32>(position, 0.0, 1.0);
out.uv = vec2<f32>(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<f32> {
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<f32>(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<f32>(world_pos, 1.0)).xyz;
let view_normal = normalize((ssgi.view * vec4<f32>(world_normal, 0.0)).xyz);
// Random rotation from noise texture (4x4 tiling)
let tex_dims = textureDimensions(t_position);
let noise_scale = vec2<f32>(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<f32>(tangent, bitangent, view_normal);
var occlusion = 0.0;
var indirect = vec3<f32>(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<f32>(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<f32>(0.001), vec2<f32>(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<f32>(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<f32>(ao, indirect);
}
- Step 2: deferred_pipeline.rs에 SSGI 파이프라인 함수 추가
Add to deferred_pipeline.rs:
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: 커밋
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). 여기에 추가:
// 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에 추가:
@group(2) @binding(5) var t_ssgi: texture_2d<f32>;
@group(2) @binding(6) var s_ssgi: sampler;
Fragment shader에서 ambient 계산 부분 변경:
// 기존: 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: 커밋
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 렌더링으로 변경합니다.
변경사항:
SsgiResources::new()호출하여 SSGI 리소스 생성- SSGI 파이프라인 + 바인드 그룹 레이아웃 생성
- SSGI 바인드 그룹 2개 생성 (G-Buffer + SSGI data)
- 기존 Shadow+IBL 바인드 그룹에 SSGI output texture + sampler 추가 (binding 5,6)
- 렌더 루프에 SSGI 패스 삽입 (Pass 2: SSGI, 기존 Lighting은 Pass 3으로)
- 매 프레임 SsgiUniform 업데이트 (view, projection 행렬)
- 리사이즈 시 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: 커밋
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 아래에:
### 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 미뤄진 항목
## Phase 7-2
- **Bilateral Blur** — SSGI 노이즈 제거 블러 미구현. 4x4 노이즈 타일링만.
- **반해상도 렌더링** — 풀 해상도에서 SSGI 실행. 성능 최적화 미적용.
- **Temporal Accumulation** — 프레임 간 누적 미구현. 매 프레임 독립 계산.
- **Light Probes** — 베이크 기반 GI 미구현.
- Step 3: 커밋
git add docs/STATUS.md docs/DEFERRED.md
git commit -m "docs: add Phase 7-2 SSGI status and deferred items"