oxigaf-render 0.1.0

Differentiable 3D Gaussian Splatting rasterizer (wgpu)
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
//! GPU compute pipeline setup and shader compilation.
//!
//! This module handles the creation of compute pipelines for 3DGS rasterization.
//! It supports shader variant selection based on SH degree for optimal performance.
//!
//! ## SH Shader Variants
//!
//! When `use_sh_variants` is enabled in the config, specialized shaders are selected
//! based on the configured `sh_degree`:
//! - Degree 0: DC term only, no direction computation (~3 ops)
//! - Degree 1: DC + linear terms (~15 ops)
//! - Degree 2: DC + linear + quadratic terms (~45 ops)
//! - Degree 3: Full SH evaluation (~100 ops)
//!
//! These variants eliminate runtime branching, improving performance by 5-10%.

use crate::config::RasterConfig;
use crate::RenderError;

/// Compiled compute pipelines for the rasterization forward and backward passes.
pub struct RasterPipelines {
    pub preprocess: wgpu::ComputePipeline,
    pub prefix_sum: wgpu::ComputePipeline,
    pub prefix_sum_add: wgpu::ComputePipeline,
    pub tile_assign: wgpu::ComputePipeline,
    pub tile_ranges: wgpu::ComputePipeline,
    pub rasterize_fwd: wgpu::ComputePipeline,
    pub rasterize_bwd: wgpu::ComputePipeline,
    pub atomic_to_f32: wgpu::ComputePipeline,
    pub preprocess_bwd: wgpu::ComputePipeline,
    pub flame_binding_bwd: wgpu::ComputePipeline,

    // Bind group layouts for each stage
    pub preprocess_bgl: wgpu::BindGroupLayout,
    pub prefix_sum_bgl: wgpu::BindGroupLayout,
    pub prefix_sum_add_bgl: wgpu::BindGroupLayout,
    pub tile_assign_bgl: wgpu::BindGroupLayout,
    pub tile_ranges_bgl: wgpu::BindGroupLayout,
    pub rasterize_fwd_bgl: wgpu::BindGroupLayout,
    pub rasterize_bwd_bgl: wgpu::BindGroupLayout,
    pub atomic_to_f32_bgl: wgpu::BindGroupLayout,
    pub preprocess_bwd_bgl: wgpu::BindGroupLayout,
    pub flame_binding_bwd_bgl: wgpu::BindGroupLayout,
}

/// Get the preprocess shader source based on SH degree and optimization settings.
///
/// When `use_sh_variants` is true and `sh_optimization` is enabled, returns
/// a specialized shader variant for the given `sh_degree`. Otherwise, returns
/// the general-purpose shader with runtime branching.
///
/// # Performance
///
/// Using specialized variants eliminates runtime branching overhead:
/// - Degree 0: Skips direction computation entirely
/// - Degree 1-3: Unrolled SH evaluation without conditionals
fn get_preprocess_shader_source(config: &RasterConfig) -> &'static str {
    if config.sh_optimization && config.use_sh_variants {
        match config.sh_degree {
            0 => include_str!("../shaders/preprocess_sh0.wgsl"),
            1 => include_str!("../shaders/preprocess_sh1.wgsl"),
            2 => include_str!("../shaders/preprocess_sh2.wgsl"),
            3 => include_str!("../shaders/preprocess_sh3.wgsl"),
            // For degrees > 3, fall back to general shader
            _ => include_str!("../shaders/preprocess.wgsl"),
        }
    } else {
        // Use general-purpose shader with runtime branching
        include_str!("../shaders/preprocess.wgsl")
    }
}

/// Get a descriptive label for the preprocess shader based on configuration.
fn get_preprocess_shader_label(config: &RasterConfig) -> &'static str {
    if config.sh_optimization && config.use_sh_variants {
        match config.sh_degree {
            0 => "preprocess_sh0",
            1 => "preprocess_sh1",
            2 => "preprocess_sh2",
            3 => "preprocess_sh3",
            _ => "preprocess",
        }
    } else {
        "preprocess"
    }
}

