Blender V5.3
gsplat.h
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2026 Blender Foundation
2 *
3 * SPDX-License-Identifier: Apache-2.0 */
4
5#pragma once
6
7#include "kernel/globals.h"
8#include "kernel/types.h"
9
11#include "kernel/geom/object.h"
13
14/* Gaussian splats evaluation and utility functions.
15 *
16 * References:
17 *
18 * [chen2024pgsr] Nicolas Moenne-Loccoz et. al.
19 * "PGSR: Planar-based Gaussian Splatting for Efficient and High-Fidelity Surface
20 * Reconstruction" (2024)
21 * https://zju3dv.github.io/pgsr/
22 *
23 * [3dgs2023] Bernhard Kebl, Georgios Kopanas et al.
24 * 3D Gaussian Splatting for Real-Time Radiance Field Rendering
25 * ACM Transactions on Graphics (SIGGRAPH 2023)
26 * https://repo-sam.inria.fr/fungraph/3d-gaussian-splatting/
27 */
28
30
31#if defined(__GSPLATS__)
32
33ccl_device_inline float3 gsplat_radiance(KernelGlobals kg, const ccl_private ShaderData &sd)
34{
36
37 const int radiance_base_offset = gsplat_attr_radiance_base_offset(kg, sd.object);
38 const float4 radiance_base = (sd.type & PRIMITIVE_MOTION) ?
39 motion_gsplat_radiance_base(kg, sd.object, sd.prim, sd.time) :
40 kernel_data_fetch(attributes_float4,
41 radiance_base_offset + sd.prim);
42
43 /* Transform incident direction into the local pointcloud object.
44 * This is easier than transforming spherical harmonics into the world space.
45 *
46 * Note that the wi is not guaranteed to be normalized, but the spherical harmonic evaluation
47 * requires direction to be normalized.
48 *
49 * Use safe_normalize() to avoid possible NaN values appearing in color channels. */
50 float3 direction = -sd.wi;
51 object_inverse_dir_transform(kg, &sd, &direction);
52 direction = safe_normalize(direction);
53 kernel_assert((kernel_data_fetch(object_flag, sd.object) & SD_OBJECT_TRANSFORM_APPLIED) == 0);
54
55 float3 color_srgb = spherical_harmonics_evaluate_band_L0(direction, make_float3(radiance_base));
56
57 /* TODO(sergey): Support motion blur for spherical harmonics. */
58 const int radiance_spherical_harmonics_rest_offset =
59 kernel_data_fetch(objects, sd.object).gsplat.radiance_spherical_harmonics_rest_offset;
60 if (radiance_spherical_harmonics_rest_offset != ATTR_STD_NOT_FOUND) {
61 const ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest =
62 kernel_data_fetch(attributes_spherical_harmonics_rest,
63 radiance_spherical_harmonics_rest_offset + sd.prim);
64 color_srgb += spherical_harmonics_evaluate_rest(packed_spherical_harmonics_rest, direction);
65 }
66
67 /* Map to linear color space, add 1/2 offset to mirror source code of [3dgs2023]. */
68 const float3 color_rec709 = color_srgb_to_linear_v3(color_srgb + 0.5f);
69 return rec709_to_rgb(kg, color_rec709);
70}
71
72/* Get Gaussian splat normal in the object space. */
73ccl_device_inline float3 gsplat_normal(
74 KernelGlobals kg, const int object, const int prim, const float time, const int primitive_type)
75{
76 /* Follows the "Flattening 3D Gaussian" section of [chen2024pgsr].
77 *
78 * The intuitive way to think about it is that gsplat is a pancake, so its normal in the Gaussian
79 * splat space points in the direction of the smallest scale (orthogonal to two largest scales).
80 * This means, for example, that if the scale's z component is the smallest then the normal in
81 * the splat space is (0, 0, 1).
82 *
83 * It needs to be converted to the object space. The naive implementation would be is
84 *
85 * N_{object_space} = R * N_{splat_space}
86 *
87 * where R is a transformation matrix constructed from the Gaussian splat rotation:
88 *
89 * R = quaternion_to_rotation(rotation_quat)
90 *
91 * We can avoid the matrix multiplication by utilizing the knowledge that the normal is the
92 * Gaussian splat space has only one component set to 1 and the rest are set to 0: the result
93 * is the column of the matrix R with the same index as the component of the local normal that is
94 * set to 1. */
95
96 /* TODO(sergey): Solve ambiguity when there are two smallest axis. */
97 /* The paper mentions this case explicitly and that it is solved using the view direction. */
98
101 if ((primitive_type & PRIMITIVE_MOTION) == 0) {
102 const int scale_offset = gsplat_attr_scale_offset(kg, object);
103 const int rotation_offset = gsplat_attr_rotation_offset(kg, object);
104 scale = kernel_data_fetch(attributes_float3, scale_offset + prim);
105 rotation = kernel_data_fetch(attributes_quaternion, rotation_offset + prim);
106 }
107 else {
108 const GSplatMotionInfo motion_info = motion_gsplat_compute_motion_info(kg, object, time);
109 scale = motion_gsplat_scale(kg, motion_info, object, prim);
110 rotation = motion_gsplat_rotation(kg, motion_info, object, prim);
111 }
112
113# if 0
114 /* The naive implementation, for the reference. */
115 const float3x3 R = quaternion_to_rotation(rotation);
116 if ((scale.x <= scale.y) && (scale.x <= scale.z)) {
117 return R * make_float3(1.0f, 0.0f, 0.0f);
118 }
119 if ((scale.y < scale.x) && (scale.y <= scale.z)) {
120 return R * make_float3(0.0f, 1.0f, 0.0f);
121 }
122 kernel_assert((scale.z < scale.x) && (scale.z < scale.y));
123 return R * make_float3(0.0f, 0.0f, 1.0f);
124# else
125 /* More optimal implementation: only evaluate the actually required elements of the rotation
126 * matrix. */
127 const float normalizer = 1.0f / (rotation.x * rotation.x + rotation.y * rotation.y +
128 rotation.z * rotation.z + rotation.w * rotation.w);
129
130 const float a = rotation.w;
131 const float b = rotation.x;
132 const float c = rotation.y;
133 const float d = rotation.z;
134
135 if ((scale.x <= scale.y) && (scale.x <= scale.z)) {
136 return make_float3(
137 a * a + b * b - c * c - d * d, 2.0f * (a * d + b * c), 2.0f * (b * d - a * c)) *
138 normalizer;
139 }
140 if ((scale.y < scale.x) && (scale.y <= scale.z)) {
141 return make_float3(
142 2.0f * (b * c - a * d), a * a - b * b + c * c - d * d, 2.0f * (a * b + c * d)) *
143 normalizer;
144 }
145 kernel_assert((scale.z < scale.x) && (scale.z < scale.y));
146 return make_float3(
147 2.0f * (a * c + b * d), 2.0f * (c * d - a * b), a * a - b * b - c * c + d * d) *
148 normalizer;
149# endif
150}
151
152#endif /* __GSPLATS__ */
153
ccl_device float3 color_srgb_to_linear_v3(const float3 c)
Definition color.h:317
#define kernel_assert(cond)
#define kernel_data_fetch(name, index)
#define ccl_private
#define ccl_device_inline
#define ccl_global
#define CCL_NAMESPACE_END
ccl_device_forceinline float3 make_float3(const float x, const float y, const float z)
void quaternion_to_rotation(float w, float x, float y, float z, float4 &rotation)
float3x3 scale(float3x3 mat, float2 scale)
VecT safe_normalize(VecT vector)
ccl_device_inline void object_inverse_dir_transform(KernelGlobals kg, const ccl_private ShaderData *sd, ccl_private float3 *D)
@ PRIMITIVE_MOTION
@ PRIMITIVE_GSPLAT
@ SD_OBJECT_TRANSFORM_APPLIED
@ ATTR_STD_NOT_FOUND
ccl_device float3 rec709_to_rgb(KernelGlobals kg, const float3 rec709)
ccl_device_inline float3 spherical_harmonics_evaluate_rest(const ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest, const float3 direction)
ccl_device_forceinline T spherical_harmonics_evaluate_band_L0(const float3 direction, const T M0)
#define R
CCL_NAMESPACE_BEGIN ccl_device_forceinline int gsplat_attr_radiance_base_offset(KernelGlobals kg, const int object)
ccl_device_forceinline int gsplat_attr_scale_offset(KernelGlobals kg, const int object)
ccl_device_forceinline int gsplat_attr_rotation_offset(KernelGlobals kg, const int object)