Debian Codegraph @

libs/ibl/src/CubemapSH.cpp

raw
1 /*
2 * Copyright (C) 2015 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 #include <ibl/CubemapSH.h>
18
19 #include <ibl/Cubemap.h>
20 #include <ibl/CubemapUtils.h>
21 #include <ibl/utilities.h>
22
23 #include "CubemapUtilsImpl.h"
24
25 #include <utils/JobSystem.h>
26
27 #include <math/mat4.h>
28
29 #include <array>
30 #include <limits>
31 #include <iomanip>
32
33 using namespace filament::math;
34 using namespace utils;
35
36 namespace filament {
37 namespace ibl {
38
39 // -----------------------------------------------------------------------------------------------
40 // A few useful utilities
41 // -----------------------------------------------------------------------------------------------
42
43 /*
44 * returns n! / d!
45 */
46 static constexpr float factorial(size_t n, size_t d = 1) {
47 d = std::max(size_t(1), d);
48 n = std::max(size_t(1), n);
49 float r = 1.0;
50 if (n == d) {
51 // intentionally left blank
52 } else if (n > d) {
53 for ( ; n>d ; n--) {
54 r *= n;
55 }
56 } else {
57 for ( ; d>n ; d--) {
58 r *= d;
59 }
60 r = 1.0f / r;
61 }
62 return r;
63 }
64
65 // -----------------------------------------------------------------------------------------------
66
67 /*
68 * SH scaling factors:
69 * returns sqrt((2*l + 1) / 4*pi) * sqrt( (l-|m|)! / (l+|m|)! )
70 */
71 float CubemapSH::Kml(ssize_t m, size_t l) {
72 m = m < 0 ? -m : m; // abs() is not constexpr
73 const float K = (2 * l + 1) * factorial(size_t(l - m), size_t(l + m));
74 return std::sqrt(K) * (F_2_SQRTPI * 0.25);
75 }
76
77 std::vector<float> CubemapSH::Ki(size_t numBands) {
78 const size_t numCoefs = numBands * numBands;
79 std::vector<float> K(numCoefs);
80 for (size_t l = 0; l < numBands; l++) {
81 K[SHindex(0, l)] = Kml(0, l);
82 for (size_t m = 1; m <= l; m++) {
83 K[SHindex(m, l)] =
84 K[SHindex(-m, l)] = F_SQRT2 * Kml(m, l);
85 }
86 }
87 return K;
88 }
89
90 // < cos(theta) > SH coefficients pre-multiplied by 1 / K(0,l)
91 constexpr float CubemapSH::computeTruncatedCosSh(size_t l) {
92 if (l == 0) {
93 return F_PI;
94 } else if (l == 1) {
95 return 2 * F_PI / 3;
96 } else if (l & 1u) {
97 return 0;
98 }
99 const size_t l_2 = l / 2;
100 float A0 = ((l_2 & 1u) ? 1.0f : -1.0f) / ((l + 2) * (l - 1));
101 float A1 = factorial(l, l_2) / (factorial(l_2) * (1 << l));
102 return 2 * F_PI * A0 * A1;
103 }
104
105 /*
106 * Calculates non-normalized SH bases, i.e.:
107 * m > 0, cos(m*phi) * P(m,l)
108 * m < 0, sin(|m|*phi) * P(|m|,l)
109 * m = 0, P(0,l)
110 */
111 void CubemapSH::computeShBasis(
112 float* UTILS_RESTRICT SHb,
113 size_t numBands,
114 const float3& s)
115 {
116 #if 0
117 // Reference implementation
118 float phi = atan2(s.x, s.y);
119 for (size_t l = 0; l < numBands; l++) {
120 SHb[SHindex(0, l)] = Legendre(l, 0, s.z);
121 for (size_t m = 1; m <= l; m++) {
122 float p = Legendre(l, m, s.z);
123 SHb[SHindex(-m, l)] = std::sin(m * phi) * p;
124 SHb[SHindex( m, l)] = std::cos(m * phi) * p;
125 }
126 }
127 #endif
128
129 /*
130 * TODO: all the Legendre computation below is identical for all faces, so it
131 * might make sense to pre-compute it once. Also note that there is
132 * a fair amount of symmetry within a face (which we could take advantage of
133 * to reduce the pre-compute table).
134 */
135
136 /*
137 * Below, we compute the associated Legendre polynomials using recursion.
138 * see: http://mathworld.wolfram.com/AssociatedLegendrePolynomial.html
139 *
140 * Note [0]: s.z == cos(theta) ==> we only need to compute P(s.z)
141 *
142 * Note [1]: We in fact compute P(s.z) / sin(theta)^|m|, by removing
143 * the "sqrt(1 - s.z*s.z)" [i.e.: sin(theta)] factor from the recursion.
144 * This is later corrected in the ( cos(m*phi), sin(m*phi) ) recursion.
145 */
146
147 // s = (x, y, z) = (sin(theta)*cos(phi), sin(theta)*sin(phi), cos(theta))
148
149 // handle m=0 separately, since it produces only one coefficient
150 float Pml_2 = 0;
151 float Pml_1 = 1;
152 SHb[0] = Pml_1;
153 for (size_t l=1; l<numBands; l++) {
154 float Pml = ((2*l-1.0f)*Pml_1*s.z - (l-1.0f)*Pml_2) / l;
155 Pml_2 = Pml_1;
156 Pml_1 = Pml;
157 SHb[SHindex(0, l)] = Pml;
158 }
159 float Pmm = 1;
160 for (size_t m=1 ; m<numBands ; m++) {
161 Pmm = (1.0f - 2*m) * Pmm; // See [1], divide by sqrt(1 - s.z*s.z);
162 Pml_2 = Pmm;
163 Pml_1 = (2*m + 1.0f)*Pmm*s.z;
164 // l == m
165 SHb[SHindex(-m, m)] = Pml_2;
166 SHb[SHindex( m, m)] = Pml_2;
167 if (m+1 < numBands) {
168 // l == m+1
169 SHb[SHindex(-m, m+1)] = Pml_1;
170 SHb[SHindex( m, m+1)] = Pml_1;
171 for (size_t l=m+2 ; l<numBands ; l++) {
172 float Pml = ((2*l - 1.0f)*Pml_1*s.z - (l + m - 1.0f)*Pml_2) / (l-m);
173 Pml_2 = Pml_1;
174 Pml_1 = Pml;
175 SHb[SHindex(-m, l)] = Pml;
176 SHb[SHindex( m, l)] = Pml;
177 }
178 }
179 }
180
181 // At this point, SHb contains the associated Legendre polynomials divided
182 // by sin(theta)^|m|. Below we compute the SH basis.
183 //
184 // ( cos(m*phi), sin(m*phi) ) recursion:
185 // cos(m*phi + phi) == cos(m*phi)*cos(phi) - sin(m*phi)*sin(phi)
186 // sin(m*phi + phi) == sin(m*phi)*cos(phi) + cos(m*phi)*sin(phi)
187 // cos[m+1] == cos[m]*s.x - sin[m]*s.y
188 // sin[m+1] == sin[m]*s.x + cos[m]*s.y
189 //
190 // Note that (d.x, d.y) == (cos(phi), sin(phi)) * sin(theta), so the
191 // code below actually evaluates:
192 // (cos((m*phi), sin(m*phi)) * sin(theta)^|m|
193 float Cm = s.x;
194 float Sm = s.y;
195 for (size_t m = 1; m <= numBands; m++) {
196 for (size_t l = m; l < numBands; l++) {
197 SHb[SHindex(-m, l)] *= Sm;
198 SHb[SHindex( m, l)] *= Cm;
199 }
200 float Cm1 = Cm * s.x - Sm * s.y;
201 float Sm1 = Sm * s.x + Cm * s.y;
202 Cm = Cm1;
203 Sm = Sm1;
204 }
205 }
206
207
208 /*
209 * utilities to rotate very low order spherical harmonics (up to 3rd band)
210 */
211 float3 CubemapSH::rotateShericalHarmonicBand1(float3 band1, mat3f const& M) {
212
213 // inverse() is not constexpr -- so we pre-calculate it in mathematica
214 //
215 // constexpr float3 N0{ 1, 0, 0 };
216 // constexpr float3 N1{ 0, 1, 0 };
217 // constexpr float3 N2{ 0, 0, 1 };
218 //
219 // constexpr mat3f A1 = { // this is the projection of N0, N1, N2 to SH space
220 // float3{ -N0.y, N0.z, -N0.x },
221 // float3{ -N1.y, N1.z, -N1.x },
222 // float3{ -N2.y, N2.z, -N2.x }
223 // };
224 //
225 // const mat3f invA1 = inverse(A1);
226
227 constexpr mat3f invA1TimesK = {
228 float3{ 0, -1, 0 },
229 float3{ 0, 0, 1 },
230 float3{-1, 0, 0 }
231 };
232
233 // below can't be constexpr
234 const float3 MN0 = M[0]; // M * N0;
235 const float3 MN1 = M[1]; // M * N1;
236 const float3 MN2 = M[2]; // M * N2;
237 const mat3f R1OverK = {
238 float3{ -MN0.y, MN0.z, -MN0.x },
239 float3{ -MN1.y, MN1.z, -MN1.x },
240 float3{ -MN2.y, MN2.z, -MN2.x }
241 };
242
243 return R1OverK * (invA1TimesK * band1);
244 }
245
246 CubemapSH::float5 CubemapSH::rotateShericalHarmonicBand2(float5 const& band2, mat3f const& M) {
247 constexpr float M_SQRT_3 = 1.7320508076f;
248 constexpr float n = F_SQRT1_2;
249
250 // Below we precompute (with help of Mathematica):
251 // constexpr float3 N0{ 1, 0, 0 };
252 // constexpr float3 N1{ 0, 0, 1 };
253 // constexpr float3 N2{ n, n, 0 };
254 // constexpr float3 N3{ n, 0, n };
255 // constexpr float3 N4{ 0, n, n };
256 // constexpr float M_SQRT_PI = 1.7724538509f;
257 // constexpr float M_SQRT_15 = 3.8729833462f;
258 // constexpr float k = M_SQRT_15 / (2.0f * M_SQRT_PI);
259 // --> k * inverse(mat5{project(N0), project(N1), project(N2), project(N3), project(N4)})
260 constexpr float5 invATimesK[5] = {
261 { 0, 1, 2, 0, 0 },
262 { -1, 0, 0, 0, -2 },
263 { 0, M_SQRT_3, 0, 0, 0 },
264 { 1, 1, 0, -2, 0 },
265 { 2, 1, 0, 0, 0 }
266 };
267
268 // This projects a vec3 to SH2/k space (i.e. we premultiply by 1/k)
269 // below can't be constexpr
270 auto project = [](float3 s) -> float5 {
271 return {
272 (s.y * s.x),
273 - (s.y * s.z),
274 1 / (2 * M_SQRT_3) * ((3 * s.z * s.z - 1)),
275 - (s.z * s.x),
276 0.5f * ((s.x * s.x - s.y * s.y))
277 };
278 };
279
280 // this is: invA * k * band2
281 // 5x5 matrix by vec5 (this a lot of zeroes and constants, which the compiler should eliminate)
282 const float5 invATimesKTimesBand2 = multiply(invATimesK, band2);
283
284 // this is: mat5{project(N0), project(N1), project(N2), project(N3), project(N4)} / k
285 // (the 1/k comes from project(), see above)
286 const float5 ROverK[5] = {
287 project(M[0]), // M * N0
288 project(M[2]), // M * N1
289 project(n * (M[0] + M[1])), // M * N2
290 project(n * (M[0] + M[2])), // M * N3
291 project(n * (M[1] + M[2])) // M * N4
292 };
293
294 // notice how "k" disappears
295 // this is: (R / k) * (invA * k) * band2 == R * invA * band2
296 const float5 result = multiply(ROverK, invATimesKTimesBand2);
297
298 return result;
299 }
300
301 /*
302 * SH from environment with high dynamic range (or high frequencies -- high dynamic range creates
303 * high frequencies) exhibit "ringing" and negative values when reconstructed.
304 * To mitigate this, we need to low-pass the input image -- or equivalently window the SH by
305 * coefficient that tapper towards zero with the band.
306 *
307 * We use ideas and techniques from
308 * Stupid Spherical Harmonics (SH)
309 * Deringing Spherical Harmonics
310 * by Peter-Pike Sloan
311 * https://www.ppsloan.org/publications/shdering.pdf
312 *
313 */
314 float CubemapSH::sincWindow(size_t l, float w) {
315 if (l == 0) {
316 return 1.0f;
317 } else if (l >= w) {
318 return 0.0f;
319 }
320
321 // we use a sinc window scaled to the desired window size in bands units
322 // a sinc window only has zonal harmonics
323 float x = (float(F_PI) * l) / w;
324 x = std::sin(x) / x;
325
326 // The convolution of a SH function f and a ZH function h is just the product of both
327 // scaled by 1 / K(0,l) -- the window coefficients include this scale factor.
328
329 // Taking the window to power N is equivalent to applying the filter N times
330 return std::pow(x, 4);
331 }
332
333 void CubemapSH::windowSH(std::unique_ptr<float3[]>& sh, size_t numBands, float cutoff) {
334
335 using SH3 = std::array<float, 9>;
336
337 auto rotateSh3Bands = [](SH3 const& sh, mat3f M) -> SH3 {
338 SH3 out;
339 const float b0 = sh[0];
340 const float3 band1{ sh[1], sh[2], sh[3] };
341 const float3 b1 = rotateShericalHarmonicBand1(band1, M);
342 const float5 band2{ sh[4], sh[5], sh[6], sh[7], sh[8] };
343 const float5 b2 = rotateShericalHarmonicBand2(band2, M);
344 return { b0, b1[0], b1[1], b1[2], b2[0], b2[1], b2[2], b2[3], b2[4] };
345 };
346
347 auto shmin = [rotateSh3Bands](SH3 f) -> float {
348 // See "Deringing Spherical Harmonics" by Peter-Pike Sloan
349 // https://www.ppsloan.org/publications/shdering.pdf
350
351 constexpr float M_SQRT_PI = 1.7724538509f;
352 constexpr float M_SQRT_3 = 1.7320508076f;
353 constexpr float M_SQRT_5 = 2.2360679775f;
354 constexpr float M_SQRT_15 = 3.8729833462f;
355 constexpr float A[9] = {
356 1.0f / (2.0f * M_SQRT_PI), // 0: 0 0
357 -M_SQRT_3 / (2.0f * M_SQRT_PI), // 1: 1 -1
358 M_SQRT_3 / (2.0f * M_SQRT_PI), // 2: 1 0
359 -M_SQRT_3 / (2.0f * M_SQRT_PI), // 3: 1 1
360 M_SQRT_15 / (2.0f * M_SQRT_PI), // 4: 2 -2
361 -M_SQRT_15 / (2.0f * M_SQRT_PI), // 5: 2 -1
362 M_SQRT_5 / (4.0f * M_SQRT_PI), // 6: 2 0
363 -M_SQRT_15 / (2.0f * M_SQRT_PI), // 7: 2 1
364 M_SQRT_15 / (4.0f * M_SQRT_PI) // 8: 2 2
365 };
366
367 // first this to do is to rotate the SH to align Z with the optimal linear direction
368 const float3 dir = normalize(float3{ -f[3], -f[1], f[2] });
369 const float3 z_axis = -dir;
370 const float3 x_axis = normalize(cross(z_axis, float3{ 0, 1, 0 }));
371 const float3 y_axis = cross(x_axis, z_axis);
372 const mat3f M = transpose(mat3f{ x_axis, y_axis, -z_axis });
373
374 f = rotateSh3Bands(f, M);
375 // here we're guaranteed to have normalize(float3{ -f[3], -f[1], f[2] }) == { 0, 0, 1 }
376
377
378 // Find the min for |m| = 2
379 // ------------------------
380 //
381 // Peter-Pike Sloan shows that the minimum can be expressed as a function
382 // of z such as: m2min = -m2max * (1 - z^2) = m2max * z^2 - m2max
383 // with m2max = A[8] * std::sqrt(f[8] * f[8] + f[4] * f[4]);
384 // We can therefore include this in the ZH min computation (which is function of z^2 as well)
385 float m2max = A[8] * std::sqrt(f[8] * f[8] + f[4] * f[4]);
386
387 // Find the min of the zonal harmonics
388 // -----------------------------------
389 //
390 // This comes from minimizing the function:
391 // ZH(z) = (A[0] * f[0])
392 // + (A[2] * f[2]) * z
393 // + (A[6] * f[6]) * (3 * s.z * s.z - 1)
394 //
395 // We do that by finding where it's derivative d/dz is zero:
396 // dZH(z)/dz = a * z^2 + b * z + c
397 // which is zero for z = -b / 2 * a
398 //
399 // We also needs to check that -1 < z < 1, otherwise the min is either in z = -1 or 1
400 //
401 const float a = 3 * A[6] * f[6] + m2max;
402 const float b = A[2] * f[2];
403 const float c = A[0] * f[0] - A[6] * f[6] - m2max;
404
405 const float zmin = -b / (2.0f * a);
406 const float m0min_z = a * zmin * zmin + b * zmin + c;
407 const float m0min_b = std::min(a + b + c, a - b + c);
408
409 const float m0min = (a > 0 && zmin >= -1 && zmin <= 1) ? m0min_z : m0min_b;
410
411 // Find the min for l = 2, |m| = 1
412 // -------------------------------
413 //
414 // Note l = 1, |m| = 1 is guaranteed to be 0 because of the rotation step
415 //
416 // The function considered is:
417 // Y(x, y, z) = A[5] * f[5] * s.y * s.z
418 // + A[7] * f[7] * s.z * s.x
419 float d = A[4] * std::sqrt(f[5] * f[5] + f[7] * f[7]);
420
421 // the |m|=1 function is minimal in -0.5 -- use that to skip the Newton's loop when possible
422 float minimum = m0min - 0.5f * d;
423 if (minimum < 0) {
424 // We could be negative, to find the minimum we will use Newton's method
425 // See https://en.wikipedia.org/wiki/Newton%27s_method_in_optimization
426
427 // this is the function we're trying to minimize
428 auto func = [=](float x) {
429 // first term accounts for ZH + |m| = 2, second terms for |m| = 1
430 return (a * x * x + b * x + c) + (d * x * std::sqrt(1 - x * x));
431 };
432
433 // This is func' / func'' -- this was computed with Mathematica
434 auto increment = [=](float x) {
435 return (x * x - 1) * (d - 2 * d * x * x + (b + 2 * a * x) * std::sqrt(1 - x * x))
436 / (3 * d * x - 2 * d * x * x * x - 2 * a * std::pow(1 - x * x, 1.5f));
437
438 };
439
440 float dz;
441 float z = -F_SQRT1_2; // we start guessing at the min of |m|=1 function
442 do {
443 minimum = func(z); // evaluate our function
444 dz = increment(z); // refine our guess by this amount
445 z = z - dz;
446 // exit if z goes out of range, or if we have reached enough precision
447 } while (std::abs(z) <= 1 && std::abs(dz) > 1e-5f);
448
449 if (std::abs(z) > 1) {
450 // z was out of range
451 minimum = std::min(func(1), func(-1));
452 }
453 }
454 return minimum;
455 };
456
457 auto windowing = [numBands](SH3 f, float cutoff) -> SH3 {
458 for (ssize_t l = 0; l < numBands; l++) {
459 float w = sincWindow(l, cutoff);
460 f[SHindex(0, l)] *= w;
461 for (size_t m = 1; m <= l; m++) {
462 f[SHindex(-m, l)] *= w;
463 f[SHindex(m, l)] *= w;
464 }
465 }
466 return f;
467 };
468
469 if (cutoff == 0) { // auto windowing (default)
470 if (numBands > 3) {
471 // auto-windowing works only for 1, 2 or 3 bands
472 slog.e << "--sh-window=auto can't work with more than 3 bands. Disabling." << io::endl;
473 return;
474 }
475
476 cutoff = numBands * 4 + 1; // start at a large band
477 // We need to process each channel separately
478 SH3 SH = {};
479 for (size_t channel = 0; channel < 3; channel++) {
480 for (size_t i = 0; i < numBands * numBands; i++) {
481 SH[i] = sh[i][channel];
482 }
483
484 // find a cut-off band that works
485 float l = numBands;
486 float r = cutoff;
487 for (size_t i = 0; i < 16 && l + 0.1f < r; i++) {
488 float m = 0.5f * (l + r);
489 if (shmin(windowing(SH, m)) < 0) {
490 r = m;
491 } else {
492 l = m;
493 }
494 }
495 cutoff = std::min(cutoff, l);
496 }
497 }
498
499 //slog.d << cutoff << io::endl;
500 for (ssize_t l = 0; l < numBands; l++) {
501 float w = sincWindow(l, cutoff);
502 sh[SHindex(0, l)] *= w;
503 for (size_t m = 1; m <= l; m++) {
504 sh[SHindex(-m, l)] *= w;
505 sh[SHindex(m, l)] *= w;
506 }
507 }
508 }
509
510 std::unique_ptr<float3[]> CubemapSH::computeSH(JobSystem& js, const Cubemap& cm, size_t numBands, bool irradiance) {
511
512 const size_t numCoefs = numBands * numBands;
513 std::unique_ptr<float3[]> SH(new float3[numCoefs]{});
514
515 struct State {
516 State() = default;
517 explicit State(size_t numCoefs) : numCoefs(numCoefs) { }
518
519 State& operator=(State const & rhs) {
520 SH.reset(new float3[rhs.numCoefs]{}); // NOLINT(modernize-make-unique)
521 SHb.reset(new float[rhs.numCoefs]{}); // NOLINT(modernize-make-unique)
522 return *this;
523 }
524 size_t numCoefs = 0;
525 std::unique_ptr<float3[]> SH;
526 std::unique_ptr<float[]> SHb;
527 } prototype(numCoefs);
528
529 CubemapUtils::process<State>(const_cast<Cubemap&>(cm), js,
530 [&](State& state, size_t y, Cubemap::Face f, Cubemap::Texel const* data, size_t dim) {
531 for (size_t x=0 ; x<dim ; ++x, ++data) {
532
533 float3 s(cm.getDirectionFor(f, x, y));
534
535 // sample a color
536 float3 color(Cubemap::sampleAt(data));
537
538 // take solid angle into account
539 color *= CubemapUtils::solidAngle(dim, x, y);
540
541 computeShBasis(state.SHb.get(), numBands, s);
542
543 // apply coefficients to the sampled color
544 for (size_t i=0 ; i<numCoefs ; i++) {
545 state.SH[i] += color * state.SHb[i];
546 }
547 }
548 },
549 [&](State& state) {
550 for (size_t i=0 ; i<numCoefs ; i++) {
551 SH[i] += state.SH[i];
552 }
553 }, prototype);
554
555 // precompute the scaling factor K
556 std::vector<float> K = Ki(numBands);
557
558 // apply truncated cos (irradiance)
559 if (irradiance) {
560 for (size_t l = 0; l < numBands; l++) {
561 const float truncatedCosSh = computeTruncatedCosSh(size_t(l));
562 K[SHindex(0, l)] *= truncatedCosSh;
563 for (size_t m = 1; m <= l; m++) {
564 K[SHindex(-m, l)] *= truncatedCosSh;
565 K[SHindex( m, l)] *= truncatedCosSh;
566 }
567 }
568 }
569
570 // apply all the scale factors
571 for (size_t i = 0; i < numCoefs; i++) {
572 SH[i] *= K[i];
573 }
574 return SH;
575 }
576
577 void CubemapSH::renderSH(JobSystem& js, Cubemap& cm,
578 const std::unique_ptr<float3[]>& sh, size_t numBands) {
579 const size_t numCoefs = numBands * numBands;
580
581 // precompute the scaling factor K
582 const std::vector<float> K = Ki(numBands);
583
584 struct State {
585 // we compute the min just for debugging -- it's not actually needed.
586 float3 min = std::numeric_limits<float>::max();
587 } prototype;
588
589 CubemapUtils::process<State>(cm, js,
590 [&](State& state, size_t y,
591 Cubemap::Face f, Cubemap::Texel* data, size_t dim) {
592 std::vector<float> SHb(numCoefs);
593 for (size_t x = 0; x < dim; ++x, ++data) {
594 float3 s(cm.getDirectionFor(f, x, y));
595 computeShBasis(SHb.data(), numBands, s);
596 float3 c = 0;
597 for (size_t i = 0; i < numCoefs; i++) {
598 c += sh[i] * (K[i] * SHb[i]);
599 }
600 c *= F_1_PI;
601 state.min = min(c, state.min);
602 Cubemap::writeAt(data, Cubemap::Texel(c));
603 }
604 },
605 [&](State& state) {
606 prototype.min = min(prototype.min, state.min);
607 }, prototype);
608 //slog.d << prototype.min << io::endl;
609 }
610
611 /*
612 * This computes the 3-bands SH coefficients of the Cubemap convoluted by the
613 * truncated cos(theta) (i.e.: saturate(s.z)), pre-scaled by the reconstruction
614 * factors.
615 */
616 void CubemapSH::preprocessSHForShader(std::unique_ptr<filament::math::float3[]>& SH) {
617 constexpr size_t numBands = 3;
618 constexpr size_t numCoefs = numBands * numBands;
619
620 // Coefficient for the polynomial form of the SH functions -- these were taken from
621 // "Stupid Spherical Harmonics (SH)" by Peter-Pike Sloan
622 // They simply come for expanding the computation of each SH function.
623 //
624 // To render spherical harmonics we can use the polynomial form, like this:
625 // c += sh[0] * A[0];
626 // c += sh[1] * A[1] * s.y;
627 // c += sh[2] * A[2] * s.z;
628 // c += sh[3] * A[3] * s.x;
629 // c += sh[4] * A[4] * s.y * s.x;
630 // c += sh[5] * A[5] * s.y * s.z;
631 // c += sh[6] * A[6] * (3 * s.z * s.z - 1);
632 // c += sh[7] * A[7] * s.z * s.x;
633 // c += sh[8] * A[8] * (s.x * s.x - s.y * s.y);
634 //
635 // To save math in the shader, we pre-multiply our SH coefficient by the A[i] factors.
636 // Additionally, we include the lambertian diffuse BRDF 1/pi.
637
638 constexpr float M_SQRT_PI = 1.7724538509f;
639 constexpr float M_SQRT_3 = 1.7320508076f;
640 constexpr float M_SQRT_5 = 2.2360679775f;
641 constexpr float M_SQRT_15 = 3.8729833462f;
642 constexpr float A[numCoefs] = {
643 1.0f / (2.0f * M_SQRT_PI), // 0 0
644 -M_SQRT_3 / (2.0f * M_SQRT_PI), // 1 -1
645 M_SQRT_3 / (2.0f * M_SQRT_PI), // 1 0
646 -M_SQRT_3 / (2.0f * M_SQRT_PI), // 1 1
647 M_SQRT_15 / (2.0f * M_SQRT_PI), // 2 -2
648 -M_SQRT_15 / (2.0f * M_SQRT_PI), // 3 -1
649 M_SQRT_5 / (4.0f * M_SQRT_PI), // 3 0
650 -M_SQRT_15 / (2.0f * M_SQRT_PI), // 3 1
651 M_SQRT_15 / (4.0f * M_SQRT_PI) // 3 2
652 };
653
654 for (size_t i = 0; i < numCoefs; i++) {
655 SH[i] *= A[i] * F_1_PI;
656 }
657 }
658
659 void CubemapSH::renderPreScaledSH3Bands(JobSystem& js,
660 Cubemap& cm, const std::unique_ptr<filament::math::float3[]>& sh) {
661 CubemapUtils::process<CubemapUtils::EmptyState>(cm, js,
662 [&](CubemapUtils::EmptyState&, size_t y, Cubemap::Face f, Cubemap::Texel* data,
663 size_t dim) {
664 for (size_t x = 0; x < dim; ++x, ++data) {
665 float3 s(cm.getDirectionFor(f, x, y));
666 float3 c = 0;
667 c += sh[0];
668
669 c += sh[1] * s.y;
670 c += sh[2] * s.z;
671 c += sh[3] * s.x;
672
673 c += sh[4] * s.y * s.x;
674 c += sh[5] * s.y * s.z;
675 c += sh[6] * (3 * s.z * s.z - 1);
676 c += sh[7] * s.z * s.x;
677 c += sh[8] * (s.x * s.x - s.y * s.y);
678 Cubemap::writeAt(data, Cubemap::Texel(c));
679 }
680 });
681 }
682
683 // -----------------------------------------------------------------------------------------------
684 // Only used for debugging
685 // -----------------------------------------------------------------------------------------------
686
687 float UTILS_UNUSED CubemapSH::Legendre(ssize_t l, ssize_t m, float x) {
688 // evaluate an Associated Legendre Polynomial P(l,m,x) at x
689 float pmm = 1.0;
690 if (m > 0) {
691 float somx2 = sqrt((1.0f - x) * (1.0f + x));
692 float fact = 1.0f;
693 for (int i = 1; i <= m; i++) {
694 pmm *= (-fact) * somx2;
695 fact += 2.0f;
696 }
697 }
698 if (l == m)
699 return pmm;
700 float pmmp1 = x * (2.0f * m + 1.0f) * pmm;
701 if (l == m + 1)
702 return pmmp1;
703 float pll = 0.0;
704 for (ssize_t ll = m + 2; ll <= l; ++ll) {
705 pll = ((2.0f * ll - 1.0f) * x * pmmp1 - (ll + m - 1.0f) * pmm) / (ll - m);
706 pmm = pmmp1;
707 pmmp1 = pll;
708 }
709 return pll;
710 }
711
712 // Only used for debugging
713 float UTILS_UNUSED CubemapSH::TSH(int l, int m, const float3& d) {
714 if (l==0 && m==0) {
715 return 1 / (2*sqrt(F_PI));
716 } else if (l==1 && m==-1) {
717 return -(sqrt(3)*d.y)/(2*sqrt(F_PI));
718 } else if (l==1 && m==0) {
719 return (sqrt(3)*d.z)/(2*sqrt(F_PI));
720 } else if (l==1 && m==1) {
721 return -(sqrt(3)*d.x)/(2*sqrt(F_PI));
722 } else if (l==2 && m==-2) {
723 return (sqrt(15)*d.y*d.x)/(2*sqrt(F_PI));
724 } else if (l==2 && m==-1) {
725 return -(sqrt(15)*d.y*d.z)/(2*sqrt(F_PI));
726 } else if (l==2 && m==0) {
727 return (sqrt(5)*(3*d.z*d.z-1))/(4*sqrt(F_PI));
728 } else if (l==2 && m==1) {
729 return -(sqrt(15)*d.z*d.x)/(2*sqrt(F_PI));
730 } else if (l==2 && m==2) {
731 return (sqrt(15)*(d.x*d.x - d.y*d.y))/(4*sqrt(F_PI));
732 }
733 return 0;
734 }
735
736 void UTILS_UNUSED CubemapSH::printShBase(std::ostream& out, int l, int m) {
737 if (l<3 && std::abs(m) <= l) {
738 const char* d = nullptr;
739 float c = 0;
740 if (l==0 && m==0) {
741 c = F_2_SQRTPI * 0.25;
742 d = " ";
743 } else if (l==1 && m==-1) {
744 c = -F_2_SQRTPI * sqrt(3) * 0.25;
745 d = " * y; ";
746 } else if (l==1 && m==0) {
747 c = F_2_SQRTPI * sqrt(3) * 0.25;
748 d = " * z; ";
749 } else if (l==1 && m==1) {
750 c = -F_2_SQRTPI * sqrt(3) * 0.25;
751 d = " * x; ";
752 } else if (l==2 && m==-2) {
753 c = F_2_SQRTPI * sqrt(15) * 0.25;
754 d = " * y*x; ";
755 } else if (l==2 && m==-1) {
756 c = -F_2_SQRTPI * sqrt(15) * 0.25;
757 d = " * y*z; ";
758 } else if (l==2 && m==0) {
759 c = F_2_SQRTPI * sqrt(5) * 0.125;
760 d = " * (3*z*z -1); ";
761 } else if (l==2 && m==1) {
762 c = -F_2_SQRTPI * sqrt(15) * 0.25;
763 d = " * z*x; ";
764 } else if (l==2 && m==2) {
765 c = F_2_SQRTPI * sqrt(15) * 0.125;
766 d = " * (x*x - y*y);";
767 }
768 out << "SHb[" << SHindex(m, size_t(l)) << "] = ";
769 out << std::fixed << std::setprecision(15) << std::setw(18) << c << d;
770 out << " // L" << l << m;
771 }
772 }
773
774 } // namespace ibl
775 } // namespace filament