impl RasterPipelines {
    /// Compile all compute pipelines.
    ///
    /// When `config.use_sh_variants` is true, selects specialized preprocess
    /// shaders based on `config.sh_degree` for optimal SH evaluation performance.
    pub fn new(device: &wgpu::Device, config: &RasterConfig) -> Result<Self, RenderError> {
        // --- Preprocess ---
        // Bind group layout includes normals buffer for optional normal output
        let preprocess_bgl = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("preprocess_bgl"),
            entries: &[
                uniform_entry(0),     // uniforms
                storage_ro_entry(1),  // positions
                storage_ro_entry(2),  // rotations
                storage_ro_entry(3),  // scales
                storage_ro_entry(4),  // opacities
                storage_rw_entry(5),  // means2d
                storage_rw_entry(6),  // cov2d
                storage_rw_entry(7),  // conics
                storage_rw_entry(8),  // depths
                storage_rw_entry(9),  // radii
                storage_rw_entry(10), // tile_counts
                storage_ro_entry(11), // sh_coeffs
                storage_rw_entry(12), // colors
                storage_rw_entry(13), // normals (for optional normal output)
            ],
        });

        // Select shader variant based on config
        let preprocess_source = get_preprocess_shader_source(config);
        let preprocess_label = get_preprocess_shader_label(config);

        let preprocess = compile_pipeline(
            device,
            preprocess_label,
            preprocess_source,
            "preprocess",
            &preprocess_bgl,
        );

        // --- Prefix sum ---
        let prefix_sum_bgl = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("prefix_sum_bgl"),
            entries: &[
                storage_ro_entry(0), // input
                storage_rw_entry(1), // output
                uniform_entry(2),    // params
                storage_rw_entry(3), // block_sums
            ],
        });
        let prefix_sum = compile_pipeline(
            device,
            "prefix_sum",
            include_str!("../shaders/prefix_sum.wgsl"),
            "prefix_sum",
            &prefix_sum_bgl,
        );

        // --- Prefix sum add (propagate block offsets) ---
        let prefix_sum_add_bgl =
            device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
                label: Some("prefix_sum_add_bgl"),
                entries: &[
                    storage_rw_entry(0), // data (in-place add)
                    storage_ro_entry(1), // block_offsets
                    uniform_entry(2),    // params
                ],
            });
        let prefix_sum_add = compile_pipeline(
            device,
            "prefix_sum_add",
            include_str!("../shaders/prefix_sum_add.wgsl"),
            "prefix_sum_add",
            &prefix_sum_add_bgl,
        );

        // --- Tile assign ---
        let tile_assign_bgl = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("tile_assign_bgl"),
            entries: &[
                uniform_entry(0),    // uniforms
                storage_ro_entry(1), // means2d
                storage_ro_entry(2), // depths
                storage_ro_entry(3), // radii
                storage_ro_entry(4), // tile_offsets
                storage_rw_entry(5), // sort_keys
                storage_rw_entry(6), // sort_values
            ],
        });
        let tile_assign = compile_pipeline(
            device,
            "tile_assign",
            include_str!("../shaders/tile_assign.wgsl"),
            "tile_assign",
            &tile_assign_bgl,
        );

        // --- Tile ranges ---
        let tile_ranges_bgl = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("tile_ranges_bgl"),
            entries: &[
                storage_ro_entry(0), // sort_keys
                storage_rw_entry(1), // tile_ranges
                uniform_entry(2),    // params
            ],
        });
        let tile_ranges = compile_pipeline(
            device,
            "tile_ranges",
            include_str!("../shaders/tile_ranges.wgsl"),
            "tile_ranges_kernel",
            &tile_ranges_bgl,
        );

        // --- Rasterize forward ---
        let rasterize_fwd_bgl = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("rasterize_fwd_bgl"),
            entries: &[
                uniform_entry(0),     // uniforms
                storage_ro_entry(1),  // means2d
                storage_ro_entry(2),  // conics
                storage_ro_entry(3),  // colors
                storage_ro_entry(4),  // opacities
                storage_ro_entry(5),  // depths
                storage_ro_entry(6),  // tile_ranges
                storage_ro_entry(7),  // sort_values
                storage_rw_entry(8),  // out_color
                storage_rw_entry(9),  // out_depth
                storage_rw_entry(10), // out_transmittance
                storage_rw_entry(11), // out_n_contrib
                storage_ro_entry(12), // normals (per-Gaussian normals from preprocess)
                storage_rw_entry(13), // out_normals (per-pixel normals output)
            ],
        });
        let rasterize_fwd = compile_pipeline(
            device,
            "rasterize_fwd",
            include_str!("../shaders/rasterize_fwd.wgsl"),
            "rasterize_forward",
            &rasterize_fwd_bgl,
        );

        // --- Rasterize backward ---
        let rasterize_bwd_bgl = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("rasterize_bwd_bgl"),
            entries: &[
                uniform_entry(0),     // uniforms
                storage_ro_entry(1),  // means2d
                storage_ro_entry(2),  // conics
                storage_ro_entry(3),  // colors
                storage_ro_entry(4),  // opacities
                storage_ro_entry(5),  // out_color
                storage_ro_entry(6),  // out_transmittance
                storage_ro_entry(7),  // out_n_contrib
                storage_ro_entry(8),  // tile_ranges
                storage_ro_entry(9),  // sort_values
                storage_ro_entry(10), // grad_output
                storage_rw_entry(11), // grad_colors
                storage_rw_entry(12), // grad_opacities
                storage_rw_entry(13), // grad_means2d
                storage_rw_entry(14), // grad_conics
            ],
        });
        let rasterize_bwd = compile_pipeline(
            device,
            "rasterize_bwd",
            include_str!("../shaders/rasterize_bwd.wgsl"),
            "rasterize_backward",
            &rasterize_bwd_bgl,
        );

        // --- Atomic to f32 conversion ---
        let atomic_to_f32_bgl = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("atomic_to_f32_bgl"),
            entries: &[
                uniform_entry(0),    // num_elements
                storage_rw_entry(1), // atomic_buffer (array<atomic<u32>>)
                storage_rw_entry(2), // f32_buffer (array<f32>)
            ],
        });
        let atomic_to_f32 = compile_pipeline(
            device,
            "atomic_to_f32",
            include_str!("../shaders/atomic_to_f32.wgsl"),
            "atomic_to_f32",
            &atomic_to_f32_bgl,
        );

        // --- Preprocess backward ---
        let preprocess_bwd_bgl =
            device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
                label: Some("preprocess_bwd_bgl"),
                entries: &[
                    uniform_entry(0),     // uniforms
                    storage_ro_entry(1),  // positions
                    storage_ro_entry(2),  // rotations
                    storage_ro_entry(3),  // scales
                    storage_ro_entry(4),  // cov2d
                    storage_ro_entry(5),  // conics
                    storage_ro_entry(6),  // sh_coeffs
                    storage_ro_entry(7),  // grad_means2d (from rasterize_bwd)
                    storage_ro_entry(8),  // grad_conics (from rasterize_bwd)
                    storage_ro_entry(9),  // grad_colors (from rasterize_bwd)
                    storage_rw_entry(10), // grad_positions
                    storage_rw_entry(11), // grad_rotations
                    storage_rw_entry(12), // grad_scales
                    storage_rw_entry(13), // grad_sh_coeffs
                ],
            });
        let preprocess_bwd = compile_pipeline(
            device,
            "preprocess_bwd",
            include_str!("../shaders/preprocess_bwd.wgsl"),
            "preprocess_backward",
            &preprocess_bwd_bgl,
        );

        // FLAME binding backward pass
        let flame_binding_bwd_bgl =
            device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
                label: Some("flame_binding_bwd_bgl"),
                entries: &[
                    uniform_entry(0),    // uniforms (num_gaussians)
                    storage_ro_entry(1), // binding_info (vertex_id per Gaussian)
                    storage_ro_entry(2), // tbn_frames (tangent, bitangent, normal per vertex)
                    storage_ro_entry(3), // position_grads (∂L/∂position per Gaussian)
                    storage_rw_entry(4), // offset_grads (∂L/∂local_offset output)
                ],
            });
        let flame_binding_bwd = compile_pipeline(
            device,
            "flame_binding_bwd",
            include_str!("../shaders/flame_binding_bwd.wgsl"),
            "flame_binding_backward",
            &flame_binding_bwd_bgl,
        );

        Ok(Self {
            preprocess,
            prefix_sum,
            prefix_sum_add,
            tile_assign,
            tile_ranges,
            rasterize_fwd,
            rasterize_bwd,
            atomic_to_f32,
            preprocess_bwd,
            flame_binding_bwd,
            preprocess_bgl,
            prefix_sum_bgl,
            prefix_sum_add_bgl,
            tile_assign_bgl,
            tile_ranges_bgl,
            rasterize_fwd_bgl,
            rasterize_bwd_bgl,
            atomic_to_f32_bgl,
            preprocess_bwd_bgl,
            flame_binding_bwd_bgl,
        })
    }
}

