Blender V5.3
types_spherical_harmonics.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 "util/defines.h"
8#include "util/math_float3.h"
9#include "util/types_base.h"
10#include "util/types_float3.h"
11
12#if !defined(__KERNEL_GPU__)
13# include <cstring> /* for memset(). */
14#endif
15
17
18/* A packed representation of spherical harmonics for bands 1 to 3.
19 *
20 * The spherical harmonics for band=0 is stored as a separate attribute. Such division allows for
21 * slightly better packing with opacity, and also allows to have higher bands optional.
22 *
23 * The naming is inspired by the storage of Gaussians splats in the PLY format, where the band=0
24 * is stored as f_dc, and the higher bands are stored as f_rest.
25 *
26 * The values are quantized to 8 bit.
27 *
28 * The order is: <L=1 M=-1>, <L=1 M=0>, <L=1 M=1>, <L=2 M=-2> ...
29 * where L is the band index, M is the basis function.
30 *
31 * NOTE: There is an utility spherical_harmonics_get<L, M> to access bands in a more semantic way.
32 */
34 /* Some formats (like SPZ) define the maximum degree as 4.
35 * However, in practice it is hard to run across dataset that is actually trained using such
36 * high degree, and the difference that the higher degree brings is probably barely perceivable.
37 * To keep logic simple, assume the most commonly used degree of 3, and allocate coefficients for
38 * it. */
41
43
44 /* NOTE: Can not have methods here, as the kernel references data from global memory, which makes
45 * it tricky on Metal that either doesn't support it or requires some non-trivial way, as calling
46 * methods from a `ccl_global PackedSphericalHarmonicsRest *` conflicts with the address space
47 * for `this`. */
48};
49
50/* Quantize spherical harmonics coefficients from float to uint8_t.
51 * Similar to the float_to_byte(), but deals with input values in the range [-1 .. 1]. */
53{
54 const float rescaled = saturatef((value + 1.0f) / 2.0f);
55 return float_to_byte(rescaled);
56}
57
59{
60 return byte_to_float(value) * 2.0f - 1.0f;
61}
62
63/* Set all spherical harmonics values to 0. */
65 ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest)
66{
67 /* Note this is not the same as integer 0. */
68 const uint8_t zero = quantize_spherical_harmonics(0.0f);
69#if !defined(__KERNEL_GPU__)
70 memset(packed_spherical_harmonics_rest.coefficients,
71 zero,
72 sizeof(packed_spherical_harmonics_rest.coefficients));
73#else
74 /* Metal does not support memset() call. */
75 for (int i = 0; i < 3 * PackedSphericalHarmonicsRest::MAX_COEFFICIENTS; ++i) {
76 packed_spherical_harmonics_rest.coefficients[i] = zero;
77 }
78#endif
79}
80
81/* Set the spherical harmonic coefficient by its flat index. */
83 ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest,
84 const int index,
85 const float3 value)
86{
87 util_assert(index >= 0);
89 const int i = index * 3;
90 packed_spherical_harmonics_rest.coefficients[i + 0] = quantize_spherical_harmonics(value.x);
91 packed_spherical_harmonics_rest.coefficients[i + 1] = quantize_spherical_harmonics(value.y);
92 packed_spherical_harmonics_rest.coefficients[i + 2] = quantize_spherical_harmonics(value.z);
93}
94
95/* Get unquantized spherical harmonics coefficient by its flat index. */
97 const ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest,
98 const int index)
99{
100 util_assert(index >= 0);
102 const int i = index * 3;
103 return make_float3(
104 unquantize_spherical_harmonics(packed_spherical_harmonics_rest.coefficients[i + 0]),
105 unquantize_spherical_harmonics(packed_spherical_harmonics_rest.coefficients[i + 1]),
106 unquantize_spherical_harmonics(packed_spherical_harmonics_rest.coefficients[i + 2]));
107}
108
109/* Get unquantized spherical harmonics coefficient by the band L and the basis function M. */
110template<int L, int M>
112 const ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest);
113
114/* Band L=1. */
116 const ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest)
117{
118 return spherical_harmonics_rest_get_coefficient(packed_spherical_harmonics_rest, 0);
119}
121 const ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest)
122{
123 return spherical_harmonics_rest_get_coefficient(packed_spherical_harmonics_rest, 1);
124}
126 const ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest)
127{
128 return spherical_harmonics_rest_get_coefficient(packed_spherical_harmonics_rest, 2);
129}
130
131/* Band L=2. */
133 const ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest)
134{
135 return spherical_harmonics_rest_get_coefficient(packed_spherical_harmonics_rest, 3);
136}
138 const ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest)
139{
140 return spherical_harmonics_rest_get_coefficient(packed_spherical_harmonics_rest, 4);
141}
143 const ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest)
144{
145 return spherical_harmonics_rest_get_coefficient(packed_spherical_harmonics_rest, 5);
146}
148 const ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest)
149{
150 return spherical_harmonics_rest_get_coefficient(packed_spherical_harmonics_rest, 6);
151}
153 const ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest)
154{
155 return spherical_harmonics_rest_get_coefficient(packed_spherical_harmonics_rest, 7);
156}
157
158/* Band L=3. */
160 const ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest)
161{
162 return spherical_harmonics_rest_get_coefficient(packed_spherical_harmonics_rest, 8);
163}
165 const ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest)
166{
167 return spherical_harmonics_rest_get_coefficient(packed_spherical_harmonics_rest, 9);
168}
170 const ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest)
171{
172 return spherical_harmonics_rest_get_coefficient(packed_spherical_harmonics_rest, 10);
173}
175 const ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest)
176{
177 return spherical_harmonics_rest_get_coefficient(packed_spherical_harmonics_rest, 11);
178}
180 const ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest)
181{
182 return spherical_harmonics_rest_get_coefficient(packed_spherical_harmonics_rest, 12);
183}
185 const ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest)
186{
187 return spherical_harmonics_rest_get_coefficient(packed_spherical_harmonics_rest, 13);
188}
190 const ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest)
191{
192 return spherical_harmonics_rest_get_coefficient(packed_spherical_harmonics_rest, 14);
193}
194
#define util_assert(statement)
#define ccl_device_forceinline
#define ccl_device_inline
#define ccl_device_template_spec
#define ccl_global
#define ccl_static_constexpr
#define CCL_NAMESPACE_END
#define saturatef(x)
ccl_device_forceinline float3 make_float3(const float x, const float y, const float z)
#define index(i)
ccl_device_inline float byte_to_float(const uchar val)
Definition math_base.h:1008
ccl_device_inline uchar float_to_byte(const float val)
Definition math_base.h:999
ccl_static_constexpr int MAX_COEFFICIENTS
uint8_t coefficients[3 *MAX_COEFFICIENTS]
float z
Definition sky_math.h:136
float y
Definition sky_math.h:136
float x
Definition sky_math.h:136
ccl_device_forceinline void spherical_harmonics_rest_fill_zero(ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest)
ccl_device_forceinline float3 spherical_harmonics_rest_get_coefficient(const ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest, const int index)
ccl_device_forceinline void spherical_harmonics_rest_set_coefficient(ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest, const int index, const float3 value)
ccl_device_inline float3 spherical_harmonics_get(const ccl_global PackedSphericalHarmonicsRest &packed_spherical_harmonics_rest)
ccl_device_forceinline uint8_t quantize_spherical_harmonics(const float value)
ccl_device_forceinline float unquantize_spherical_harmonics(const uint8_t value)