Voxel Renderer Skill

References (read these before writing rendering code)

1. .claude/references/sdl3-gpu-api.md — API overview, capabilities, what backends exist
2. .claude/references/sdl3-gpu-patterns.md — Concrete code patterns: init, buffer upload, instancing, compute→graphics, draw indirect, depth passes. Copy these.
3. .claude/references/shader-workflow.md — HLSL→SPIR-V compilation with DXC, CMake integration, binding conventions, example shaders
4. .claude/references/voxel-meshing-algorithms.md — Greedy meshing algorithm, per-vertex AO formula, packed vertex formats, fragment lifecycle
5. .claude/references/voxel-rendering-research.md — Teardown analysis, performance numbers, what matters at RTS distance
6. .claude/references/deferred-pbr-correctness.md — Deferred PBR correctness spec: G-buffer formats, triplanar normals, Cook-Torrance GGX, tonemapping, AO, gamma pipeline. Read this before writing or modifying any shader or render pass.

Material Model: Exterior vs Interior Surfaces

Every mesh face has an exposure attribute: 1 = exterior (weathered), 0 = interior (fresh fracture).

Exterior faces use triplanar projection with a weathered rock texture — dark patina, smooth, color variation. When a rock fractures, the outside pieces KEEP their original exterior texture unchanged.

Interior faces (newly exposed by fracture) use a plain per-material tint — light gray for stone, tan for sandstone, etc. These are the "fresh cut" surfaces.

The shader blends between exterior and interior texture sets based on the exposure attribute. Triplanar projection means no UVs — works on any geometry including fresh fracture faces.

Weathering over game-time (nice-to-have): fresh interior faces gradually accumulate exposure (0.0 → 1.0) and transition to the weathered look. Not needed for MVP.

Quick Decisions

Shader language: HLSL. Compile to SPIR-V with DXC (already installed on this machine).

Per-frame instance update: Use persistent transfer buffer with cycle=true. Map, write, unmap, upload. SDL handles double-buffering internally.

Uniforms: Push-based (SDL_PushGPUVertexUniformData) for MVP matrix and light params. NO UBO creation needed.

Large data: Storage buffers (SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ), not uniform buffers.

Depth buffer: SDL_GPU_TEXTUREFORMAT_D32_FLOAT. Created once at init, passed to SDL_BeginGPURenderPass as depth-stencil target.

What Matters Visually at RTS Distance

At Anno/Cities Skylines zoom, 1 pixel = 5-10cm. Individual voxel edges are invisible.

High impact: Ambient occlusion, directional shadows, per-voxel color noise, silhouette variation.

Zero impact: Normal maps, PBR roughness detail, smooth mesh extraction (all sub-pixel).

Rendering Correctness

Full spec: .claude/references/deferred-pbr-correctness.md — read before writing or modifying any shader, render pass, or texture loading code.

G-Buffer Formats (non-negotiable)

Triplanar Normal Mapping: Golus Canonical Whiteout Blend

The Whiteout blend uses Ben Golus's canonical formulation (from his GitHub reference implementation). Three rules:

1. Golus canonical re-swizzle. Tangent XY are ADDED to corresponding world normal components, tangent Z is MULTIPLIED by world normal axis component. Then re-swizzle (.zyx, .xzy, .xyz) during final blend to map back to world space.
2. NO negations on tangent or world normal components. Spurious negations cause bump directions to cancel during blending, producing flat normals.
3. Normal strength scales tangent XY BEFORE Whiteout, with Z adjustment via lerp(1.0, tn.z, saturate(strength)). This is Unity's standard approach.

Reference HLSL in the full spec (Section 2).

Tonemapping

Do NOT use Reinhard (color / (color + 1)). It compresses highlights so aggressively that normal-map detail becomes invisible at sun intensity > 3. Use ACES Filmic tonemapping instead (reference code in Section 4 of the spec).

Texture Loading

Gamma Pipeline

Exactly one sRGB encode across the entire path. Check SDL_GetGPUSwapchainTextureFormat() at runtime:

• If it returns *_SRGB: output linear values, hardware encodes. NO manual pow(1/2.2).
• If it returns plain UNORM: apply pow(1/2.2) in fragment shader.
• Double gamma (both) = washed out. No gamma (neither) = too dark.

Mipmaps

All textures used with triplanar mapping MUST have mipmaps. Without them, distant surfaces shimmer and specular averages to a flat sheen. Set num_levels = floor(log2(max(w,h))) + 1. Use SDL_GPU_SAMPLERMIPMAPMODE_LINEAR for trilinear.

IBL (Image-Based Lighting)

IBL is mandatory for PBR to look correct. Without it, surfaces look flat and unnaturally dark in shadow. The engine uses HDRI environment map IBL with analytical fallback:

• HDRI source: assets/hdri/outdoor.hdr — equirectangular Radiance HDR, loaded as RGBA16F with mipmap chain
• Diffuse IBL: HDRI sampled at surface normal direction (mip 0)
• Specular IBL: HDRI sampled at reflection vector with roughness * (mipCount - 1) mip LOD
• BRDF LUT: Karis analytical approximation (no texture needed) for split-sum
• Fallback: If HDRI not loaded, analytical sky/ground gradient (procedural) is used
• Sampler: Trilinear, repeat-U (phi wraps), clamp-V (theta at poles)

IBL is scaled by AmbientIntensity for artist control. Shader slot 5 in the lighting pass. Controlled by HasHDRI and HDRIMipCount uniforms.

AO Application

AO modulates indirect light (IBL) only. Direct sunlight and fill light are NOT affected by AO (they have shadow maps). Applying AO to direct light causes unnatural double-darkening in crevices.

Diagnostic Checklist

If the render looks flat or washed out:

• Normal map affecting lighting? (render normals as color to verify)
• Triplanar normal swizzle correct? (Golus canonical with re-swizzle)
• Normals stored in RGBA16F, not RGBA8?
• IBL active? (shadow side should show sky/ground gradient, not flat black)
• Tonemapping preserving highlight contrast? (ACES Filmic, never Reinhard)
• AO applied to indirect only? (AO modulates IBL, not direct sun)
• AO darkening crevices? (render AO as grayscale to verify)
• Mipmaps enabled on all textures?
• Gamma applied exactly once? (not zero, not twice)
• Albedo loaded as sRGB?
• Normal map loaded as LINEAR (not sRGB)?

Performance Budget

• 10K-40K fragments at 60fps is trivially within GPU budget
• Modern GPU handles 500K+ instanced cubes at 60fps
• Sub-pixel fragments: render as colored points, not cubes (avoids 40-80x quad waste)
• Instance buffer: 24 bytes/fragment × 100K max = 2.4 MB (nothing)