fn compile_pipeline(
    device: &wgpu::Device,
    label: &str,
    source: &str,
    entry_point: &str,
    bgl: &wgpu::BindGroupLayout,
) -> wgpu::ComputePipeline {
    let module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
        label: Some(label),
        source: wgpu::ShaderSource::Wgsl(source.into()),
    });

    let layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
        label: Some(&format!("{label}_layout")),
        bind_group_layouts: &[bgl],
        immediate_size: 0,
    });

    device.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
        label: Some(&format!("{label}_pipeline")),
        layout: Some(&layout),
        module: &module,
        entry_point: Some(entry_point),
        compilation_options: Default::default(),
        cache: None,
    })
}

fn uniform_entry(binding: u32) -> wgpu::BindGroupLayoutEntry {
    wgpu::BindGroupLayoutEntry {
        binding,
        visibility: wgpu::ShaderStages::COMPUTE,
        ty: wgpu::BindingType::Buffer {
            ty: wgpu::BufferBindingType::Uniform,
            has_dynamic_offset: false,
            min_binding_size: None,
        },
        count: None,
    }
}

fn storage_ro_entry(binding: u32) -> wgpu::BindGroupLayoutEntry {
    wgpu::BindGroupLayoutEntry {
        binding,
        visibility: wgpu::ShaderStages::COMPUTE,
        ty: wgpu::BindingType::Buffer {
            ty: wgpu::BufferBindingType::Storage { read_only: true },
            has_dynamic_offset: false,
            min_binding_size: None,
        },
        count: None,
    }
}

fn storage_rw_entry(binding: u32) -> wgpu::BindGroupLayoutEntry {
    wgpu::BindGroupLayoutEntry {
        binding,
        visibility: wgpu::ShaderStages::COMPUTE,
        ty: wgpu::BindingType::Buffer {
            ty: wgpu::BufferBindingType::Storage { read_only: false },
            has_dynamic_offset: false,
            min_binding_size: None,
        },
        count: None,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_get_preprocess_shader_label() {
        // With variants enabled
        let mut config = RasterConfig {
            sh_optimization: true,
            use_sh_variants: true,
            ..RasterConfig::default()
        };

        config.sh_degree = 0;
        assert_eq!(get_preprocess_shader_label(&config), "preprocess_sh0");

        config.sh_degree = 1;
        assert_eq!(get_preprocess_shader_label(&config), "preprocess_sh1");

        config.sh_degree = 2;
        assert_eq!(get_preprocess_shader_label(&config), "preprocess_sh2");

        config.sh_degree = 3;
        assert_eq!(get_preprocess_shader_label(&config), "preprocess_sh3");

        // Without variants
        config.use_sh_variants = false;
        config.sh_degree = 0;
        assert_eq!(get_preprocess_shader_label(&config), "preprocess");
    }
}