Blender V5.3
gpu_shader_math_spherical_harmonics.bsl.hh
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2023 Blender Authors
2 *
3 * SPDX-License-Identifier: GPL-2.0-or-later */
4
5#pragma once
6
9
10/* -------------------------------------------------------------------- */
25
27
28float L0_M0_coef(float3 /*v*/)
29{
30 return 0.282094792f;
31}
32
34{
35 return -0.488602512f * v.y;
36}
38{
39 return 0.488602512f * v.z;
40}
42{
43 return -0.488602512f * v.x;
44}
45
47{
48 return 1.092548431f * (v.x * v.y);
49}
51{
52 return -1.092548431f * (v.y * v.z);
53}
55{
56 return 0.315391565f * (3.0f * v.z * v.z - 1.0f);
57}
59{
60 return -1.092548431f * (v.x * v.z);
61}
63{
64 return 0.546274215f * (v.x * v.x - v.y * v.y);
65}
66
68{
69 return -0.590043589f * v.y * (3.0f * v.x * v.x - v.y * v.y);
70}
72{
73 return 2.890611442f * (v.y * v.x * v.z);
74}
76{
77 return -0.457045799f * v.y * (-1.0f + 5.0f * v.z * v.z);
78}
80{
81 return 0.373176332f * v.z * (5.0f * v.z * v.z - 3.0f);
82}
84{
85 return -0.457045799f * v.x * (-1.0f + 5.0f * v.z * v.z);
86}
88{
89 return 1.445305721f * v.z * (v.x * v.x - v.y * v.y);
90}
92{
93 return -0.5900435899f * v.x * (v.x * v.x - 3.0f * v.y * v.y);
94}
95
96template<typename T> struct BandL0 {
98
99 void encode_signal_sample(float3 direction, T amplitude)
100 {
101 M0 += L0_M0_coef(direction) * amplitude;
102 }
103
104 T evaluate(float3 direction) const
105 {
106 return L0_M0_coef(direction) * M0;
107 }
108
109 static BandL0<T> madd(BandL0<T> a, float b, BandL0<T> c)
110 {
111 BandL0<T> result;
112 result.M0 = a.M0 * b + c.M0;
113 return result;
114 }
115
117 {
118 BandL0<T> result;
119 result.M0 = a.M0 * b;
120 return result;
121 }
122
124 {
125 BandL0<T> result;
126 result.M0 = a.M0 * b;
127 return result;
128 }
129
131 {
132 BandL0<T> result;
133 result.M0 = a.M0 + b.M0;
134 return result;
135 }
136};
137
138template<typename T> struct BandL1 {
140
141 void encode_signal_sample(float3 direction, T amplitude)
142 {
143 Mn1 += L1_Mn1_coef(direction) * amplitude;
144 M0 += L1_M0_coef(direction) * amplitude;
145 Mp1 += L1_Mp1_coef(direction) * amplitude;
146 }
147
148 T evaluate(float3 direction) const
149 {
150 return L1_Mn1_coef(direction) * Mn1 + L1_M0_coef(direction) * M0 +
151 L1_Mp1_coef(direction) * Mp1;
152 }
153
154 static BandL1<T> madd(BandL1<T> a, float b, BandL1<T> c)
155 {
156 BandL1<T> result;
157 result.Mn1 = a.Mn1 * b + c.Mn1;
158 result.M0 = a.M0 * b + c.M0;
159 result.Mp1 = a.Mp1 * b + c.Mp1;
160 return result;
161 }
162
164 {
165 BandL1<T> result;
166 result.Mn1 = a.Mn1 * b;
167 result.M0 = a.M0 * b;
168 result.Mp1 = a.Mp1 * b;
169 return result;
170 }
171
173 {
174 BandL1<T> result;
175 result.Mn1 = a.Mn1 * b;
176 result.M0 = a.M0 * b;
177 result.Mp1 = a.Mp1 * b;
178 return result;
179 }
180
182 {
183 BandL1<T> result;
184 result.Mn1 = a.Mn1 + b.Mn1;
185 result.M0 = a.M0 + b.M0;
186 result.Mp1 = a.Mp1 + b.Mp1;
187 return result;
188 }
189};
190
191template<typename T> struct BandL2 {
193
194 void encode_signal_sample(float3 direction, T amplitude)
195 {
196 Mn2 += L2_Mn2_coef(direction) * amplitude;
197 Mn1 += L2_Mn1_coef(direction) * amplitude;
198 M0 += L2_M0_coef(direction) * amplitude;
199 Mp1 += L2_Mp1_coef(direction) * amplitude;
200 Mp2 += L2_Mp2_coef(direction) * amplitude;
201 }
202
203 T evaluate(float3 direction) const
204 {
205 return L2_Mn2_coef(direction) * Mn2 + L2_Mn1_coef(direction) * Mn1 +
206 L2_M0_coef(direction) * M0 + L2_Mp1_coef(direction) * Mp1 +
207 L2_Mp2_coef(direction) * Mp2;
208 }
209
210 static BandL2 madd(BandL2 a, float b, BandL2 c)
211 {
212 BandL2 result;
213 result.Mn2 = a.Mn2 * b + c.Mn2;
214 result.Mn1 = a.Mn1 * b + c.Mn1;
215 result.M0 = a.M0 * b + c.M0;
216 result.Mp1 = a.Mp1 * b + c.Mp1;
217 result.Mp2 = a.Mp2 * b + c.Mp2;
218 return result;
219 }
220
221 static BandL2 mul(BandL2 a, float b)
222 {
223 BandL2 result;
224 result.Mn2 = a.Mn2 * b;
225 result.Mn1 = a.Mn1 * b;
226 result.M0 = a.M0 * b;
227 result.Mp1 = a.Mp1 * b;
228 result.Mp2 = a.Mp2 * b;
229 return result;
230 }
231
233 {
234 BandL2 result;
235 result.Mn2 = a.Mn2 + b.Mn2;
236 result.Mn1 = a.Mn1 + b.Mn1;
237 result.M0 = a.M0 + b.M0;
238 result.Mp1 = a.Mp1 + b.Mp1;
239 result.Mp2 = a.Mp2 + b.Mp2;
240 return result;
241 }
242};
243
244template<typename T> struct BandL3 {
246
247 void encode_signal_sample(float3 direction, T amplitude)
248 {
249 Mn3 += L3_Mn3_coef(direction) * amplitude;
250 Mn2 += L3_Mn2_coef(direction) * amplitude;
251 Mn1 += L3_Mn1_coef(direction) * amplitude;
252 M0 += L3_M0_coef(direction) * amplitude;
253 Mp1 += L3_Mp1_coef(direction) * amplitude;
254 Mp2 += L3_Mp2_coef(direction) * amplitude;
255 Mp3 += L3_Mp3_coef(direction) * amplitude;
256 }
257
258 T evaluate(float3 direction) const
259 {
260 return L3_Mn3_coef(direction) * Mn3 + L3_Mn2_coef(direction) * Mn2 +
261 L3_Mn1_coef(direction) * Mn1 + L3_M0_coef(direction) * M0 +
262 L3_Mp1_coef(direction) * Mp1 + L3_Mp2_coef(direction) * Mp2 +
263 L3_Mp3_coef(direction) * Mp3;
264 }
265
266 static BandL3 madd(BandL3 a, float b, BandL3 c)
267 {
268 BandL3 result;
269 result.Mn3 = a.Mn3 * b + c.Mn3;
270 result.Mn2 = a.Mn2 * b + c.Mn2;
271 result.Mn1 = a.Mn1 * b + c.Mn1;
272 result.M0 = a.M0 * b + c.M0;
273 result.Mp1 = a.Mp1 * b + c.Mp1;
274 result.Mp2 = a.Mp2 * b + c.Mp2;
275 result.Mp3 = a.Mp3 * b + c.Mp3;
276 return result;
277 }
278
279 static BandL3 mul(BandL3 a, float b)
280 {
281 BandL3 result;
282 result.Mn3 = a.Mn3 * b;
283 result.Mn2 = a.Mn2 * b;
284 result.Mn1 = a.Mn1 * b;
285 result.M0 = a.M0 * b;
286 result.Mp1 = a.Mp1 * b;
287 result.Mp2 = a.Mp2 * b;
288 result.Mp3 = a.Mp3 * b;
289 return result;
290 }
291
293 {
294 BandL3 result;
295 result.Mn3 = a.Mn3 + b.Mn3;
296 result.Mn2 = a.Mn2 + b.Mn2;
297 result.Mn1 = a.Mn1 + b.Mn1;
298 result.M0 = a.M0 + b.M0;
299 result.Mp1 = a.Mp1 + b.Mp1;
300 result.Mp2 = a.Mp2 + b.Mp2;
301 result.Mp3 = a.Mp3 + b.Mp3;
302 return result;
303 }
304};
305
306template struct BandL0<float>;
307template struct BandL0<float3>;
308template struct BandL0<float4>;
309template struct BandL1<float>;
310template struct BandL1<float3>;
311template struct BandL1<float4>;
312template struct BandL2<float>;
313template struct BandL2<float3>;
314template struct BandL2<float4>;
315template struct BandL3<float>;
316template struct BandL3<float3>;
317template struct BandL3<float4>;
318
319} // namespace spherical_harmonics
320
321template<typename T> struct SphericalHarmonicL1 {
324
325 /* Decompose an input signal into spherical harmonic coefficients.
326 * Note that `amplitude` need to be scaled by solid angle. */
327 void encode_signal_sample(float3 direction, T amplitude)
328 {
329 L0.encode_signal_sample(direction, amplitude);
330 L1.encode_signal_sample(direction, amplitude);
331 }
332
333 /* Evaluate an encoded signal in a given unit vector direction. */
334 T evaluate(float3 direction) const
335 {
336 T eval = L0.evaluate(direction) + L1.evaluate(direction);
337 return max(T(0.0f), eval);
338 }
339
347 {
348 T radiance = L0.evaluate(N) + L1.evaluate(N) * (2.0f / 3.0f);
349 return max(T(0.0f), radiance);
350 }
351
352#if 0 /* Not used. */
353 float3 evaluate_lambert_non_linear(float3 N) const
354 {
355 /* Shuffling based on L1_* functions. */
356 float3 R1_r = float3(-L1.Mp1.r, -L1.Mn1.r, L1.M0.r);
357 float3 R1_g = float3(-L1.Mp1.g, -L1.Mn1.g, L1.M0.g);
358 float3 R1_b = float3(-L1.Mp1.b, -L1.Mn1.b, L1.M0.b);
359
360 float3 radiance = float3(evaluate_non_linear(N, L0.M0.r, R1_r),
361 evaluate_non_linear(N, L0.M0.g, R1_g),
362 evaluate_non_linear(N, L0.M0.b, R1_b));
363 /* Return lambertian radiance. So divide by PI. */
364 return radiance / M_PI;
365 }
366
367 private:
373 static float evaluate_non_linear(float3 N, float R0, float3 R1)
374 {
375 /* No idea why this is needed. */
376 R1 /= 2.0f;
377
378 float R1_len;
379 float3 R1_dir = normalize_and_get_length(R1, R1_len);
380 float rcp_R0 = safe_rcp(R0);
381
382 float q = (1.0f + dot(R1_dir, N)) / 2.0f;
383 float p = 1.0f + 2.0f * R1_len * rcp_R0;
384 float a = (1.0f - R1_len * rcp_R0) * safe_rcp(1.0f + R1_len * rcp_R0);
385
386 return R0 * (a + (1.0f - a) * (p + 1.0f) * pow(q, p));
387 }
388#endif
389};
390
391template struct SphericalHarmonicL1<float>;
392template struct SphericalHarmonicL1<float4>;
393
395
396namespace spherical_harmonics {
397
398/* -------------------------------------------------------------------- */
403
405 float4 L0_L1_b,
406 float4 L0_L1_c,
407 float4 L0_L1_vis)
408{
410 sh.L0.M0.xyz = L0_L1_a.xyz;
411 sh.L1.Mn1.xyz = L0_L1_b.xyz;
412 sh.L1.M0.xyz = L0_L1_c.xyz;
413 sh.L1.Mp1.xyz = float3(L0_L1_a.w, L0_L1_b.w, L0_L1_c.w);
414 sh.L0.M0.w = L0_L1_vis.x;
415 sh.L1.Mn1.w = L0_L1_vis.y;
416 sh.L1.M0.w = L0_L1_vis.z;
417 sh.L1.Mp1.w = L0_L1_vis.w;
418 return sh;
419}
420
422 float4 &L0_L1_a,
423 float4 &L0_L1_b,
424 float4 &L0_L1_c,
425 float4 &L0_L1_vis)
426{
427 L0_L1_a.xyz = sh.L0.M0.xyz;
428 L0_L1_b.xyz = sh.L1.Mn1.xyz;
429 L0_L1_c.xyz = sh.L1.M0.xyz;
430 L0_L1_a.w = sh.L1.Mp1.x;
431 L0_L1_b.w = sh.L1.Mp1.y;
432 L0_L1_c.w = sh.L1.Mp1.z;
433 L0_L1_vis = float4(sh.L0.M0.w, sh.L1.Mn1.w, sh.L1.M0.w, sh.L1.Mp1.w);
434}
435
437
438/* -------------------------------------------------------------------- */
441
444{
445 /* Adapted from:
446 * "Code Generation and Factoring for Fast Evaluation of Low-order Spherical Harmonic Products
447 * and Squares" Function "SH_product_3". */
448 constexpr float L0_M0_coef = 0.282094792f;
450 sh.L0.M0 = a.L0.M0 * b.L0.M0;
451 sh.L0.M0 += a.L1.Mn1 * b.L1.Mn1;
452 sh.L0.M0 += a.L1.M0 * b.L1.M0;
453 sh.L0.M0 += a.L1.Mp1 * b.L1.Mp1;
454 sh.L0.M0 *= L0_M0_coef;
455
456 sh.L1.Mn1 = L0_M0_coef * (a.L0.M0 * b.L1.Mn1 + b.L0.M0 * a.L1.Mn1);
457 sh.L1.M0 = L0_M0_coef * (a.L0.M0 * b.L1.M0 + b.L0.M0 * a.L1.M0);
458 sh.L1.Mp1 = L0_M0_coef * (a.L0.M0 * b.L1.Mp1 + b.L0.M0 * a.L1.Mp1);
459 return sh;
460}
461
463
464/* -------------------------------------------------------------------- */
467
469 float b,
471{
473 result.L0 = BandL0<float4>::madd(a.L0, b, c.L0);
474 result.L1 = BandL1<float4>::madd(a.L1, b, c.L1);
475 return result;
476}
477
479{
481 result.L0 = BandL0<float4>::mul_scalar(a.L0, b);
482 result.L1 = BandL1<float4>::mul_scalar(a.L1, b);
483 return result;
484}
485
487{
489 result.L0 = BandL0<float4>::mul(a.L0, b);
490 result.L1 = BandL1<float4>::mul(a.L1, b);
491 return result;
492}
493
501
503{
504 /* Convert L1 coefficients to per channel column.
505 * Note the component shuffle to match blender coordinate system. */
506 float4x3 per_channel = transpose(float3x4(sh.L1.Mp1, sh.L1.Mn1, -sh.L1.M0));
507 /* Rotate each channel. */
508 per_channel[0] = rotation * per_channel[0];
509 per_channel[1] = rotation * per_channel[1];
510 per_channel[2] = rotation * per_channel[2];
511 per_channel[3] = rotation * per_channel[3];
512 /* Convert back from L1 coefficients to per channel column.
513 * Note the component shuffle to match blender coordinate system. */
514 float3x4 per_coef = transpose(per_channel);
515 sh.L1.Mn1 = per_coef[1];
516 sh.L1.M0 = -per_coef[2];
517 sh.L1.Mp1 = per_coef[0];
518 /* NOTE: L0 band being a constant function (i.e: there is no directionality) there is nothing to
519 * rotate. */
520 return sh;
521}
522
524
525/* -------------------------------------------------------------------- */
528
530{
531 /* Convert coefficients to per channel column. */
532 float4x4 a_mat = transpose(float4x4(a.L0.M0, a.L1.Mn1, a.L1.M0, a.L1.Mp1));
533 float4x4 b_mat = transpose(float4x4(b.L0.M0, b.L1.Mn1, b.L1.M0, b.L1.Mp1));
534 float4 result;
535 result[0] = ::dot(a_mat[0], b_mat[0]);
536 result[1] = ::dot(a_mat[1], b_mat[1]);
537 result[2] = ::dot(a_mat[2], b_mat[2]);
538 result[3] = ::dot(a_mat[3], b_mat[3]);
539 return result;
540}
541
543
544/* -------------------------------------------------------------------- */
549
551{
553 result.L0 = sh.L0;
554 float4 fac = safe_rcp(sh.L0.M0 * M_SQRT3);
555 result.L1.Mn1 = (sh.L1.Mn1 * fac) * 0.5f + 0.5f;
556 result.L1.M0 = (sh.L1.M0 * fac) * 0.5f + 0.5f;
557 result.L1.Mp1 = (sh.L1.Mp1 * fac) * 0.5f + 0.5f;
558 return result;
559}
560
562{
564 result.L0 = sh.L0;
565 float4 fac = sh.L0.M0 * M_SQRT3;
566 result.L1.Mn1 = (sh.L1.Mn1 * 2.0f - 1.0f) * fac;
567 result.L1.M0 = (sh.L1.M0 * 2.0f - 1.0f) * fac;
568 result.L1.Mp1 = (sh.L1.Mp1 * 2.0f - 1.0f) * fac;
569 return result;
570}
571
573
574/* -------------------------------------------------------------------- */
579
581{
582 float L0_weight = 0.282094792f;
583 float L1_weight = 0.488602512f;
584 /* Multiply by lambert convolution weight (see #evaluate_lambert). */
585 L1_weight *= (2.0f / 3.0f);
586 /* Add some bias to avoid too much unrealistic contrast. */
587 L1_weight += 0.05f;
588
589 /* Convert coefficients to per channel column. */
590 const float4x4 m = transpose(float4x4(max(abs(sh.L0.M0) * L0_weight, float4(1e-8f)),
591 abs(sh.L1.Mn1),
592 abs(sh.L1.M0),
593 abs(sh.L1.Mp1)));
594
595 /* Multiply by each band's weight. */
596 /* Find maximum value the L1 band can contain that doesn't exhibit ringing artifacts. */
597 float fac_r = m[0].x / max(1e-8f, length(m[0].yzw) * L1_weight);
598 float fac_g = m[1].x / max(1e-8f, length(m[1].yzw) * L1_weight);
599 float fac_b = m[2].x / max(1e-8f, length(m[2].yzw) * L1_weight);
600 /* Choose the factor for the component with higher directionality and apply it on all component.
601 * Otherwise this can result in color drifting. */
602 float fac = reduce_min(float3(fac_r, fac_g, fac_b));
603 if (fac < 1.0f) {
604 sh.L1 = BandL1<float4>::mul(sh.L1, float4(fac));
605 }
606 return sh;
607}
608
610
611/* -------------------------------------------------------------------- */
616
618{
619 /* Convert coefficients to per channel column. */
620 float4x4 per_channel = transpose(float4x4(sh.L0.M0, sh.L1.Mn1, sh.L1.M0, sh.L1.Mp1));
621 /* Magnitude per channel. */
622 float3 mag_L1;
623 mag_L1.r = length(per_channel[0].yzw);
624 mag_L1.g = length(per_channel[1].yzw);
625 mag_L1.b = length(per_channel[2].yzw);
626 /* Find maximum of the sh function over all channels. */
627 float3 max_sh = abs(sh.L0.M0.rgb) * 0.282094792f + mag_L1 * 0.488602512f;
628
629 float fac = clamp_value * safe_rcp(reduce_max(max_sh));
630 if (fac < 1.0f) {
631 sh = spherical_harmonics::mul(sh, fac);
632 }
633 return sh;
634}
635
637
638} // namespace spherical_harmonics
#define M_SQRT3
#define M_PI
btScalar max
#define pow
float dot(VecOp< float, D >, VecOp< float, D >) RET
#define abs
MatBase< R, C > transpose(MatBase< C, R >) RET
float length(VecOp< float, D >) RET
MatBase< 4, 3 > float4x3
void clamp_value(float value, float min, float max, float &result)
float safe_rcp(float a)
VecT normalize_and_get_length(VecT vector, float &out_length)
float reduce_min(float2 a)
float reduce_max(float2 a)
#define N
#define T
MatBase< float, 4, 4 > float4x4
MatBase< float, 3, 4 > float3x4
VecBase< float, 3 > float3
SphericalHarmonicL1< float4 > add(SphericalHarmonicL1< float4 > a, SphericalHarmonicL1< float4 > b)
void pack(SphericalHarmonicL1< float4 > sh, float4 &L0_L1_a, float4 &L0_L1_b, float4 &L0_L1_c, float4 &L0_L1_vis)
SphericalHarmonicL1< float4 > unpack(float4 L0_L1_a, float4 L0_L1_b, float4 L0_L1_c, float4 L0_L1_vis)
SphericalHarmonicL1< float4 > mul(SphericalHarmonicL1< float4 > a, float b)
SphericalHarmonicL1< float4 > clamp_energy(SphericalHarmonicL1< float4 > sh, float clamp_value)
SphericalHarmonicL1< float4 > rotate(float3x3 rotation, SphericalHarmonicL1< float4 > sh)
SphericalHarmonicL1< float4 > compress(SphericalHarmonicL1< float4 > sh)
SphericalHarmonicL1< float4 > triple_product(SphericalHarmonicL1< float4 > a, SphericalHarmonicL1< float4 > b)
SphericalHarmonicL1< float4 > madd(SphericalHarmonicL1< float4 > a, float b, SphericalHarmonicL1< float4 > c)
SphericalHarmonicL1< float4 > dering(SphericalHarmonicL1< float4 > sh)
float4 dot(SphericalHarmonicL1< float4 > a, SphericalHarmonicL1< float4 > b)
SphericalHarmonicL1< float4 > decompress(SphericalHarmonicL1< float4 > sh)
spherical_harmonics::BandL1< T > L1
spherical_harmonics::BandL0< T > L0
void encode_signal_sample(float3 direction, T amplitude)
float y
Definition sky_math.h:225
float z
Definition sky_math.h:225
float x
Definition sky_math.h:225
float w
Definition sky_math.h:225
static BandL0< T > add(BandL0< T > a, BandL0< T > b)
static BandL0< T > mul(BandL0< T > a, T b)
static BandL0< T > madd(BandL0< T > a, float b, BandL0< T > c)
static BandL0< T > mul_scalar(BandL0< T > a, float b)
void encode_signal_sample(float3 direction, T amplitude)
static BandL1< T > add(BandL1< T > a, BandL1< T > b)
static BandL1< T > mul(BandL1< T > a, T b)
static BandL1< T > madd(BandL1< T > a, float b, BandL1< T > c)
void encode_signal_sample(float3 direction, T amplitude)
static BandL1< T > mul_scalar(BandL1< T > a, float b)
void encode_signal_sample(float3 direction, T amplitude)
static BandL2 madd(BandL2 a, float b, BandL2 c)
static BandL3 madd(BandL3 a, float b, BandL3 c)
void encode_signal_sample(float3 direction, T amplitude)