float D_GGX(float NoH, float roughness) {
- float a = NoH * roughness;
- float k = roughness / (1.0 - NoH * NoH + a * a);
+float D_GGX(float NoH, float roughness) {
+ float a = NoH * roughness;
+ float k = roughness / (1.0 - NoH * NoH + a * a);
return k * k * (1.0 / PI);
}
@@ -590,10 +590,10 @@ V(v,l,\alpha) = \frac{0.5}{\NoL \sqrt{(\NoV)^2 (1 - \aa) + \aa} + \NoV \sqrt{(\N
\end{equation}$$
The GLSL implementation of the visibility term, shown in listing 3, is a bit more expensive than we would like since it requires two sqrt operations.
-
float V_SmithGGXCorrelated(float NoV, float NoL, float roughness) {
- float a2 = roughness * roughness;
- float GGXV = NoL * sqrt(NoV * NoV * (1.0 - a2) + a2);
- float GGXL = NoV * sqrt(NoL * NoL * (1.0 - a2) + a2);
+float V_SmithGGXCorrelated(float NoV, float NoL, float roughness) {
+ float a2 = roughness * roughness;
+ float GGXV = NoL * sqrt(NoV * NoV * (1.0 - a2) + a2);
+ float GGXL = NoV * sqrt(NoL * NoL * (1.0 - a2) + a2);
return 0.5 / (GGXV + GGXL);
}
@@ -604,10 +604,10 @@ V(v,l,\alpha) = \frac{0.5}{\NoL (\NoV (1 - \alpha) + \alpha) + \NoV (\NoL (1 - \
\end{equation}$$
This approximation is mathematically wrong but saves two square root operations and is good enough for real-time mobile applications, as shown in listing 4.
-
float V_SmithGGXCorrelatedFast(float NoV, float NoL, float roughness) {
- float a = roughness;
- float GGXV = NoL * (NoV * (1.0 - a) + a);
- float GGXL = NoV * (NoL * (1.0 - a) + a);
+float V_SmithGGXCorrelatedFast(float NoV, float NoL, float roughness) {
+ float a = roughness;
+ float GGXV = NoL * (NoV * (1.0 - a) + a);
+ float GGXL = NoV * (NoL * (1.0 - a) + a);
return 0.5 / (GGXV + GGXL);
}
@@ -659,7 +659,7 @@ $$\begin{equation}
\end{equation}$$
In practice, the diffuse reflectance \(\sigma\) is multiplied later, as shown in listing 8.
-
float Fd_Lambert() {
+float Fd_Lambert() {
return 1.0 / PI;
}
@@ -680,14 +680,14 @@ Where:
$$\begin{equation}
\fGrazing=0.5 + 2 \cdot \alpha cos^2(\theta_d)
\end{equation}$$
-float F_Schlick(float u, float f0, float f90) {
- return f0 + (f90 - f0) * pow(1.0 - u, 5.0);
+float F_Schlick(float u, float f0, float f90) {
+ return f0 + (f90 - f0) * pow(1.0 - u, 5.0);
}
-float Fd_Burley(float NoV, float NoL, float LoH, float roughness) {
- float f90 = 0.5 + 2.0 * roughness * LoH * LoH;
- float lightScatter = F_Schlick(NoL, 1.0, f90);
- float viewScatter = F_Schlick(NoV, 1.0, f90);
+float Fd_Burley(float NoV, float NoL, float LoH, float roughness) {
+ float f90 = 0.5 + 2.0 * roughness * LoH * LoH;
+ float lightScatter = F_Schlick(NoL, 1.0, f90);
+ float viewScatter = F_Schlick(NoV, 1.0, f90);
return lightScatter * viewScatter * (1.0 / PI);
}
@@ -704,47 +704,47 @@ We could allow artists/developers to choose the Disney diffuse BRDF depending on
Diffuse term: a Lambertian diffuse model.
The full GLSL implementation of the standard model is shown in listing 9.
-
float D_GGX(float NoH, float a) {
- float a2 = a * a;
- float f = (NoH * a2 - NoH) * NoH + 1.0;
+float D_GGX(float NoH, float a) {
+ float a2 = a * a;
+ float f = (NoH * a2 - NoH) * NoH + 1.0;
return a2 / (PI * f * f);
}
-vec3 F_Schlick(float u, vec3 f0) {
- return f0 + (vec3(1.0) - f0) * pow(1.0 - u, 5.0);
+vec3 F_Schlick(float u, vec3 f0) {
+ return f0 + (vec3(1.0) - f0) * pow(1.0 - u, 5.0);
}
-float V_SmithGGXCorrelated(float NoV, float NoL, float a) {
- float a2 = a * a;
- float GGXL = NoV * sqrt((-NoL * a2 + NoL) * NoL + a2);
- float GGXV = NoL * sqrt((-NoV * a2 + NoV) * NoV + a2);
+float V_SmithGGXCorrelated(float NoV, float NoL, float a) {
+ float a2 = a * a;
+ float GGXL = NoV * sqrt((-NoL * a2 + NoL) * NoL + a2);
+ float GGXV = NoL * sqrt((-NoV * a2 + NoV) * NoV + a2);
return 0.5 / (GGXV + GGXL);
}
-float Fd_Lambert() {
+float Fd_Lambert() {
return 1.0 / PI;
}
-void BRDF(...) {
- vec3 h = normalize(v + l);
+void BRDF(...) {
+ vec3 h = normalize(v + l);
- float NoV = abs(dot(n, v)) + 1e-5;
- float NoL = clamp(dot(n, l), 0.0, 1.0);
- float NoH = clamp(dot(n, h), 0.0, 1.0);
- float LoH = clamp(dot(l, h), 0.0, 1.0);
+ float NoV = abs(dot(n, v)) + 1e-5;
+ float NoL = clamp(dot(n, l), 0.0, 1.0);
+ float NoH = clamp(dot(n, h), 0.0, 1.0);
+ float LoH = clamp(dot(l, h), 0.0, 1.0);
// perceptually linear roughness to roughness (see parameterization)
- float roughness = perceptualRoughness * perceptualRoughness;
+ float roughness = perceptualRoughness * perceptualRoughness;
- float D = D_GGX(NoH, roughness);
- vec3 F = F_Schlick(LoH, f0);
- float V = V_SmithGGXCorrelated(NoV, NoL, roughness);
+ float D = D_GGX(NoH, roughness);
+ vec3 F = F_Schlick(LoH, f0);
+ float V = V_SmithGGXCorrelated(NoV, NoL, roughness);
// specular BRDF
- vec3 Fr = (D * V) * F;
+ vec3 Fr = (D * V) * F;
// diffuse BRDF
- vec3 Fd = diffuseColor * Fd_Lambert();
+ vec3 Fd = diffuseColor * Fd_Lambert();
// apply lighting...
}
Listing 12 shows how \(\fNormal\) is computed for both dielectric and metallic materials. It shows that the color of the specular reflectance is derived from the base color in the metallic case.
-
vec3 f0 = 0.16 * reflectance * reflectance * (1.0 - metallic) + baseColor * metallic;
vec3 f0 = 0.16 * reflectance * reflectance * (1.0 - metallic) + baseColor * metallic;
Roughness remapping and clamping
The roughness set by the user, called perceptualRoughness here, is remapped to a perceptually linear range using the following formulation:
@@ -1054,7 +1054,7 @@ V(l,h) = \frac{1}{4(\LoH)^2}
This masking-shadowing function is not physically based, as shown in [Heitz14], but its simplicity makes it desirable for real-time rendering.
In summary, our clear coat BRDF is a Cook-Torrance specular microfacet model, with a GGX normal distribution function, a Kelemen visibility function, and a Schlick Fresnel function. Listing 13 shows how trivial the GLSL implementation is.
-
float V_Kelemen(float LoH) {
+float V_Kelemen(float LoH) {
return 0.25 / (LoH * LoH);
}
@@ -1097,18 +1097,18 @@ The clear coat roughness parameter is remapped and clamped in a similar way to t
Listing 14 shows the GLSL implementation of the clear coat material model after remapping, parameterization and integration in the standard surface response.
-
void BRDF(...) {
+void BRDF(...) {
// compute Fd and Fr from standard model
// remapping and linearization of clear coat roughness
- clearCoatPerceptualRoughness = clamp(clearCoatPerceptualRoughness, 0.089, 1.0);
+ clearCoatPerceptualRoughness = clamp(clearCoatPerceptualRoughness, 0.089, 1.0);
clearCoatRoughness = clearCoatPerceptualRoughness * clearCoatPerceptualRoughness;
// clear coat BRDF
- float Dc = D_GGX(clearCoatRoughness, NoH);
- float Vc = V_Kelemen(clearCoatRoughness, LoH);
- float Fc = F_Schlick(0.04, LoH) * clearCoat; // clear coat strength
- float Frc = (Dc * Vc) * Fc;
+ float Dc = D_GGX(clearCoatRoughness, NoH);
+ float Vc = V_Kelemen(clearCoatRoughness, LoH);
+ float Fc = F_Schlick(0.04, LoH) * clearCoat; // clear coat strength
+ float Frc = (Dc * Vc) * Fc;
// account for energy loss in the base layer
return color * ((Fd + Fr * (1.0 - Fc)) * (1.0 - Fc) + Frc);
@@ -1294,14 +1294,14 @@ f_{r}(v,h,\alpha) = \frac{D_{velvet}(v,h,\alpha)}{4(\NoL + \NoV - (\NoL)(\NoV))}
\end{equation}$$
The implementation of the velvet NDF is presented in listing 17, optimized to properly fit in half float formats and to avoid computing a costly cotangent, relying instead on trigonometric identities. Note that we removed the Fresnel component from this BRDF.
-
float D_Ashikhmin(float roughness, float NoH) {
+float D_Ashikhmin(float roughness, float NoH) {
// Ashikhmin 2007, "Distribution-based BRDFs"
- float a2 = roughness * roughness;
- float cos2h = NoH * NoH;
- float sin2h = max(1.0 - cos2h, 0.0078125); // 2^(-14/2), so sin2h^2 > 0 in fp16
- float sin4h = sin2h * sin2h;
- float cot2 = -cos2h / (a2 * sin2h);
- return 1.0 / (PI * (4.0 * a2 + 1.0) * sin4h) * (4.0 * exp(cot2) + sin4h);
+ float a2 = roughness * roughness;
+ float cos2h = NoH * NoH;
+ float sin2h = max(1.0 - cos2h, 0.0078125); // 2^(-14/2), so sin2h^2 > 0 in fp16
+ float sin4h = sin2h * sin2h;
+ float cot2 = -cos2h / (a2 * sin2h);
+ return 1.0 / (PI * (4.0 * a2 + 1.0) * sin4h) * (4.0 * exp(cot2) + sin4h);
}
In [Estevez17] Estevez and Kulla propose a different NDF (called the “Charlie” sheen) that is based on an exponentiated sinusoidal instead of an inverted Gaussian. This NDF is appealing for several reasons: its parameterization feels more natural and intuitive, it provides a softer appearance and, as shown in equation (\ref{charlieNDF}), its implementation is simpler:
@@ -1312,11 +1312,11 @@ D(m) = \frac{(2 + \frac{1}{\alpha}) sin(\theta)^{\frac{1}{\alpha}}}{2 \pi}
[Estevez17] also presents a new shadowing term that we omit here because of its cost. We instead rely on the visibility term from [Neubelt13] (shown in equation \(\ref{clothSpecularBRDF}\) above).
The implementation of this NDF is presented in listing 18, optimized to properly fit in half float formats.
-
float D_Charlie(float roughness, float NoH) {
+float D_Charlie(float roughness, float NoH) {
// Estevez and Kulla 2017, "Production Friendly Microfacet Sheen BRDF"
- float invAlpha = 1.0 / roughness;
- float cos2h = NoH * NoH;
- float sin2h = max(1.0 - cos2h, 0.0078125); // 2^(-14/2), so sin2h^2 > 0 in fp16
+ float invAlpha = 1.0 / roughness;
+ float cos2h = NoH * NoH;
+ float sin2h = max(1.0 - cos2h, 0.0078125); // 2^(-14/2), so sin2h^2 > 0 in fp16
return (2.0 + invAlpha) * pow(sin2h, invAlpha * 0.5) / (2.0 * PI);
}
Sheen color
@@ -1745,21 +1745,21 @@ The photometric attenuation function can be easily implemented in GLSL by adding
}
The light intensity is computed CPU-side (listing 23) and depends on whether the photometric profile is used as a mask.
-float multiplier;
+float multiplier;
// Photometric profile used as a mask
-if (photometricLight.isMasked()) {
+if (photometricLight.isMasked()) {
// The desired intensity is set by the artist
// The integrated intensity comes from a Monte-Carlo
// integration over the unit sphere around the luminaire
- multiplier = photometricLight.getDesiredIntensity() /
- photometricLight.getIntegratedIntensity();
+ multiplier = photometricLight.getDesiredIntensity() /
+ photometricLight.getIntegratedIntensity();
} else {
// Multiplier provided for convenience, set to 1.0 by default
- multiplier = photometricLight.getMultiplier();
+ multiplier = photometricLight.getMultiplier();
}
// The max intensity in cd comes from the IES profile
-float lightIntensity = photometricLight.getMaxIntensity() * multiplier;
4 The XArrow profile declares a luminous intensity of 1,750 lm but a Monte-Carlo integration shows an intensity of only 350 lm.
@@ -2058,19 +2058,19 @@ In practice only 4 or 9 coefficients (i.e.: 2 or 3 bands) are enough for \(\cosT
In practice we pre-convolve \(\Lt\) with \(\cosTheta\) and pre-scale these coefficients by the basis scaling factors \(K_l^m\) so that the reconstruction code is as simple as possible in the shader:
-
vec3 irradianceSH(vec3 n) {
- // uniform vec3 sphericalHarmonics[9]
- // We can use only the first 2 bands for better performance
- return
- sphericalHarmonics[0]
- + sphericalHarmonics[1] * (n.y)
- + sphericalHarmonics[2] * (n.z)
- + sphericalHarmonics[3] * (n.x)
- + sphericalHarmonics[4] * (n.y * n.x)
- + sphericalHarmonics[5] * (n.y * n.z)
- + sphericalHarmonics[6] * (3.0 * n.z * n.z - 1.0)
- + sphericalHarmonics[7] * (n.z * n.x)
- + sphericalHarmonics[8] * (n.x * n.x - n.y * n.y);
+vec3 irradianceSH(vec3 n) {
+ // uniform vec3 sphericalHarmonics[9]
+ // We can use only the first 2 bands for better performance
+ return
+ sphericalHarmonics[0]
+ + sphericalHarmonics[1] * (n.y)
+ + sphericalHarmonics[2] * (n.z)
+ + sphericalHarmonics[3] * (n.x)
+ + sphericalHarmonics[4] * (n.y * n.x)
+ + sphericalHarmonics[5] * (n.y * n.z)
+ + sphericalHarmonics[6] * (3.0 * n.z * n.z - 1.0)
+ + sphericalHarmonics[7] * (n.z * n.x)
+ + sphericalHarmonics[8] * (n.x * n.x - n.y * n.y);
}
Note that with 2 bands, the computation above becomes a single (4 \times 4) matrix-by-vector multiply.
@@ -2443,7 +2443,7 @@ LD(n, \alpha) &= \frac{\sum_i^N V(l_i, n,
$$
These two new \(DFG\) terms simply need to replace the ones used in the implementation shown in section 9.5:
-
float Fc = pow(1 - VoH, 5.0f);
+float Fc = pow(1 - VoH, 5.0f);
r.x += Gv * Fc;
r.y += Gv;
@@ -2507,11 +2507,11 @@ using an environment made of colored vertical stripes (skybox hidden).
When sampling the IBL, the clear coat layer is calculated as a second specular lobe. This specular lobe is oriented along the view direction since we cannot reasonably integrate over the hemisphere. Listing 31 demonstrates this approximation in practice. It also shows the energy conservation step. It is important to note that this second specular lobe is computed exactly the same way as the main specular lobe, using the same DFG approximation.
// clearCoat_NoV == shading_NoV if the clear coat layer doesn't have its own normal map
-float Fc = F_Schlick(0.04, 1.0, clearCoat_NoV) * clearCoat;
+float Fc = F_Schlick(0.04, 1.0, clearCoat_NoV) * clearCoat;
// base layer attenuation for energy compensation
iblDiffuse *= 1.0 - Fc;
-iblSpecular *= sq(1.0 - Fc);
-iblSpecular += specularIBL(r, clearCoatPerceptualRoughness) * Fc;
Anisotropy
[McAuley15] describes a technique called “bent reflection vector”, based [Revie12]. The bent reflection vector is a rough approximation of anisotropic lighting but the alternative is to use importance sampling. This approximation is sufficiently cheap to compute and provides good results, as shown in figure 59 and figure 60.
@@ -2550,17 +2550,17 @@ The DG term is generated using uniform sampling as recommended in [
Figure 62: DFG LUT with a 3rd channel encoding the DG term of the cloth BRDF
The remainder of the image-based lighting implementation follows the same steps as the implementation of regular lights, including the optional subsurface scattering term and its wrap diffuse component. Just as with the clear coat IBL implementation, we cannot integrate over the hemisphere and use the view direction as the dominant light direction to compute the wrap diffuse component.
-
float diffuse = Fd_Lambert() * ambientOcclusion;
-#if defined(SHADING_MODEL_CLOTH)
-#if defined(MATERIAL_HAS_SUBSURFACE_COLOR)
-diffuse *= saturate((NoV + 0.5) / 2.25);
-#endif
-#endif
+float diffuse = Fd_Lambert() * ambientOcclusion;
+#if defined(SHADING_MODEL_CLOTH)
+#if defined(MATERIAL_HAS_SUBSURFACE_COLOR)
+diffuse *= saturate((NoV + 0.5) / 2.25);
+#endif
+#endif
-vec3 indirectDiffuse = irradianceIBL(n) * diffuse;
-#if defined(SHADING_MODEL_CLOTH) && defined(MATERIAL_HAS_SUBSURFACE_COLOR)
-indirectDiffuse *= saturate(subsurfaceColor + NoV);
-#endif
+vec3 indirectDiffuse = irradianceIBL(n) * diffuse;
+#if defined(SHADING_MODEL_CLOTH) && defined(MATERIAL_HAS_SUBSURFACE_COLOR)
+indirectDiffuse *= saturate(subsurfaceColor + NoV);
+#endif
vec3 ibl = diffuseColor * indirectDiffuse + indirectSpecular * specularColor;
@@ -2982,20 +2982,20 @@ L_{max} &= 2^{EV_{100}} \times 1.2
// aperture in f-stops
// shutterSpeed in seconds
// sensitivity in ISO
-float exposureSettings(float aperture, float shutterSpeed, float sensitivity) {
+float exposureSettings(float aperture, float shutterSpeed, float sensitivity) {
return log2((aperture * aperture) / shutterSpeed * 100.0 / sensitivity);
}
// Computes the exposure normalization factor from
// the camera's EV100
-float exposure(float ev100) {
- return 1.0 / (pow(2.0, ev100) * 1.2);
+float exposure(float ev100) {
+ return 1.0 / (pow(2.0, ev100) * 1.2);
}
-float ev100 = exposureSettings(aperture, shutterSpeed, sensitivity);
-float exposure = exposure(ev100);
+float ev100 = exposureSettings(aperture, shutterSpeed, sensitivity);
+float exposure = exposure(ev100);
-vec4 color = evaluateLighting();
+vec4 color = evaluateLighting();
color.rgb *= exposure;
In practice the exposure factor can be pre-computed on the CPU to save shader instructions.
@@ -3466,9 +3466,9 @@ Our implementation is presented in listing&
// Data source:
// http://cvrl.ioo.ucl.ac.uk/cmfs.htm
// http://cvrl.ioo.ucl.ac.uk/database/text/cmfs/ciexyz31.htm
-const size_t CIE_XYZ_START = 360;
-const size_t CIE_XYZ_COUNT = 471;
-const float3 CIE_XYZ[CIE_XYZ_COUNT] = { ... };
+const size_t CIE_XYZ_START = 360;
+const size_t CIE_XYZ_COUNT = 471;
+const float3 CIE_XYZ[CIE_XYZ_COUNT] = { ... };
// CIE Standard Illuminant D65 relative spectral power distribution,
// from 300nm to 830, at 5nm intervals
@@ -3476,51 +3476,51 @@ Our implementation is presented in listing&
// Data source:
// https://en.wikipedia.org/wiki/Illuminant_D65
// https://cielab.xyz/pdf/CIE_sel_colorimetric_tables.xls
-const size_t CIE_D65_INTERVAL = 5;
-const size_t CIE_D65_START = 300;
-const size_t CIE_D65_END = 830;
-const size_t CIE_D65_COUNT = 107;
-const float CIE_D65[CIE_D65_COUNT] = { ... };
+const size_t CIE_D65_INTERVAL = 5;
+const size_t CIE_D65_START = 300;
+const size_t CIE_D65_END = 830;
+const size_t CIE_D65_COUNT = 107;
+const float CIE_D65[CIE_D65_COUNT] = { ... };
-struct Sample {
- float w = 0.0f; // wavelength
- std::complex<float> ior; // complex IOR, n + ik
+struct Sample {
+ float w = 0.0f; // wavelength
+ std::complex<float> ior; // complex IOR, n + ik
};
-static float illuminantD65(float w) {
- auto i0 = size_t((w - CIE_D65_START) / CIE_D65_INTERVAL);
- uint2 indexBounds{i0, std::min(i0 + 1, CIE_D65_END)};
+static float illuminantD65(float w) {
+ auto i0 = size_t((w - CIE_D65_START) / CIE_D65_INTERVAL);
+ uint2 indexBounds{i0, std::min(i0 + 1, CIE_D65_END)};
float2 wavelengthBounds = CIE_D65_START + float2{indexBounds} * CIE_D65_INTERVAL;
- float t = (w - wavelengthBounds.x) / (wavelengthBounds.y - wavelengthBounds.x);
- return lerp(CIE_D65[indexBounds.x], CIE_D65[indexBounds.y], t);
+ float t = (w - wavelengthBounds.x) / (wavelengthBounds.y - wavelengthBounds.x);
+ return lerp(CIE_D65[indexBounds.x], CIE_D65[indexBounds.y], t);
}
// For std::lower_bound
-bool operator<(const Sample& lhs, const Sample& rhs) {
+bool operator<(const Sample& lhs, const Sample& rhs) {
return lhs.w < rhs.w;
}
// The wavelength w must be between 360nm and 830nm
-static std::complex<float> findSample(const std::vector<sample>& samples, float w) {
- auto i1 = std::lower_bound(
- samples.begin(), samples.end(), Sample{w, 0.0f + 0.0if});
+static std::complex<float> findSample(const std::vector<sample>& samples, float w) {
+ auto i1 = std::lower_bound(
+ samples.begin(), samples.end(), Sample{w, 0.0f + 0.0if});
auto i0 = i1 - 1;
// Interpolate the complex IORs
- float t = (w - i0->w) / (i1->w - i0->w);
- float n = lerp(i0->ior.real(), i1->ior.real(), t);
- float k = lerp(i0->ior.imag(), i1->ior.imag(), t);
+ float t = (w - i0->w) / (i1->w - i0->w);
+ float n = lerp(i0->ior.real(), i1->ior.real(), t);
+ float k = lerp(i0->ior.imag(), i1->ior.imag(), t);
return { n, k };
}
-static float fresnel(const std::complex<float>& sample) {
- return (((sample - (1.0f + 0if)) * (std::conj(sample) - (1.0f + 0if))) /
- ((sample + (1.0f + 0if)) * (std::conj(sample) + (1.0f + 0if)))).real();
+static float fresnel(const std::complex<float>& sample) {
+ return (((sample - (1.0f + 0if)) * (std::conj(sample) - (1.0f + 0if))) /
+ ((sample + (1.0f + 0if)) * (std::conj(sample) + (1.0f + 0if)))).real();
}
-static float3 XYZ_to_sRGB(const float3& v) {
- const mat3f XYZ_sRGB{
+static float3 XYZ_to_sRGB(const float3& v) {
+ const mat3f XYZ_sRGB{
3.2404542f, -0.9692660f, 0.0556434f,
-1.5371385f, 1.8760108f, -0.2040259f,
-0.4985314f, 0.0415560f, 1.0572252f
@@ -3529,21 +3529,21 @@ Our implementation is presented in listing&
}
// Outputs a linear sRGB color
-static float3 computeColor(const std::vector<sample>& samples) {
+static float3 computeColor(const std::vector<sample>& samples) {
float3 xyz{0.0f};
- float y = 0.0f;
+ float y = 0.0f;
- for (size_t i = 0; i < CIE_XYZ_COUNT; i++) {
+ for (size_t i = 0; i < CIE_XYZ_COUNT; i++) {
// Current wavelength
- float w = CIE_XYZ_START + i;
+ float w = CIE_XYZ_START + i;
// Find most appropriate CIE XYZ sample for the wavelength
- auto sample = findSample(samples, w);
+ auto sample = findSample(samples, w);
// Compute Fresnel reflectance at normal incidence
- float f0 = fresnel(sample);
+ float f0 = fresnel(sample);
// We need to multiply by the spectral power distribution of the illuminant
- float d65 = illuminantD65(w);
+ float d65 = illuminantD65(w);
xyz += f0 * CIE_XYZ[i] * d65;
y += CIE_XYZ[i].y * d65;
@@ -3552,10 +3552,10 @@ Our implementation is presented in listing&
// Normalize so that 100% reflectance at every wavelength yields Y=1
xyz /= y;
- float3 linear = XYZ_to_sRGB(xyz);
+ float3 linear = XYZ_to_sRGB(xyz);
// Normalize out-of-gamut values
- if (any(greaterThan(linear, float3{1.0f}))) linear *= 1.0f / max(linear);
+ if (any(greaterThan(linear, float3{1.0f}))) linear *= 1.0f / max(linear);
return linear;
}
vec2f hammersley(uint i, float numSamples) {
uint bits = i;
bits = (bits << 16) | (bits >> 16);
- bits = ((bits & 0x55555555) << 1) | ((bits & 0xAAAAAAAA) >> 1);
- bits = ((bits & 0x33333333) << 2) | ((bits & 0xCCCCCCCC) >> 2);
- bits = ((bits & 0x0F0F0F0F) << 4) | ((bits & 0xF0F0F0F0) >> 4);
- bits = ((bits & 0x00FF00FF) << 8) | ((bits & 0xFF00FF00) >> 8);
- return vec2f(i / numSamples, bits / exp2(32));
+ bits = ((bits & 0x55555555) << 1) | ((bits & 0xAAAAAAAA) >> 1);
+ bits = ((bits & 0x33333333) << 2) | ((bits & 0xCCCCCCCC) >> 2);
+ bits = ((bits & 0x0F0F0F0F) << 4) | ((bits & 0xF0F0F0F0) >> 4);
+ bits = ((bits & 0x00FF00FF) << 8) | ((bits & 0xFF00FF00) >> 8);
+ return vec2f(i / numSamples, bits / exp2(32));
}
C++ implementation of a Hammersley sequence generator
Precomputing L for image-based lighting
The term ( L_{DFG} ) is only dependent on ( \NoV ). Below, the normal is arbitrarily set to ( n=\left[0, 0, 1\right] ) and (v) is chosen to satisfy ( \NoV ). The vector ( h_i ) is the ( D_{GGX}(\alpha) ) important direction sample (i).
-float GDFG(float NoV, float NoL, float a) {
- float a2 = a * a;
- float GGXL = NoV * sqrt((-NoL * a2 + NoL) * NoL + a2);
- float GGXV = NoL * sqrt((-NoV * a2 + NoV) * NoV + a2);
+float GDFG(float NoV, float NoL, float a) {
+ float a2 = a * a;
+ float GGXL = NoV * sqrt((-NoL * a2 + NoL) * NoL + a2);
+ float GGXV = NoL * sqrt((-NoV * a2 + NoV) * NoV + a2);
return (2 * NoL) / (GGXV + GGXL);
}
-float2 DFG(float NoV, float a) {
+float2 DFG(float NoV, float a) {
float3 V;
- V.x = sqrt(1.0f - NoV*NoV);
- V.y = 0.0f;
+ V.x = sqrt(1.0f - NoV*NoV);
+ V.y = 0.0f;
V.z = NoV;
- float2 r = 0.0f;
- for (uint i = 0; i < sampleCount; i++) {
- float2 Xi = hammersley(i, sampleCount);
- float3 H = importanceSampleGGX(Xi, a, N);
- float3 L = 2.0f * dot(V, H) * H - V;
+ float2 r = 0.0f;
+ for (uint i = 0; i < sampleCount; i++) {
+ float2 Xi = hammersley(i, sampleCount);
+ float3 H = importanceSampleGGX(Xi, a, N);
+ float3 L = 2.0f * dot(V, H) * H - V;
- float VoH = saturate(dot(V, H));
- float NoL = saturate(L.z);
- float NoH = saturate(H.z);
+ float VoH = saturate(dot(V, H));
+ float NoL = saturate(L.z);
+ float NoH = saturate(H.z);
- if (NoL > 0.0f) {
- float G = GDFG(NoV, NoL, a);
- float Gv = G * VoH / NoH;
- float Fc = pow(1 - VoH, 5.0f);
+ if (NoL > 0.0f) {
+ float G = GDFG(NoV, NoL, a);
+ float Gv = G * VoH / NoH;
+ float Fc = pow(1 - VoH, 5.0f);
r.x += Gv * (1 - Fc);
r.y += Gv * Fc;
}
}
- return r * (1.0f / sampleCount);
+ return r * (1.0f / sampleCount);
}
C++ implementation of the \( L_{DFG} \) term
Spherical Harmonics
@@ -3851,56 +3851,56 @@ sin(m \phi + \phi) &= sin(m \phi) cos(\phi) + cos(m \phi) sin(\phi) \Leftrightar
\end{align*}$$
Listing 47 shows the C++ code to compute the non-normalized SH basis \(\frac{y^m_l(s)}{\sqrt{2} K^m_l}\):
-
static inline size_t SHindex(ssize_t m, size_t l) {
+static inline size_t SHindex(ssize_t m, size_t l) {
return l * (l + 1) + m;
}
-void computeShBasis(
- double* const SHb,
- size_t numBands,
- const vec3& s)
+void computeShBasis(
+ double* const SHb,
+ size_t numBands,
+ const vec3& s)
{
// handle m=0 separately, since it produces only one coefficient
- double Pml_2 = 0;
- double Pml_1 = 1;
+ double Pml_2 = 0;
+ double Pml_1 = 1;
SHb[0] = Pml_1;
- for (ssize_t l = 1; l < numBands; l++) {
- double Pml = ((2 * l - 1) * Pml_1 * s.z - (l - 1) * Pml_2) / l;
+ for (ssize_t l = 1; l < numBands; l++) {
+ double Pml = ((2 * l - 1) * Pml_1 * s.z - (l - 1) * Pml_2) / l;
Pml_2 = Pml_1;
Pml_1 = Pml;
- SHb[SHindex(0, l)] = Pml;
+ SHb[SHindex(0, l)] = Pml;
}
- double Pmm = 1;
- for (ssize_t m = 1; m < numBands ; m++) {
+ double Pmm = 1;
+ for (ssize_t m = 1; m < numBands ; m++) {
Pmm = (1 - 2 * m) * Pmm;
- double Pml_2 = Pmm;
- double Pml_1 = (2 * m + 1)*Pmm*s.z;
+ double Pml_2 = Pmm;
+ double Pml_1 = (2 * m + 1)*Pmm*s.z;
// l == m
- SHb[SHindex(-m, m)] = Pml_2;
- SHb[SHindex( m, m)] = Pml_2;
+ SHb[SHindex(-m, m)] = Pml_2;
+ SHb[SHindex( m, m)] = Pml_2;
if (m + 1 < numBands) {
// l == m+1
- SHb[SHindex(-m, m + 1)] = Pml_1;
- SHb[SHindex( m, m + 1)] = Pml_1;
- for (ssize_t l = m + 2; l < numBands; l++) {
- double Pml = ((2 * l - 1) * Pml_1 * s.z - (l + m - 1) * Pml_2)
+ SHb[SHindex(-m, m + 1)] = Pml_1;
+ SHb[SHindex( m, m + 1)] = Pml_1;
+ for (ssize_t l = m + 2; l < numBands; l++) {
+ double Pml = ((2 * l - 1) * Pml_1 * s.z - (l + m - 1) * Pml_2)
/ (l - m);
Pml_2 = Pml_1;
Pml_1 = Pml;
- SHb[SHindex(-m, l)] = Pml;
- SHb[SHindex( m, l)] = Pml;
+ SHb[SHindex(-m, l)] = Pml;
+ SHb[SHindex( m, l)] = Pml;
}
}
}
- double Cm = s.x;
- double Sm = s.y;
- for (ssize_t m = 1; m <= numBands ; m++) {
- for (ssize_t l = m; l < numBands ; l++) {
- SHb[SHindex(-m, l)] *= Sm;
- SHb[SHindex( m, l)] *= Cm;
+ double Cm = s.x;
+ double Sm = s.y;
+ for (ssize_t m = 1; m <= numBands ; m++) {
+ for (ssize_t l = m; l < numBands ; l++) {
+ SHb[SHindex(-m, l)] *= Sm;
+ SHb[SHindex( m, l)] *= Cm;
}
- double Cm1 = Cm * s.x - Sm * s.y;
- double Sm1 = Sm * s.x + Cm * s.y;
+ double Cm1 = Cm * s.x - Sm * s.y;
+ double Sm1 = Sm * s.x + Cm * s.y;
Cm = Cm1;
Sm = Sm1;
}
@@ -3979,10 +3979,10 @@ $$\begin{equation}
\end{equation}$$
Here is the C++ code to compute \(\hat{C}_l\):
-
static double factorial(size_t n, size_t d = 1);
+static double factorial(size_t n, size_t d = 1);
// < cos(theta) > SH coefficients pre-multiplied by 1 / K(0,l)
-double computeTruncatedCosSh(size_t l) {
+double computeTruncatedCosSh(size_t l) {
if (l == 0) {
return M_PI;
} else if (l == 1) {
@@ -3990,17 +3990,17 @@ Here is the C++ code to compute \(\hat{C}_l\):
} else if (l & 1) {
return 0;
}
- const size_t l_2 = l / 2;
- double A0 = ((l_2 & 1) ? 1.0 : -1.0) / ((l + 2) * (l - 1));
- double A1 = factorial(l, l_2) / (factorial(l_2) * (1 << l));
+ const size_t l_2 = l / 2;
+ double A0 = ((l_2 & 1) ? 1.0 : -1.0) / ((l + 2) * (l - 1));
+ double A1 = factorial(l, l_2) / (factorial(l_2) * (1 << l));
return 2 * M_PI * A0 * A1;
}
// returns n! / d!
-double factorial(size_t n, size_t d ) {
- d = std::max(size_t(1), d);
- n = std::max(size_t(1), n);
- double r = 1.0;
+double factorial(size_t n, size_t d ) {
+ d = std::max(size_t(1), d);
+ n = std::max(size_t(1), n);
+ double r = 1.0;
if (n == d) {
// intentionally left blank
} else if (n > d) {
diff --git a/docs/searchindex.js b/docs/searchindex.js
index f13bf06cc0..f25b6e7115 100644
--- a/docs/searchindex.js
+++ b/docs/searchindex.js
@@ -1 +1 @@
-Object.assign(window.search, {"doc_urls":["dup/intro.html#filament","dup/intro.html#download","dup/intro.html#android","dup/intro.html#ios","dup/intro.html#documentation","dup/intro.html#examples","dup/intro.html#features","dup/intro.html#apis","dup/intro.html#backends","dup/intro.html#rendering","dup/intro.html#post-processing","dup/intro.html#gltf-20","dup/intro.html#rendering-with-filament","dup/intro.html#native-linux-macos-and-windows","dup/intro.html#android-1","dup/intro.html#ios-1","dup/intro.html#assets","dup/intro.html#how-to-make-contributions","dup/intro.html#directory-structure","dup/intro.html#license","dup/intro.html#disclaimer","dup/building.html#building-filament","dup/building.html#prerequisites","dup/building.html#environment-variables","dup/building.html#ide","dup/building.html#easy-build","dup/building.html#filament-specific-cmake-options","dup/building.html#linux","dup/building.html#macos","dup/building.html#ios","dup/building.html#windows","dup/building.html#building-on-windows-with-visual-studio-2019-or-later","dup/building.html#android","dup/building.html#important-sdk-location","dup/building.html#easy-android-build","dup/building.html#android-studio","dup/building.html#manual-builds","dup/building.html#aar","dup/building.html#using-filaments-aar","dup/building.html#webassembly","dup/building.html#running-the-native-samples","dup/building.html#generating-c-documentation","dup/building.html#software-rasterization","dup/building.html#swiftshader-vulkan-tested-on-macos-and-linux","dup/building.html#mesas-llvmpipe-gl-and-lavapipe-vulkan-tested-on-linux","build/windows_android.html#building-filament-for-android-on-windows","build/windows_android.html#prerequisites","build/windows_android.html#a-note-about-python-3","build/windows_android.html#desktop-tools","build/windows_android.html#build","build/windows_android.html#generate-aar","dup/contributing.html#how-to-become-a-contributor-and-submit-your-own-code","dup/contributing.html#contributor-license-agreement","dup/contributing.html#contributing-a-patch","dup/contributing.html#code-style","dup/contributing.html#code-reviews","dup/contributing.html#community-guidelines","dup/contributing.html#dependencies","dup/code_style.html#filament-code-style-and-formatting","dup/code_style.html#formatting","dup/code_style.html#naming-conventions","dup/code_style.html#files","dup/code_style.html#code","dup/code_style.html#code-style","dup/code_style.html#files-1","dup/code_style.html#headers","dup/code_style.html#strings","dup/code_style.html#misc","main/index.html#core-concepts","main/filament.html","main/materials.html","samples/index.html#tutorials-and-samples","samples/ios.html#cocoapods-hello-triangle","samples/ios.html#creating-a-boilerplate-app-with-filament","samples/ios.html#instantiating-the-filament-engine","samples/ios.html#creating-a-swapchain","samples/ios.html#clearing-the-screen","samples/ios.html#drawing-a-triangle","samples/ios.html#compiling-a-custom-material","samples/ios.html#animating-the-triangle","samples/ios.html#next-steps","samples/web.html#web-docs","samples/web.html#this-page-is-under-construction-links-are-not-working-at-the-moment","samples/web.html#tutorials","samples/web.html#demos","samples/web.html#other-documentation","notes/index.html#technical-notes","notes/material_properties.html#crafting-physically-based-materials","notes/material_properties.html#base-colorsrgb","notes/material_properties.html#base-color-luminosity","notes/material_properties.html#metallic-samples","notes/material_properties.html#non-metallic-samples","notes/material_properties.html#metallicgrayscale","notes/material_properties.html#roughnessgrayscale","notes/material_properties.html#non-metallic","notes/material_properties.html#metallic","notes/material_properties.html#reflectancegrayscale","notes/material_properties.html#samples","notes/material_properties.html#clear-coatgrayscale","notes/material_properties.html#clear-coat-roughnessgrayscale","notes/material_properties.html#anisotropygrayscale","release/index.html#release","release/cocoapods.html#filament-cocoapods","release/cocoapods.html#installation","release/cocoapods.html#linting-the-podspec","release/cocoapods.html#debugging-failures","release/cocoapods.html#isolating-subspecs","release/cocoapods.html#testing-a-podspec-locally","release/cocoapods.html#using-the-sample-project","release/maven.html#maven-release","release/maven.html#register-for-a-sonatype-account","release/maven.html#signing-key","release/maven.html#build-the-android-release","release/maven.html#publish-to-sonatype","release/maven.html#a-note-on-the-legacy-staging-service","release/maven.html#1-upload-to-the-central-publisher-portal","release/maven.html#2-publish-the-release-on-sonatype","release/guide.html#filament-release-guide","release/guide.html#0-check-versions","release/guide.html#1-bump-filament-versions-on-main-to-release","release/guide.html#2-update-release_notesmd-on-main","release/guide.html#3-run-release-script","release/guide.html#4-push-the-release-branch","release/guide.html#5-create-the-github-release","release/guide.html#6-delete-the-old-rc-branch-optional","release/guide.html#7-bump-the-version-on-the-new-rc-branch-to-next_release","release/guide.html#8-push-main","release/guide.html#9-push-the-new-rc-branch","release/guide.html#10-rebuild-the-github-release-if-failed","release/guide.html#remove-any-assets-uploaded-to-the-release-if-needed","release/guide.html#update-the-release-branch-if-needed","release/guide.html#re-run-the-github-release-workflow","release/guide.html#11-kick-off-the-npm-and-cocoapods-release-jobs","release/versioning.html#versioning","release/versioning.html#material-versioning","release/branching.html#branching","release/branching.html#which-branch-do-i-open-my-pr-against","release/branching.html#what-consitutes-a-bug","dup/docs.html#documentation","dup/docs.html#how-to-create","dup/docs.html#prerequisites","dup/docs.html#how-to-generate","dup/docs.html#copy-to-docs","dup/docs.html#document-sources","dup/docs.html#introductory-doc","dup/docs.html#core-concept-docs","dup/docs.html#readmes","dup/docs.html#other-technical-notes","dup/docs.html#raw-source-files","dup/docs.html#adding-more-documents","notes/debugging.html#debugging","notes/metal_debugging.html#debugging-metal","notes/metal_debugging.html#enable-metal-validation","notes/metal_debugging.html#metal-frame-capture-from-gltf_viewer","notes/metal_debugging.html#1-create-an-infoplist-file","notes/metal_debugging.html#2-capture-a-frame","notes/vulkan_debugging.html#debugging-vulkan","notes/vulkan_debugging.html#enable-validation-logs","notes/spirv_debugging.html#investigating-spirv-cross--spirv-tools-issues","notes/spirv_debugging.html#build-and-install-command-line-tools-on-path","notes/spirv_debugging.html#clone-and-build-each-repo","notes/spirv_debugging.html#add-directories-to-path","notes/spirv_debugging.html#isolate-the-problematic-glsl-shader","notes/spirv_debugging.html#reproduce-the-compilation-error","notes/spirv_debugging.html#clean-up-the-shader-for-a-bug-report","notes/spirv_debugging.html#submit-an-issue-with-the-relevant-khronos-repository","notes/asan_ubsan.html#running-with-asanubsan","notes/asan_ubsan.html#enabling","notes/asan_ubsan.html#getting-memory-leak-detection-on-mac","notes/asan_ubsan.html#getting-memory-leak-output-in-clion","notes/asan_ubsan.html#setting-variables","notes/asan_ubsan.html#avoiding-losing-output","notes/instruments.html#using-instruments-on-macos","notes/coverage.html#generating-backend-code-coverage","notes/coverage.html#1-prerequisites-install-clang-and-llvm-tools","notes/coverage.html#using-homebrew","notes/coverage.html#using-macports","notes/coverage.html#required-tools","notes/coverage.html#2-build-filament-with-coverage-enabled","notes/coverage.html#3-run-the-backend-tests","notes/coverage.html#4-generate-the-coverage-report","notes/performance_analysis.html#performance-analysis","notes/performance_analysis.html#android","notes/performance_analysis.html#prerequisites","notes/framegraph.html#framegraph","notes/framegraph.html#details","notes/framegraph.html#dependency-graph","notes/framegraph.html#framegraph-1","notes/framegraph.html#an-example","notes/framegraph.html#example-code","notes/framegraph.html#what-does-it-do","notes/framegraph.html#additional-details","notes/tests.html#tests","dup/backend_test.html#backend-unit-tests","dup/backend_test.html#running-with-a-specific-graphics-library","dup/backend_test.html#image-comparisons","dup/backend_test.html#python-utility-for-updating-golden-images-and-comparing-results","dup/backend_test.html#unsupported-tests","dup/test_ci_backend.html#backend-tests","dup/test_ci_backend.html#flags","dup/test_ci_renderdiff.html#rendering-difference-test","dup/test_ci_renderdiff.html#setting-up-python","dup/test_ci_renderdiff.html#running-the-test-locally","dup/test_ci_renderdiff.html#command-line-options","dup/test_ci_renderdiff.html#update-the-golden-images","dup/test_ci_renderdiff.html#using-a-script-to-update-the-golden-repo","dup/test_ci_renderdiff.html#manually-updating-the-golden-repo","dup/test_ci_renderdiff.html#automated-update-via-commit-message","dup/test_ci_renderdiff.html#viewing-test-results","notes/libs.html#libraries","dup/bluegl.html#bluegl-mechanics","dup/bluegl.html#step-0-run-bluegl-genpy","dup/bluegl.html#step-1-include-the-bluegl-defines-header","dup/bluegl.html#step-2-include-the-bluegl-header-after-the-defines-header","dup/bluegl.html#step-3-call-blueglbind","dup/bluegl.html#step-4-call-glclear","dup/bluevk.html#bluevk","dup/bluevk.html#updating-vulkan-headers","dup/fgviewer.html#fgviewer","dup/fgviewer.html#capabilities","dup/fgviewer.html#setup-for-desktop","dup/fgviewer.html#setup-for-android","dup/fgviewer.html#debugger-usage","dup/fgviewer.html#architecture-overview","dup/fgviewer.html#c-server","dup/fgviewer.html#javascript-client","dup/fgviewer.html#http-requests","dup/fgviewer.html#wish-list","dup/filamat.html#filamat","dup/filamat.html#libraries","dup/filamat.html#linking-against-filamat","dup/filamat.html#linux","dup/filamat.html#macos","dup/filamat.html#windows","dup/filamat.html#compiling","dup/filamat.html#using-the-material-with-filament","dup/filamat.html#filamat-lite","dup/gltfio.html#gltfio","dup/gltfio.html#ubershaderprovider","dup/iblprefilter.html#ibl-prefilter","dup/iblprefilter.html#library-and-headers","dup/iblprefilter.html#performance","dup/iblprefilter.html#example","dup/matdbg.html#matdbg","dup/matdbg.html#capabilities","dup/matdbg.html#setup-for-desktop","dup/matdbg.html#setup-for-android","dup/matdbg.html#debugger-usage","dup/matdbg.html#keyboard-shortcuts","dup/matdbg.html#architecture-overview","dup/matdbg.html#c-server","dup/matdbg.html#javascript-client","dup/matdbg.html#http-requests","dup/matdbg.html#wish-list","dup/matdbg.html#screenshot","dup/viewer.html#viewer-library","dup/viewer.html#features","dup/viewer.html#json-settings-schema","dup/viewer.html#root-object","dup/viewer.html#camera-settings-camera","dup/viewer.html#lighting-settings-lighting","dup/viewer.html#view-settings-view","dup/viewer.html#viewer-options-viewer","dup/viewer.html#animation-settings-animation","dup/uberz.html#uberz","dup/uberz.html#ubershader-spec-files","notes/tools.html#tools","dup/beamsplitter.html#beamsplitter","dup/beamsplitter.html#description","dup/beamsplitter.html#instructions","dup/beamsplitter.html#emitter-flags","dup/beamsplitter.html#source-files","dup/beamsplitter.html#output-files","dup/beamsplitter.html#input-format","dup/beamsplitter.html#grammar","dup/beamsplitter.html#references","dup/cmgen.html#cmgen","dup/cmgen.html#usage","dup/cmgen.html#supported-input-formats","dup/cmgen.html#options","dup/cso_lut.html#conesphere-occlusion-lut-generator","dup/filamesh.html#filamesh","dup/filamesh.html#usage","dup/filamesh.html#format","dup/filamesh.html#header","dup/filamesh.html#vertex-data","dup/filamesh.html#index-data","dup/filamesh.html#parts","dup/filamesh.html#materials","dup/filamesh.html#example","dup/matinfo.html#matinfo","dup/matinfo.html#usage","dup/mipgen.html#mipgen","dup/mipgen.html#usage","dup/normal_blending.html#normal-blending","dup/roughness_prefilter.html#roughness-prefilter","dup/specgen.html#specgen-spectral-integration-matrix-generator-for-real-time-dispersion","dup/specgen.html#theoretical-background","dup/specgen.html#1-spectral-rendering-in-rgb","dup/specgen.html#2-basis-transformation-strategy","dup/specgen.html#3-normalization-energy-conservation","dup/specgen.html#4-dispersion-and-ior-offsets","dup/specular_color.html#specular-color","dup/specular_color.html#usage","dup/zbloat.html#zbloat","dup/zbloat.html#linux-macos-and-docker"],"index":{"documentStore":{"docInfo":{"0":{"body":37,"breadcrumbs":2,"title":1},"1":{"body":38,"breadcrumbs":2,"title":1},"10":{"body":46,"breadcrumbs":3,"title":2},"100":{"body":22,"breadcrumbs":5,"title":1},"101":{"body":11,"breadcrumbs":4,"title":1},"102":{"body":9,"breadcrumbs":6,"title":2},"103":{"body":28,"breadcrumbs":5,"title":1},"104":{"body":27,"breadcrumbs":6,"title":2},"105":{"body":13,"breadcrumbs":6,"title":2},"106":{"body":58,"breadcrumbs":6,"title":2},"107":{"body":10,"breadcrumbs":7,"title":3},"108":{"body":57,"breadcrumbs":7,"title":3},"109":{"body":0,"breadcrumbs":6,"title":2},"11":{"body":47,"breadcrumbs":3,"title":2},"110":{"body":51,"breadcrumbs":7,"title":3},"111":{"body":28,"breadcrumbs":6,"title":2},"112":{"body":14,"breadcrumbs":7,"title":3},"113":{"body":0,"breadcrumbs":6,"title":2},"114":{"body":37,"breadcrumbs":8,"title":4},"115":{"body":48,"breadcrumbs":9,"title":5},"116":{"body":35,"breadcrumbs":8,"title":4},"117":{"body":32,"breadcrumbs":7,"title":3},"118":{"body":24,"breadcrumbs":7,"title":3},"119":{"body":21,"breadcrumbs":10,"title":6},"12":{"body":0,"breadcrumbs":3,"title":2},"120":{"body":28,"breadcrumbs":8,"title":4},"121":{"body":21,"breadcrumbs":8,"title":4},"122":{"body":4,"breadcrumbs":8,"title":4},"123":{"body":15,"breadcrumbs":8,"title":4},"124":{"body":15,"breadcrumbs":10,"title":6},"125":{"body":13,"breadcrumbs":11,"title":7},"126":{"body":4,"breadcrumbs":7,"title":3},"127":{"body":5,"breadcrumbs":9,"title":5},"128":{"body":11,"breadcrumbs":9,"title":5},"129":{"body":12,"breadcrumbs":9,"title":5},"13":{"body":161,"breadcrumbs":5,"title":4},"130":{"body":37,"breadcrumbs":8,"title":4},"131":{"body":21,"breadcrumbs":9,"title":5},"132":{"body":36,"breadcrumbs":10,"title":6},"133":{"body":70,"breadcrumbs":5,"title":1},"134":{"body":73,"breadcrumbs":6,"title":2},"135":{"body":3,"breadcrumbs":5,"title":1},"136":{"body":99,"breadcrumbs":8,"title":4},"137":{"body":36,"breadcrumbs":6,"title":2},"138":{"body":7,"breadcrumbs":4,"title":1},"139":{"body":0,"breadcrumbs":6,"title":3},"14":{"body":60,"breadcrumbs":2,"title":1},"140":{"body":35,"breadcrumbs":4,"title":1},"141":{"body":37,"breadcrumbs":4,"title":1},"142":{"body":11,"breadcrumbs":5,"title":2},"143":{"body":11,"breadcrumbs":5,"title":2},"144":{"body":39,"breadcrumbs":5,"title":2},"145":{"body":104,"breadcrumbs":6,"title":3},"146":{"body":39,"breadcrumbs":4,"title":1},"147":{"body":16,"breadcrumbs":5,"title":2},"148":{"body":19,"breadcrumbs":6,"title":3},"149":{"body":41,"breadcrumbs":6,"title":3},"15":{"body":31,"breadcrumbs":2,"title":1},"150":{"body":5,"breadcrumbs":4,"title":1},"151":{"body":0,"breadcrumbs":6,"title":2},"152":{"body":31,"breadcrumbs":7,"title":3},"153":{"body":5,"breadcrumbs":8,"title":4},"154":{"body":28,"breadcrumbs":8,"title":4},"155":{"body":21,"breadcrumbs":7,"title":3},"156":{"body":0,"breadcrumbs":6,"title":2},"157":{"body":42,"breadcrumbs":7,"title":3},"158":{"body":18,"breadcrumbs":11,"title":6},"159":{"body":13,"breadcrumbs":11,"title":6},"16":{"body":30,"breadcrumbs":2,"title":1},"160":{"body":95,"breadcrumbs":9,"title":4},"161":{"body":21,"breadcrumbs":8,"title":3},"162":{"body":90,"breadcrumbs":9,"title":4},"163":{"body":140,"breadcrumbs":8,"title":3},"164":{"body":83,"breadcrumbs":10,"title":5},"165":{"body":19,"breadcrumbs":10,"title":5},"166":{"body":0,"breadcrumbs":8,"title":2},"167":{"body":72,"breadcrumbs":7,"title":1},"168":{"body":62,"breadcrumbs":11,"title":5},"169":{"body":0,"breadcrumbs":11,"title":5},"17":{"body":10,"breadcrumbs":3,"title":2},"170":{"body":35,"breadcrumbs":8,"title":2},"171":{"body":49,"breadcrumbs":9,"title":3},"172":{"body":81,"breadcrumbs":9,"title":3},"173":{"body":20,"breadcrumbs":10,"title":4},"174":{"body":14,"breadcrumbs":12,"title":6},"175":{"body":16,"breadcrumbs":8,"title":2},"176":{"body":23,"breadcrumbs":8,"title":2},"177":{"body":30,"breadcrumbs":8,"title":2},"178":{"body":40,"breadcrumbs":11,"title":5},"179":{"body":36,"breadcrumbs":10,"title":4},"18":{"body":311,"breadcrumbs":3,"title":2},"180":{"body":95,"breadcrumbs":10,"title":4},"181":{"body":0,"breadcrumbs":7,"title":2},"182":{"body":0,"breadcrumbs":6,"title":1},"183":{"body":608,"breadcrumbs":6,"title":1},"184":{"body":46,"breadcrumbs":4,"title":1},"185":{"body":0,"breadcrumbs":4,"title":1},"186":{"body":41,"breadcrumbs":5,"title":2},"187":{"body":40,"breadcrumbs":4,"title":1},"188":{"body":71,"breadcrumbs":4,"title":1},"189":{"body":147,"breadcrumbs":5,"title":2},"19":{"body":3,"breadcrumbs":2,"title":1},"190":{"body":51,"breadcrumbs":3,"title":0},"191":{"body":87,"breadcrumbs":5,"title":2},"192":{"body":11,"breadcrumbs":4,"title":1},"193":{"body":20,"breadcrumbs":7,"title":3},"194":{"body":10,"breadcrumbs":8,"title":4},"195":{"body":58,"breadcrumbs":6,"title":2},"196":{"body":148,"breadcrumbs":11,"title":7},"197":{"body":12,"breadcrumbs":6,"title":2},"198":{"body":35,"breadcrumbs":7,"title":2},"199":{"body":27,"breadcrumbs":6,"title":1},"2":{"body":70,"breadcrumbs":2,"title":1},"20":{"body":4,"breadcrumbs":2,"title":1},"200":{"body":70,"breadcrumbs":8,"title":3},"201":{"body":48,"breadcrumbs":8,"title":3},"202":{"body":31,"breadcrumbs":8,"title":3},"203":{"body":46,"breadcrumbs":8,"title":3},"204":{"body":47,"breadcrumbs":8,"title":3},"205":{"body":25,"breadcrumbs":10,"title":5},"206":{"body":82,"breadcrumbs":9,"title":4},"207":{"body":49,"breadcrumbs":10,"title":5},"208":{"body":107,"breadcrumbs":8,"title":3},"209":{"body":4,"breadcrumbs":4,"title":1},"21":{"body":0,"breadcrumbs":4,"title":2},"210":{"body":3,"breadcrumbs":6,"title":2},"211":{"body":31,"breadcrumbs":9,"title":5},"212":{"body":9,"breadcrumbs":10,"title":6},"213":{"body":8,"breadcrumbs":11,"title":7},"214":{"body":27,"breadcrumbs":8,"title":4},"215":{"body":34,"breadcrumbs":8,"title":4},"216":{"body":0,"breadcrumbs":5,"title":1},"217":{"body":52,"breadcrumbs":7,"title":3},"218":{"body":17,"breadcrumbs":5,"title":1},"219":{"body":19,"breadcrumbs":5,"title":1},"22":{"body":46,"breadcrumbs":3,"title":1},"220":{"body":54,"breadcrumbs":6,"title":2},"221":{"body":93,"breadcrumbs":6,"title":2},"222":{"body":15,"breadcrumbs":6,"title":2},"223":{"body":51,"breadcrumbs":6,"title":2},"224":{"body":44,"breadcrumbs":6,"title":2},"225":{"body":40,"breadcrumbs":6,"title":2},"226":{"body":113,"breadcrumbs":6,"title":2},"227":{"body":4,"breadcrumbs":6,"title":2},"228":{"body":41,"breadcrumbs":5,"title":1},"229":{"body":51,"breadcrumbs":5,"title":1},"23":{"body":20,"breadcrumbs":4,"title":2},"230":{"body":114,"breadcrumbs":7,"title":3},"231":{"body":35,"breadcrumbs":5,"title":1},"232":{"body":30,"breadcrumbs":5,"title":1},"233":{"body":68,"breadcrumbs":5,"title":1},"234":{"body":23,"breadcrumbs":5,"title":1},"235":{"body":35,"breadcrumbs":7,"title":3},"236":{"body":77,"breadcrumbs":6,"title":2},"237":{"body":71,"breadcrumbs":5,"title":1},"238":{"body":57,"breadcrumbs":5,"title":1},"239":{"body":33,"breadcrumbs":6,"title":2},"24":{"body":14,"breadcrumbs":3,"title":1},"240":{"body":9,"breadcrumbs":6,"title":2},"241":{"body":14,"breadcrumbs":5,"title":1},"242":{"body":51,"breadcrumbs":5,"title":1},"243":{"body":22,"breadcrumbs":5,"title":1},"244":{"body":61,"breadcrumbs":5,"title":1},"245":{"body":54,"breadcrumbs":6,"title":2},"246":{"body":115,"breadcrumbs":6,"title":2},"247":{"body":83,"breadcrumbs":6,"title":2},"248":{"body":30,"breadcrumbs":6,"title":2},"249":{"body":90,"breadcrumbs":6,"title":2},"25":{"body":95,"breadcrumbs":4,"title":2},"250":{"body":42,"breadcrumbs":6,"title":2},"251":{"body":93,"breadcrumbs":6,"title":2},"252":{"body":209,"breadcrumbs":6,"title":2},"253":{"body":59,"breadcrumbs":6,"title":2},"254":{"body":0,"breadcrumbs":5,"title":1},"255":{"body":21,"breadcrumbs":6,"title":2},"256":{"body":41,"breadcrumbs":5,"title":1},"257":{"body":11,"breadcrumbs":7,"title":3},"258":{"body":49,"breadcrumbs":6,"title":2},"259":{"body":108,"breadcrumbs":7,"title":3},"26":{"body":68,"breadcrumbs":6,"title":4},"260":{"body":105,"breadcrumbs":7,"title":3},"261":{"body":42,"breadcrumbs":7,"title":3},"262":{"body":22,"breadcrumbs":7,"title":3},"263":{"body":17,"breadcrumbs":7,"title":3},"264":{"body":145,"breadcrumbs":5,"title":1},"265":{"body":168,"breadcrumbs":7,"title":3},"266":{"body":4,"breadcrumbs":4,"title":1},"267":{"body":10,"breadcrumbs":5,"title":1},"268":{"body":16,"breadcrumbs":5,"title":1},"269":{"body":15,"breadcrumbs":5,"title":1},"27":{"body":193,"breadcrumbs":3,"title":1},"270":{"body":42,"breadcrumbs":6,"title":2},"271":{"body":1,"breadcrumbs":6,"title":2},"272":{"body":21,"breadcrumbs":6,"title":2},"273":{"body":118,"breadcrumbs":6,"title":2},"274":{"body":158,"breadcrumbs":5,"title":1},"275":{"body":51,"breadcrumbs":5,"title":1},"276":{"body":47,"breadcrumbs":5,"title":1},"277":{"body":7,"breadcrumbs":5,"title":1},"278":{"body":13,"breadcrumbs":7,"title":3},"279":{"body":151,"breadcrumbs":5,"title":1},"28":{"body":51,"breadcrumbs":3,"title":1},"280":{"body":8,"breadcrumbs":9,"title":4},"281":{"body":63,"breadcrumbs":5,"title":1},"282":{"body":3,"breadcrumbs":5,"title":1},"283":{"body":21,"breadcrumbs":5,"title":1},"284":{"body":135,"breadcrumbs":5,"title":1},"285":{"body":62,"breadcrumbs":6,"title":2},"286":{"body":7,"breadcrumbs":6,"title":2},"287":{"body":44,"breadcrumbs":5,"title":1},"288":{"body":19,"breadcrumbs":5,"title":1},"289":{"body":324,"breadcrumbs":5,"title":1},"29":{"body":22,"breadcrumbs":3,"title":1},"290":{"body":12,"breadcrumbs":5,"title":1},"291":{"body":4,"breadcrumbs":5,"title":1},"292":{"body":7,"breadcrumbs":5,"title":1},"293":{"body":11,"breadcrumbs":5,"title":1},"294":{"body":29,"breadcrumbs":7,"title":2},"295":{"body":21,"breadcrumbs":7,"title":2},"296":{"body":0,"breadcrumbs":12,"title":8},"297":{"body":0,"breadcrumbs":6,"title":2},"298":{"body":58,"breadcrumbs":8,"title":4},"299":{"body":114,"breadcrumbs":8,"title":4},"3":{"body":10,"breadcrumbs":2,"title":1},"30":{"body":0,"breadcrumbs":3,"title":1},"300":{"body":133,"breadcrumbs":8,"title":4},"301":{"body":59,"breadcrumbs":8,"title":4},"302":{"body":56,"breadcrumbs":7,"title":2},"303":{"body":30,"breadcrumbs":6,"title":1},"304":{"body":70,"breadcrumbs":5,"title":1},"305":{"body":49,"breadcrumbs":7,"title":3},"31":{"body":120,"breadcrumbs":8,"title":6},"32":{"body":56,"breadcrumbs":3,"title":1},"33":{"body":18,"breadcrumbs":5,"title":3},"34":{"body":55,"breadcrumbs":5,"title":3},"35":{"body":159,"breadcrumbs":4,"title":2},"36":{"body":64,"breadcrumbs":4,"title":2},"37":{"body":86,"breadcrumbs":3,"title":1},"38":{"body":63,"breadcrumbs":5,"title":3},"39":{"body":155,"breadcrumbs":3,"title":1},"4":{"body":49,"breadcrumbs":2,"title":1},"40":{"body":158,"breadcrumbs":5,"title":3},"41":{"body":19,"breadcrumbs":5,"title":3},"42":{"body":35,"breadcrumbs":4,"title":2},"43":{"body":29,"breadcrumbs":7,"title":5},"44":{"body":93,"breadcrumbs":9,"title":7},"45":{"body":0,"breadcrumbs":8,"title":4},"46":{"body":57,"breadcrumbs":5,"title":1},"47":{"body":22,"breadcrumbs":7,"title":3},"48":{"body":57,"breadcrumbs":6,"title":2},"49":{"body":95,"breadcrumbs":5,"title":1},"5":{"body":10,"breadcrumbs":2,"title":1},"50":{"body":68,"breadcrumbs":6,"title":2},"51":{"body":0,"breadcrumbs":6,"title":4},"52":{"body":44,"breadcrumbs":5,"title":3},"53":{"body":55,"breadcrumbs":4,"title":2},"54":{"body":2,"breadcrumbs":4,"title":2},"55":{"body":20,"breadcrumbs":4,"title":2},"56":{"body":7,"breadcrumbs":4,"title":2},"57":{"body":39,"breadcrumbs":3,"title":1},"58":{"body":43,"breadcrumbs":7,"title":4},"59":{"body":33,"breadcrumbs":4,"title":1},"6":{"body":0,"breadcrumbs":2,"title":1},"60":{"body":0,"breadcrumbs":5,"title":2},"61":{"body":84,"breadcrumbs":4,"title":1},"62":{"body":79,"breadcrumbs":4,"title":1},"63":{"body":0,"breadcrumbs":5,"title":2},"64":{"body":61,"breadcrumbs":4,"title":1},"65":{"body":152,"breadcrumbs":4,"title":1},"66":{"body":19,"breadcrumbs":4,"title":1},"67":{"body":14,"breadcrumbs":4,"title":1},"68":{"body":14,"breadcrumbs":4,"title":2},"69":{"body":21814,"breadcrumbs":3,"title":2},"7":{"body":13,"breadcrumbs":2,"title":1},"70":{"body":10186,"breadcrumbs":3,"title":2},"71":{"body":18,"breadcrumbs":4,"title":2},"72":{"body":80,"breadcrumbs":7,"title":3},"73":{"body":61,"breadcrumbs":8,"title":4},"74":{"body":142,"breadcrumbs":7,"title":3},"75":{"body":141,"breadcrumbs":6,"title":2},"76":{"body":305,"breadcrumbs":6,"title":2},"77":{"body":265,"breadcrumbs":6,"title":2},"78":{"body":248,"breadcrumbs":7,"title":3},"79":{"body":96,"breadcrumbs":6,"title":2},"8":{"body":28,"breadcrumbs":2,"title":1},"80":{"body":34,"breadcrumbs":6,"title":2},"81":{"body":0,"breadcrumbs":6,"title":2},"82":{"body":0,"breadcrumbs":10,"title":6},"83":{"body":6,"breadcrumbs":5,"title":1},"84":{"body":4,"breadcrumbs":5,"title":1},"85":{"body":4,"breadcrumbs":5,"title":1},"86":{"body":6,"breadcrumbs":4,"title":2},"87":{"body":0,"breadcrumbs":8,"title":4},"88":{"body":18,"breadcrumbs":6,"title":2},"89":{"body":12,"breadcrumbs":7,"title":3},"9":{"body":89,"breadcrumbs":2,"title":1},"90":{"body":24,"breadcrumbs":6,"title":2},"91":{"body":24,"breadcrumbs":7,"title":3},"92":{"body":22,"breadcrumbs":5,"title":1},"93":{"body":9,"breadcrumbs":5,"title":1},"94":{"body":1,"breadcrumbs":6,"title":2},"95":{"body":1,"breadcrumbs":5,"title":1},"96":{"body":20,"breadcrumbs":5,"title":1},"97":{"body":24,"breadcrumbs":5,"title":1},"98":{"body":27,"breadcrumbs":6,"title":2},"99":{"body":23,"breadcrumbs":7,"title":3}},"docs":{"0":{"body":"Android Build Status iOS Build Status Linux Build Status macOS Build Status Windows Build Status Web Build Status Filament is a real-time physically based rendering engine for Android, iOS, Linux, macOS, Windows, and WebGL. It is designed to be as small as possible and as efficient as possible on Android.","breadcrumbs":"Introduction » Filament","id":"0","title":"Filament"},"1":{"body":"Download Filament releases to access stable builds. Filament release archives contains host-side tools that are required to generate assets. Make sure you always use tools from the same release as the runtime library. This is particularly important for matc (material compiler). If you'd rather build Filament yourself, please refer to our build manual .","breadcrumbs":"Introduction » Download","id":"1","title":"Download"},"10":{"body":"HDR bloom Depth of field bokeh Multiple tone mappers: PBR Neutral, AgX, generic (customizable), ACES, filmic, etc. Color and tone management: luminance scaling, gamut mapping Color grading: exposure, night adaptation, white balance, channel mixer, shadows/mid-tones/highlights, ASC CDL, contrast, saturation, etc. TAA, FXAA, MSAA Screen-space lens flares","breadcrumbs":"Introduction » Post processing","id":"10","title":"Post processing"},"100":{"body":"Defines whether the material appearance is directionally dependent , that is isotropic (0.0) or anisotropic (1.0). Brushed metals are anisotropic . Values can be negative to change the orientation of the specular reflections. 0.00.10.20.30.40.50.60.70.80.91.0 ISOTROPIC ANISOTROPIC","breadcrumbs":"Technical Notes » Material Properties » ANISOTROPY/GRAYSCALE","id":"100","title":"ANISOTROPY/GRAYSCALE"},"101":{"body":"This is a collection of guides for releasing Filament on different distribution platforms, including Github, Maven, and CocoaPods.","breadcrumbs":"Technical Notes » Release » Release","id":"101","title":"Release"},"102":{"body":"CocoaPods is the dependency manager Filament uses for Apple platforms (macOS and iOS).","breadcrumbs":"Technical Notes » Release » CocoaPods » Filament CocoaPods","id":"102","title":"Filament CocoaPods"},"103":{"body":"On macOS, CocoaPods requires a modern Ruby environment. Avoid using the system Ruby; instead, install the latest Ruby version using brew, port, or use a manager like rbenv or rvm. Once Ruby is configured: gem install cocoapods","breadcrumbs":"Technical Notes » Release » CocoaPods » Installation","id":"103","title":"Installation"},"104":{"body":"The Filament podspec is configured to fetch releases directly from GitHub. Before deployment, CocoaPods must lint the spec to validate that the library compiles and links correctly across all supported architectures. To run the linter locally: cd ios/CocoaPods/\npod spec lint","breadcrumbs":"Technical Notes » Release » CocoaPods » Linting the Podspec","id":"104","title":"Linting the Podspec"},"105":{"body":"If the lint fails, use the --verbose flag to inspect the underlying xcodebuild output: pod spec lint --verbose","breadcrumbs":"Technical Notes » Release » CocoaPods » Debugging Failures","id":"105","title":"Debugging Failures"},"106":{"body":"Filament is partitioned into multiple subspecs . CocoaPods lints these individually. To accelerate debugging or isolate a specific build failure (e.g., Filament/filament), use the following command: pod spec lint --no-clean --verbose --subspec=Filament/filament 2>&1 | tee lint_output.log --no-clean: Preserves the temporary Xcode workspace and build artifacts in /var/folders/... for inspection. --verbose: Prints the full compiler and linker invocations. --subspec: Limits the scope of the lint to a specific component. Tip: To view all defined subspecs, grep the podspec file: grep \"spec.subspec\" ios/CocoaPods/Filament.podspec","breadcrumbs":"Technical Notes » Release » CocoaPods » Isolating Subspecs","id":"106","title":"Isolating Subspecs"},"107":{"body":"Before pushing a new version to the CocoaPods trunk, you should verify the podspec in a sample project.","breadcrumbs":"Technical Notes » Release » CocoaPods » Testing a Podspec Locally","id":"107","title":"Testing a Podspec Locally"},"108":{"body":"Filament includes a dedicated sample project located in ios/samples/HelloCocoaPods. To test your local changes: Modify the Podfile : Add a :podspec directive pointing to your local .podspec file. platform :ios, '13.0' target 'HelloCocoaPods' do # Use the local development podspec pod 'Filament', :podspec => '../../CocoaPods/Filament.podspec'\nend Sync Dependencies : Run the installation command from the sample directory: pod install Verify the Build : Open the generated HelloCocoaPods.xcworkspace in Xcode. Build and run the target to ensure the headers are found and the binaries link correctly.","breadcrumbs":"Technical Notes » Release » CocoaPods » Using the Sample Project","id":"108","title":"Using the Sample Project"},"109":{"body":"","breadcrumbs":"Technical Notes » Release » Maven » Maven Release","id":"109","title":"Maven Release"},"11":{"body":"Encodings Embeded Binary Primitive Types Points Lines Line Loop Line Strip Triangles Triangle Strip Triangle Fan Animation Transform animation Linear interpolation Morph animation Sparse accessor Skin animation Joint animation Extensions KHR_draco_mesh_compression KHR_lights_punctual KHR_materials_clearcoat KHR_materials_dispersion KHR_materials_emissive_strength KHR_materials_ior KHR_materials_pbrSpecularGlossiness KHR_materials_sheen KHR_materials_specular KHR_materials_transmission KHR_materials_unlit KHR_materials_variants KHR_materials_volume KHR_mesh_quantization KHR_texture_basisu KHR_texture_transform EXT_meshopt_compression","breadcrumbs":"Introduction » glTF 2.0","id":"11","title":"glTF 2.0"},"110":{"body":"First, you'll need to register for a Sonatype account at the Central Portal . To publish under the com.google.android namespace, you'll also need to email central-support@sonatype.com with your account information to request access. Then, generate a user token through the Sonatype website. Navigate to https://central.sonatype.com/usertoken and select Generate User Token . Finally, add the generated token credentials to ~/.gradle/gradle.properties. (Note: these are different from the credentials used to log into your Sonatype account): # Generated Sonatype token\nsonatypeUsername=\nsonatypePassword=","breadcrumbs":"Technical Notes » Release » Maven » Register for a Sonatype Account","id":"110","title":"Register for a Sonatype Account"},"111":{"body":"All release artifacts must be signed. You'll need to create an OpenPGP key pair. See Gradle's documentation on Signatory credentials for instructions. Update ~/.gradle/gradle.properties with your new key's credentials: signing.keyId=\nsigning.password=\nsigning.secretKeyRingFile=","breadcrumbs":"Technical Notes » Release » Maven » Signing Key","id":"111","title":"Signing Key"},"112":{"body":"Make sure JAVA_HOME is set correctly. For example: export JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home\n./build.sh -C -i -p android release","breadcrumbs":"Technical Notes » Release » Maven » Build the Android Release","id":"112","title":"Build the Android Release"},"113":{"body":"","breadcrumbs":"Technical Notes » Release » Maven » Publish to Sonatype","id":"113","title":"Publish to Sonatype"},"114":{"body":"Previously, Filament was published to Maven via OSSRH (Open Source Software Repository Hosting). In 2025, this service was sunsetted . Now, we use Sonatype's Central Publisher Portal . The new Central Publisher Portal does not officially support Gradle. However, Sonatype provides a staging API compatibility service, which works with Filament's Gradle setup.","breadcrumbs":"Technical Notes » Release » Maven » A Note on the Legacy Staging Service","id":"114","title":"A Note on the Legacy Staging Service"},"115":{"body":"To upload the artifacts, it is important to run both of these Gradle tasks together in a single command. This ensures the staging repository is created and closed automatically. cd android\n./gradlew publishToSonatype closeSonatypeStagingRepository Troubleshooting: Manual Staging If you ran publishToSonatype by itself, the repository will remain open and won't appear in the portal correctly. You can fix this by running our automation script, which uses the sonatypeUsername and sonatypePassword from your ~/.gradle/gradle.properties file: python3 build/common/close-sonatype-staging-repository.py","breadcrumbs":"Technical Notes » Release » Maven » 1. Upload to the Central Publisher Portal","id":"115","title":"1. Upload to the Central Publisher Portal"},"116":{"body":"Once the upload is successful, you must manually trigger the final release. Navigate to Maven Central Repository Deployments . Here, you should see a new deployment with a Validated status and all your artifacts listed. Click the Publish button to publish the artifacts. It typically takes around 5 minutes after clicking Publish for the artifacts to go live.","breadcrumbs":"Technical Notes » Release » Maven » 2. Publish the Release on Sonatype","id":"116","title":"2. Publish the Release on Sonatype"},"117":{"body":"This guide makes use of some \"environment variables\": $RELEASE = the new version of Filament we are releasing today. (e.g., 1.9.3) $NEXT_RELEASE = the version we plan to release next week (e.g., 1.9.4) Before starting, ensure that each of these branches is up-to-date with origin: release rc/$RELEASE main","breadcrumbs":"Technical Notes » Release » Github » Filament Release Guide","id":"117","title":"Filament Release Guide"},"118":{"body":"Make sure the rc/$RELEASE branch has the correct Filament version. It should have the version corresponding to its name, $RELEASE. Make sure MATERIAL_VERSION has been bumped to a new version if this is a MAJOR or MINOR release (first two version numbers).","breadcrumbs":"Technical Notes » Release » Github » 0. Check versions.","id":"118","title":"0. Check versions."},"119":{"body":"Checkout main and run the following command to bump Filament's version to $RELEASE: build/common/bump-version.sh $RELEASE Commit changes to main with the title: Release Filament $RELEASE Do not push to origin yet.","breadcrumbs":"Technical Notes » Release » Github » 1. Bump Filament versions on main to $RELEASE.","id":"119","title":"1. Bump Filament versions on main to $RELEASE."},"12":{"body":"","breadcrumbs":"Introduction » Rendering with Filament","id":"12","title":"Rendering with Filament"},"120":{"body":"Create a new header in RELEASE_NOTES.md for $NEXT_RELEASE. Copy the release notes in NEW_RELEASE_NOTES.md to RELEASE_NOTES.md under the new header. Clear NEW_RELEASE_NOTES.md. Amend these changes to the \"Release Filament $RELEASE\" commit. git add -u\ngit commit --amend --no-edit","breadcrumbs":"Technical Notes » Release » Github » 2. Update RELEASE_NOTES.md on main.","id":"120","title":"2. Update RELEASE_NOTES.md on main."},"121":{"body":"build/common/release.sh rc/$RELEASE rc/$NEXT_RELEASE This script will merge rc/$RELEASE into release, delete the rc branch, and create a new rc branch called rc/$NEXT_RELEASE. Verify that everything looks okay locally.","breadcrumbs":"Technical Notes » Release » Github » 3. Run release script.","id":"121","title":"3. Run release script."},"122":{"body":"git push origin release","breadcrumbs":"Technical Notes » Release » Github » 4. Push the release branch.","id":"122","title":"4. Push the release branch."},"123":{"body":"Use the GitHub UI to create a GitHub release corresponding to $RELEASE version. Make sure the target is set to the release branch.","breadcrumbs":"Technical Notes » Release » Github » 5. Create the GitHub release.","id":"123","title":"5. Create the GitHub release."},"124":{"body":"This step is optional. The old rc branch may be left alive for a few weeks for posterity. git push origin --delete rc/$RELEASE","breadcrumbs":"Technical Notes » Release » Github » 6. Delete the old rc branch (optional).","id":"124","title":"6. Delete the old rc branch (optional)."},"125":{"body":"git checkout rc/$NEXT_RELEASE\nbuild/common/bump-version.sh $NEXT_RELEASE Commit the changes to rc/$NEXT_RELEASE with the title: Bump version to $NEXT_RELEASE","breadcrumbs":"Technical Notes » Release » Github » 7. Bump the version on the new rc branch to $NEXT_RELEASE.","id":"125","title":"7. Bump the version on the new rc branch to $NEXT_RELEASE."},"126":{"body":"git push origin main","breadcrumbs":"Technical Notes » Release » Github » 8. Push main.","id":"126","title":"8. Push main."},"127":{"body":"git push origin -u rc/$NEXT_RELEASE","breadcrumbs":"Technical Notes » Release » Github » 9. Push the new rc branch.","id":"127","title":"9. Push the new rc branch."},"128":{"body":"Sometimes the GitHub release job will fail. In this case, you can manually re-run the release job.","breadcrumbs":"Technical Notes » Release » Github » 10. Rebuild the GitHub release (if failed).","id":"128","title":"10. Rebuild the GitHub release (if failed)."},"129":{"body":"For example, if rebuilding the Mac release, ensure that the filament--mac.tgz artifact is removed from the release assets.","breadcrumbs":"Technical Notes » Release » Github » Remove any assets uploaded to the release (if needed).","id":"129","title":"Remove any assets uploaded to the release (if needed)."},"13":{"body":"You must create an Engine, a Renderer and a SwapChain. The SwapChain is created from a native window pointer (an NSView on macOS or a HWND on Windows for instance): Engine* engine = Engine::create();\nSwapChain* swapChain = engine->createSwapChain(nativeWindow);\nRenderer* renderer = engine->createRenderer(); To render a frame you must then create a View, a Scene and a Camera: Camera* camera = engine->createCamera(EntityManager::get().create());\nView* view = engine->createView();\nScene* scene = engine->createScene(); view->setCamera(camera);\nview->setScene(scene); Renderables are added to the scene: Entity renderable = EntityManager::get().create();\n// build a quad\nRenderableManager::Builder(1) .boundingBox({{ -1, -1, -1 }, { 1, 1, 1 }}) .material(0, materialInstance) .geometry(0, RenderableManager::PrimitiveType::TRIANGLES, vertexBuffer, indexBuffer, 0, 6) .culling(false) .build(*engine, renderable);\nscene->addEntity(renderable); The material instance is obtained from a material, itself loaded from a binary blob generated by matc: Material* material = Material::Builder() .package((void*) BAKED_MATERIAL_PACKAGE, sizeof(BAKED_MATERIAL_PACKAGE)) .build(*engine);\nMaterialInstance* materialInstance = material->createInstance(); To learn more about materials and matc, please refer to the materials documentation . To render, simply pass the View to the Renderer: // beginFrame() returns false if we need to skip a frame\nif (renderer->beginFrame(swapChain)) { // for each View renderer->render(view); renderer->endFrame();\n} For complete examples of Linux, macOS and Windows Filament applications, look at the source files in the samples/ directory. These samples are all based on libs/filamentapp/ which contains the code that creates a native window with SDL2 and initializes the Filament engine, renderer and views. For more information on how to prepare environment maps for image-based lighting please refer to BUILDING.md .","breadcrumbs":"Introduction » Native Linux, macOS and Windows","id":"13","title":"Native Linux, macOS and Windows"},"130":{"body":"If you need to add one or more new commits to the release, perform the following: First, push the new commit(s) to the release branch. Then, with the release branch checked out with the new commit(s), run git tag -f -a \ngit push origin -f This will update and force push the tag.","breadcrumbs":"Technical Notes » Release » Github » Update the release branch (if needed).","id":"130","title":"Update the release branch (if needed)."},"131":{"body":"Navigate to Filament's release workflow . Hit the Run workflow dropdown. Modify Platform to build and Release tag to build , then hit Run workflow . This will initiate a new release run.","breadcrumbs":"Technical Notes » Release » Github » Re-run the GitHub release workflow","id":"131","title":"Re-run the GitHub release workflow"},"132":{"body":"Navigate to Filament's npm deploy workflow . Hit the Run workflow dropdown. Modify Release tag to deploy to the tag corresponding to this release (for example, v1.42.2). Navigate to Filament's CocoaPods deploy workflow . Hit the Run workflow dropdown. Modify Release tag to deploy to the tag corresponding to this release (for example, v1.42.2).","breadcrumbs":"Technical Notes » Release » Github » 11. Kick off the npm and CocoaPods release jobs","id":"132","title":"11. Kick off the npm and CocoaPods release jobs"},"133":{"body":"Filament uses a 3-number versioning scheme that superficially resembles a semantic version but is actually more interesting because of our material system. Here are the guidelines: Increment the most significant number only when making a non-backwards compatible API change, or when introducing a major new API. Increment the middle number only when making a non-backwards compatible change to the material system. When this number gets bumped, users need to rebuild their mat files. Reset the middle number to zero when the most significant number has been incremented. Increment the least significant number each time a new release is published. Reset this number to zero if one of the other two numbers have been incremented.","breadcrumbs":"Technical Notes » Release » Versioning » Versioning","id":"133","title":"Versioning"},"134":{"body":"Additionally, the Filament renderer and material compiler internally contain a standalone integer called MATERIAL_VERSION, defined in MaterialEnums.h. This should be incremented every time we change the middle number in the public-facing version. When a material version mismatch is detected at run time, a panic is triggered, even in release builds. Therefore we should increment this only when making a serious breaking change to the material system (e.g. changing the size of a uniform block). Cosmetic shader changes usually do not merit a change to the material version number. Currently our material archives have two version chunks, one for \"normal\" materials and one for post-process materials. However for now these two numbers must be set to the same value.","breadcrumbs":"Technical Notes » Release » Versioning » Material Versioning","id":"134","title":"Material Versioning"},"135":{"body":"Filament branching strategy","breadcrumbs":"Technical Notes » Release » Branching » Branching","id":"135","title":"Branching"},"136":{"body":"For normal development, open PRs against main. Once they're merged, no further action is necessary. If you discover a bug with the latest release candidate , open a bug fix PR against the release candidate branch (rc/1.9.0, for example). Once the PR is merged, decide whether it makes sense for the fix to also go into main. If it was a temporary fix, simply make the correct fix in main as you would any other change. If the fix is good for main as well, use git cherry-pick to cherry-pick it into main. If an immediate hotfix is needed on the release branch, open a PR against the release branch. Once the PR is merged, decide whether the fix is temporary or permanent. If the fix was temporary, make the correct fix in both the next release candidate branch and main. If the fix is good, use git cherry-pick to cherry-pick it into the relase candidate branch and main.","breadcrumbs":"Technical Notes » Release » Branching » Which branch do I open my PR against?","id":"136","title":"Which branch do I open my PR against?"},"137":{"body":"Only bug fix PRs should be opened against the release candidate branch. Bugs are defined as one of the following introduced since the prior release : crashes rendering issues unintentional binary size increases unintentional public API changes For example, a long-standing crash just recently discovered would not necessitate a bug fix PR.","breadcrumbs":"Technical Notes » Release » Branching » What consitutes a bug?","id":"137","title":"What consitutes a bug?"},"138":{"body":"Filament's documentation (which you are reading) is a collection of pages created with mdBook .","breadcrumbs":"Technical Notes » Documentation » Documentation","id":"138","title":"Documentation"},"139":{"body":"","breadcrumbs":"Technical Notes » Documentation » How the book is created and updated","id":"139","title":"How the book is created and updated"},"14":{"body":"See android/samples for examples of how to use Filament on Android. You must always first initialize Filament by calling Filament.init(). Rendering with Filament on Android is similar to rendering from native code (the APIs are largely the same across languages). You can render into a Surface by passing a Surface to the createSwapChain method. This allows you to render to a SurfaceTexture, a TextureView or a SurfaceView. To make things easier we provide an Android specific API called UiHelper in the package com.google.android.filament.android. All you need to do is set a render callback on the helper and attach your SurfaceView or TextureView to it. You are still responsible for creating the swap chain in the onNativeWindowChanged() callback.","breadcrumbs":"Introduction » Android","id":"14","title":"Android"},"140":{"body":"Install mdBook for your platform There is a script docs_src/build/install_mdbook.sh that might help. It is best practice to install the python dependencies in a virtual python environment. You can start such an environment by python3 -m venv venv\n. venv/bin/activate After that you may install deps and run the build script. selenium package for python python3 -m pip install selenium","breadcrumbs":"Technical Notes » Documentation » Prerequisites","id":"140","title":"Prerequisites"},"141":{"body":"We wrote a python script to gather and transform the different documents in the project tree into a single book. This script can be found in docs_src/build/run.py . In addition, docs_src/build/duplicates.json is used to describe the markdown files that are copied and transformed from the source tree. These copies are placed into docs_src/src_mdbook/src/dup. To collect the pages and generate the book, run the following cd docs_src\npython3 build/run.py","breadcrumbs":"Technical Notes » Documentation » Generate","id":"141","title":"Generate"},"142":{"body":"docs is the github-specfic directory for producing a web frontend (i.e. documentation) for a project. (To be completed)","breadcrumbs":"Technical Notes » Documentation » Copy to docs","id":"142","title":"Copy to docs"},"143":{"body":"We list the different document sources and how they are copied and processed into the collection of markdown files that are then processed with mdBook.","breadcrumbs":"Technical Notes » Documentation » Document sources","id":"143","title":"Document sources"},"144":{"body":"The github landing page for Filament displays an extensive introduction to Filament. It links to BUILDING.md and CONTRIBUTING.md, which are conventional pages for building or contributing to the project. We copy these pages from their respective locations in the project tree into docs_src/src_mdbook/src/dup. Moreover, to restore valid linkage between the pages, we need to perform a number of URL replacements in addition to the copy. These replacements are described in docs_src/build/duplicates.json .","breadcrumbs":"Technical Notes » Documentation » Introductory docs","id":"144","title":"Introductory docs"},"145":{"body":"The primary design of Filament as a physically-based renderer and details of its materials system are described in Filament.md.html and Materials.md.html, respectively. These two documents are written in markdeep . To embed them into our book, we Convert the markdeep into html Embed the html output in a markdown file Place the markdown file in docs_src/src_mdbook/src/main We describe step 1 in detail for the sake of record: Start a local-only server to serve the markdeep file (e.g. Filament.md.html) Start a selenium driver (essentially run chromium in headless mode) Visit the local page through the driver (i.e. open url http://localhost:xx/Filament.md.html?export) Parse out the exported output in the retrieved html (note that the output of the markdeep export is an html with the output captured in a tag). Replace css styling in the exported output as needed (so they don't interfere with the book's css. Replace resource urls to refer to locations relative to the mdbook structure. Any markdeep doc can be placed in docs_src/src_markdeep/ and they will be parsed to html and included in the book as above.","breadcrumbs":"Technical Notes » Documentation » Core concept docs","id":"145","title":"Core concept docs"},"146":{"body":"Filament depends on a number of libraries, which reside in the directory libs. These individual libaries often have README.md in their root to describe itself. We collect these descriptions into our book. In addition, client usage of Filament also requires using a set of binary tools, which are located in tools. Some of tools also have README.md as description. We also collect them into the book. The process for copying and processing these READMEs is outlined in Introductory docs .","breadcrumbs":"Technical Notes » Documentation » READMEs","id":"146","title":"READMEs"},"147":{"body":"These are technical documents that do not fit into a library, tool, or directory of the Filament source tree. We collect them into the docs_src/src_mdbook/src/notes directory. No additional processing is needed for these documents.","breadcrumbs":"Technical Notes » Documentation » Other technical notes","id":"147","title":"Other technical notes"},"148":{"body":"These are files that are not part of the mdbook generation, but should be included output in /docs to point to standalone pages or components (for example, the remote page for Android's gltf_viewer). These files are stored in docs_src/src_raw.","breadcrumbs":"Technical Notes » Documentation » Raw source files","id":"148","title":"Raw source files"},"149":{"body":"To add any documentation, first consider the type of the document you like to add. If it belongs to any of the above sources, then simply place the document in the appropriate place, add a link in SUMMARY.md, and perform the steps outlined in how-to create section . For example, if you are adding a general technical note, then you would Place the document (file with extension .md) in docs_src/src_mdbook/src/notes Add a link in docs_src/src_mdbook/src/SUMMARY.md Run the commands in the Generate section","breadcrumbs":"Technical Notes » Documentation » Adding more documents","id":"149","title":"Adding more documents"},"15":{"body":"Filament is supported on iOS 11.0 and above. See ios/samples for examples of using Filament on iOS. Filament on iOS is largely the same as native rendering with C++. A CAEAGLLayer or CAMetalLayer is passed to the createSwapChain method. Filament for iOS supports both Metal (preferred) and OpenGL ES.","breadcrumbs":"Introduction » iOS","id":"15","title":"iOS"},"150":{"body":"Helpful documents for specific debugging needs.","breadcrumbs":"Technical Notes » Debugging » Debugging","id":"150","title":"Debugging"},"151":{"body":"","breadcrumbs":"Technical Notes » Debugging » Metal » Debugging Metal","id":"151","title":"Debugging Metal"},"152":{"body":"To enable the Metal validation layers when running a sample through the command-line, set the following environment variable: export METAL_DEVICE_WRAPPER_TYPE=1 You should then see the following output when running a sample with the Metal backend: 2020-10-13 18:01:44.101 gltf_viewer[73303:4946828] Metal API Validation Enabled","breadcrumbs":"Technical Notes » Debugging » Metal » Enable Metal Validation","id":"152","title":"Enable Metal Validation"},"153":{"body":"To capture Metal frames from within gltf_viewer:","breadcrumbs":"Technical Notes » Debugging » Metal » Metal Frame Capture from gltf_viewer","id":"153","title":"Metal Frame Capture from gltf_viewer"},"154":{"body":"Create an Info.plist file in the same directory as gltf_viewer (cmake/samples). Set its contents to: \n\n\n MetalCaptureEnabled \n ","breadcrumbs":"Technical Notes » Debugging » Metal » 1. Create an Info.plist file","id":"154","title":"1. Create an Info.plist file"},"155":{"body":"Run gltf_viewer as normal, and hit the \"Capture frame\" button under the Debug menu. The captured frame will be saved to filament.gputrace in the current working directory. This file can then be opened with Xcode for inspection.","breadcrumbs":"Technical Notes » Debugging » Metal » 2. Capture a frame","id":"155","title":"2. Capture a frame"},"156":{"body":"","breadcrumbs":"Technical Notes » Debugging » Vulkan » Debugging Vulkan","id":"156","title":"Debugging Vulkan"},"157":{"body":"Simply install the LunarG SDK (it's fast and easy), then make sure you've got the following environment variables set up in your bashrc file. For example: export VULKAN_SDK='/path_to_home/VulkanSDK/1.3.216.0/x86_64'\nexport VK_LAYER_PATH=\"$VULKAN_SDK/etc/explicit_layer.d\"\nexport PATH=\"$VULKAN_SDK/bin:$PATH\" As long as you're running a debug build of Filament, you should now see extra debugging spew in your console if there are any errors or performance issues being caught by validation.","breadcrumbs":"Technical Notes » Debugging » Vulkan » Enable Validation Logs","id":"157","title":"Enable Validation Logs"},"158":{"body":"There are 4 repositories at play here: KhronosGroup/glslang KhronosGroup/spirv-tools KhronosGroup/spirv-cross KhronosGroup/SPIRV-Headers Typically, the bug is present either in spirv-tools or spirv-cross.","breadcrumbs":"Technical Notes » Debugging » SPIR-V » Investigating SPIRV-Cross / SPIRV-Tools issues","id":"158","title":"Investigating SPIRV-Cross / SPIRV-Tools issues"},"159":{"body":"The goal is to replicate the bug outside of Filament, so we're going to use command-line versions of the SPIRV tools.","breadcrumbs":"Technical Notes » Debugging » SPIR-V » Build and install command-line tools on PATH","id":"159","title":"Build and install command-line tools on PATH"},"16":{"body":"To get started you can use the textures and environment maps found respectively in third_party/textures and third_party/environments. These assets are under CC0 license. Please refer to their respective URL.txt files to know more about the original authors. Environments must be pre-processed using cmgen or using the libiblprefilter library.","breadcrumbs":"Introduction » Assets","id":"16","title":"Assets"},"160":{"body":"Note: Filament checks-out versions of these repositories inside third_party/; however, I've found it easiser to check out fresh copies separately so I can simply git pull to get the latest versions. Furthermore, Filament has modified some of these repositories locally for its own use case. Checking them out separately \"proves\" that the issue isn't Filament-specific. git clone git@github.com:KhronosGroup/SPIRV-Tools.git\ngit clone git@github.com:KhronosGroup/SPIRV-Cross.git\ngit clone git@github.com:KhronosGroup/glslang.git\ngit clone git@github.com:KhronosGroup/SPIRV-Headers.git SPIRV-Tools/external/SPIRV-Headers cd SPIRV-Tools/\nmkdir build && cmake . -G Ninja -B build\nninja -C build\ncd .. cd SPIRV-Cross/\nmkdir build && cmake . -G Ninja -B build\nninja -C build\ncd .. cd glslang/\nmkdir build && cmake . -G Ninja -B build\nninja -C build\ncd ..","breadcrumbs":"Technical Notes » Debugging » SPIR-V » Clone and build each repo","id":"160","title":"Clone and build each repo"},"161":{"body":"export PATH=`pwd`/SPIRV-Tools/build/tools:$PATH\nexport PATH=`pwd`/glslang/build/StandAlone:$PATH\nexport PATH=`pwd`/spirv-cross/build:$PATH Ensure the following tools now exist on your PATH: glslangValidator spiv-opt spirv-val spirv-cross","breadcrumbs":"Technical Notes » Debugging » SPIR-V » Add directories to PATH","id":"161","title":"Add directories to PATH"},"162":{"body":"First determine the Filament material and variant that causes the problem. What we want is the \"raw\" GLSL version of the shader, before any optimizations / cross-compilation happens. We can use the --save-raw-variants debug flag in matc to export each GLSL shader to a file. For example: matc --save-raw-variants --optimize-size --variant-filter fog,ssr,vsm,stereo \\ -a all -p all -o mymaterial.filamat mymaterial.mat Files will be named like mymaterial_0x05.frag or mymaterial_0x05.vert. Note that gltfio material \"templates\" first go through a build step. After building gltfio, the gltfio Filament materials are output to: out/cmake-release/libs/gltfio/*.mat One of these materials can be compiled with the following command: matc \\ -TCUSTOM_PARAMS=\"// no custom params\" \\ -TCUSTOM_VERTEX=\"// no custom vertex\" \\ -TCUSTOM_FRAGMENT=\"// no custom fragment\" \\ -TDOUBLESIDED=false \\ -TTRANSPARENCY=default \\ -TSHADINGMODEL=unlit \\ -TBLENDING=opaque \\ --platform mobile --api metal -o temp.filamat \\ unlit_opaque.mat","breadcrumbs":"Technical Notes » Debugging » SPIR-V » Isolate the problematic GLSL shader","id":"162","title":"Isolate the problematic GLSL shader"},"163":{"body":"The goal is to generate a .spv file that doesn't pass validation (through the spirv-val tool). Reproducing the error usually involves a few steps: Compile the raw GLSL shader into SPIR-V. glslangValidator -V -o unoptimized.spv in.frag Optimize for performance. spirv-opt -Oconfig=optimizations.cfg unoptimized.spv -o optimized.spv See optimizations.cfg for a template. This file should contain the same list of optimizations that Filament employs. This should match the same optimizations specified in GLSLPostProcessor, for example, GLSLPostProcessor::registerPerformancePasses or GLSLPostProcessor::registerSizePasses. For shaders targeting Metal, convert relaxed ops to half. spirv-opt \\ --convert-relaxed-to-half \\ --simplify-instructions \\ --redundancy-elimination \\ --eliminate-dead-code-aggressive \\ optimized.spv \\ -o half.spv Finally, validate the final SPIR-V. spirv-val half.spv Sometimes validation will still pass, but still generate invalid shaders after cross-compiling. In these cases, you'll need to cross compile to the target language and manually pick out errors in the generated shader. # for OpenGL\nspirv-cross optimized.spv > optimized.frag # for OpenGL ES\nspirv-cross --es optimized.spv > optimized.frag # for MSL\nspirv-cross --msl optimized.spv > optimized.metal To invoke Apple's compiler to compile MSL, you can run: xcrun -sdk macosx metal -c optimized.metal -o /dev/null","breadcrumbs":"Technical Notes » Debugging » SPIR-V » Reproduce the compilation error","id":"163","title":"Reproduce the compilation error"},"164":{"body":"These commands will run the preprocessor only on in.frag, and remove any empty lines. glslangValidator -E in.frag > preprocessed.frag\nsed '/^$/d' preprocessed.frag > preprocessed_small.frag You can also run clang-format on the preprocessed shader to make it easier to read: clang-format -i preprocessed_small.frag I always try to \"whittle down\" the shader to a smaller version that still reproduces the error. This might make it a bit easier on the Khronos team to diagnose the issue. I typically follow these steps in a loop until I'm satisfied: Delete an unnecessary part of the shader Run the steps to reproduce the error If the error still reproduces, repeat Otherwise, undo the change and make a smaller change There's also a Reducer tool that's part of SPIRV-Tools which can be used to automate these steps. I haven't experimented much with this, but it seems promising.","breadcrumbs":"Technical Notes » Debugging » SPIR-V » Clean up the shader for a bug report","id":"164","title":"Clean up the shader for a bug report"},"165":{"body":"See some example issues that have been filed in the past: https://github.com/KhronosGroup/SPIRV-Cross/issues/1935 https://github.com/KhronosGroup/SPIRV-Cross/issues/1088 https://github.com/KhronosGroup/SPIRV-Cross/issues/1026 https://github.com/KhronosGroup/SPIRV-Tools/issues/4452 https://github.com/KhronosGroup/SPIRV-Tools/issues/3406 https://github.com/KhronosGroup/SPIRV-Tools/issues/3099 https://github.com/KhronosGroup/SPIRV-Tools/issues/5044","breadcrumbs":"Technical Notes » Debugging » SPIR-V » Submit an Issue with the relevant Khronos repository","id":"165","title":"Submit an Issue with the relevant Khronos repository"},"166":{"body":"","breadcrumbs":"Technical Notes » Debugging » Running with ASAN and UBSAN » Running with ASAN/UBSAN","id":"166","title":"Running with ASAN/UBSAN"},"167":{"body":"When building though build.sh, pass the -b flag. This sets the cmake variable FILAMENT_ENABLE_ASAN_UBSAN=ON which eventually passes \"-fsanitize=address -fsanitize=undefined\" to all compile and link operations. It might be desirable to pair the -b with -y release. The -y flag indicates that targets in /tools will be built separately from the filament target, and the filament build depends on the /tools targets as prebuilt binaries. This separation reduces ASAN/UBSAN build time considerably. This option assumes that the user is trying to catch sanitization issues for filament and not the tools that are used to build filament. If building through CMake directly, or an IDE like CLion that doesn't use build.sh, instead pass -DFILAMENT_ENABLE_ASAN_UBSAN=ON to cmake in order to get the same result.","breadcrumbs":"Technical Notes » Debugging » Running with ASAN and UBSAN » Enabling","id":"167","title":"Enabling"},"168":{"body":"Memory leak detection isn't enabled by default on MacOS. There are two issues to address, first is using a version of clang that supports memory leak detection and second is enabling it at runtime. The version of clang distributed by Apple (with a version like \"Apple clang version 16.0.0\") doesn't currently support leak detection at all. Instead you will need to get or build a different LLVM, such as the one distributed through homebrew and get CMake to use that instead. Then during runtime you'll need to have the environment variable ASAN_OPTIONS include the option detect_leaks=1. Multiple ASAN_OPTIONS values are concatenated with :.","breadcrumbs":"Technical Notes » Debugging » Running with ASAN and UBSAN » Getting memory leak detection on Mac","id":"168","title":"Getting memory leak detection on Mac"},"169":{"body":"","breadcrumbs":"Technical Notes » Debugging » Running with ASAN and UBSAN » Getting memory leak output in CLion","id":"169","title":"Getting memory leak output in CLion"},"17":{"body":"Please read and follow the steps in CONTRIBUTING.md . Make sure you are familiar with the code style .","breadcrumbs":"Introduction » How to make contributions","id":"17","title":"How to make contributions"},"170":{"body":"Under Settings | Build, Execution, Deployment | Dynamic Analysis Tools | Sanitizers there is an ASAN Settings field that overrides whatever other ASAN_OPTIONS you might set elsewhere, so you must use that instead of setting it through your Run/Debug Configuration. To pass -DFILAMENT_ENABLE_ASAN_UBSAN=ON to CMake you'll want to create a new CMake Profile and pass it as a CMake argument.","breadcrumbs":"Technical Notes » Debugging » Running with ASAN and UBSAN » Setting variables","id":"170","title":"Setting variables"},"171":{"body":"CMake will consume ASAN output and display it through a separate \"Sanitizers\" tab. Unfortunately certain leak detection errors that interrupt the executable seem to not show up in this tab, but are still removed from the user-visible console output. If this is happening and you need to see the unfiltered console output you'll need to go to Settings | Build, Execution, Deployment | Dynamic Analysis Tools | Sanitizers and uncheck \"Use visual representation for Sanitizer's output\".","breadcrumbs":"Technical Notes » Debugging » Running with ASAN and UBSAN » Avoiding losing output","id":"171","title":"Avoiding losing output"},"172":{"body":"When running a binary under Instruments on macOS, you may run into the following issue when launching or attaching to an executable: Failed to gain authorization\nRecovery Suggestion: Target binary needs to be debuggable and signed with 'get-task-allow' This is a security precaution; the solution is to code sign the binary with the com.apple.security.get-task-allow entitlement. Create an entitlements.plist file with the following contents: \n\n\n com.apple.security.get-task-allow \n Run the following command: codesign -s - --entitlements entitlements.plist Replace with the name of the binary, for example: out/cmake-debug/samples/gltf_viewer. Afterwards, you should be able to successfully launch and attach to the executable using Instruments.","breadcrumbs":"Technical Notes » Debugging » Using Instruments on macOS » Using Instruments on macOS","id":"172","title":"Using Instruments on macOS"},"173":{"body":"Code coverage analysis helps visualize which parts of the backend are exercised by backend tests. This guide outlines the process for generating an HTML coverage report for Filament's backend on macOS.","breadcrumbs":"Technical Notes » Debugging » Code coverage analysis » Generating Backend Code Coverage","id":"173","title":"Generating Backend Code Coverage"},"174":{"body":"You'll need a recent version of Clang and its corresponding LLVM tools for code coverage. You can install these using Homebrew or MacPorts.","breadcrumbs":"Technical Notes » Debugging » Code coverage analysis » 1. Prerequisites: Install Clang and LLVM tools","id":"174","title":"1. Prerequisites: Install Clang and LLVM tools"},"175":{"body":"Install the llvm package: brew install llvm This typically installs the tools in a location like /usr/local/opt/llvm/bin. You may need to add this to your PATH environment variable.","breadcrumbs":"Technical Notes » Debugging » Code coverage analysis » Using Homebrew","id":"175","title":"Using Homebrew"},"176":{"body":"Install a specific version of Clang (e.g., version 18): sudo port install clang-18 MacPorts often adds version suffixes to the tool names (e.g., llvm-cov-mp-18).","breadcrumbs":"Technical Notes » Debugging » Code coverage analysis » Using MacPorts","id":"176","title":"Using MacPorts"},"177":{"body":"Ensure you can locate the following tools from your installation: clang and clang++ (The C/C++ compilers) llvm-profdata (For merging coverage data) llvm-cov (For generating reports) The rest of this guide assumes your tools are in your PATH. If not, you'll need to use the full path to each executable.","breadcrumbs":"Technical Notes » Debugging » Code coverage analysis » Required Tools","id":"177","title":"Required Tools"},"178":{"body":"Compile the backend_test_mac target with coverage instrumentation. This is done by setting the CC and CXX environment variables to point to your Clang compiler and using the -V flag in the build script. CC=clang CXX=clang++ ./build.sh -V -p desktop debug backend_test_mac If your Clang executables aren't in your PATH or have version suffixes, provide the full name or path (e.g., CC=/opt/local/bin/clang CXX=/opt/local/bin/clang++).","breadcrumbs":"Technical Notes » Debugging » Code coverage analysis » 2. Build Filament with Coverage Enabled","id":"178","title":"2. Build Filament with Coverage Enabled"},"179":{"body":"Running the test suite will generate the raw coverage data needed for the report. Navigate to the build output directory: cd out/cmake-debug/filament/backend Run the tests for a specific backend (e.g., Metal): ./backend_test_mac --api metal This command creates a default.profraw file in the current directory, which contains the raw execution profile data.","breadcrumbs":"Technical Notes » Debugging » Code coverage analysis » 3. Run the Backend Tests","id":"179","title":"3. Run the Backend Tests"},"18":{"body":"This repository not only contains the core Filament engine, but also its supporting libraries and tools. android: Android libraries and projects filamat-android: Filament material generation library (AAR) for Android filament-android: Filament library (AAR) for Android filament-utils-android: Extra utilities (KTX loader, math types, etc.) gltfio-android: Filament glTF loading library (AAR) for Android samples: Android-specific Filament samples art: Source for various artworks (logos, PDF manuals, etc.) assets: 3D assets to use with sample applications build: CMake build scripts docs: Documentation math: Mathematica notebooks used to explore BRDFs, equations, etc. filament: Filament rendering engine (minimal dependencies) backend: Rendering backends/drivers (Vulkan, Metal, OpenGL/ES) ide: Configuration files for IDEs (CLion, etc.) ios: Sample projects for iOS libs: Libraries bluegl: OpenGL bindings for macOS, Linux and Windows bluevk: Vulkan bindings for macOS, Linux, Windows and Android camutils: Camera manipulation utilities filabridge: Library shared by the Filament engine and host tools filaflat: Serialization/deserialization library used for materials filagui: Helper library for Dear ImGui filamat: Material generation library filamentapp: SDL2 skeleton to build sample apps filameshio: Tiny filamesh parsing library (see also tools/filamesh) geometry: Mesh-related utilities gltfio: Loader for glTF 2.0 ibl: IBL generation tools image: Image filtering and simple transforms imageio: Image file reading / writing, only intended for internal use matdbg: DebugServer for inspecting shaders at run-time (debug builds only) math: Math library mathio: Math types support for output streams utils: Utility library (threads, memory, data structures, etc.) viewer: glTF viewer library (requires gltfio) samples: Sample desktop applications shaders: Shaders used by filamat and matc third_party: External libraries and assets environments: Environment maps under CC0 license that can be used with cmgen models: Models under permissive licenses textures: Textures under CC0 license tools: Host tools cmgen: Image-based lighting asset generator filamesh: Mesh converter glslminifier: Minifies GLSL source code matc: Material compiler matedit: Material editor for compiled materials matinfo Displays information about materials compiled with matc mipgen Generates a series of miplevels from a source image normal-blending: Tool to blend normal maps resgen Aggregates binary blobs into embeddable resources roughness-prefilter: Pre-filters a roughness map from a normal map to reduce aliasing specular-color: Computes the specular color of conductors based on spectral data web: JavaScript bindings, documentation, and samples","breadcrumbs":"Introduction » Directory structure","id":"18","title":"Directory structure"},"180":{"body":"Finally, process the raw data and generate an HTML report. Merge the raw profile data into a single file using llvm-profdata. llvm-profdata merge -sparse default.profraw -o filament.profdata Remember to use the version-specific tool name if required (e.g., llvm-profdata-mp-18). Generate the HTML report using llvm-cov. This command creates a report for the entire backend_test_mac executable. llvm-cov show ./backend_test_mac \\ -instr-profile=filament.profdata \\ -format=html \\ -show-line-counts-or-regions > coverage.html To view coverage for a specific source file , add its path at the end of the command: llvm-cov show ./backend_test_mac \\ -instr-profile=filament.profdata \\ -format=html \\ -show-line-counts-or-regions \\ -- ../../../../filament/backend/src/metal/MetalDriver.mm > coverage.html Open the report in your browser: open coverage.html In the report, code paths that were not executed during the test run will be highlighted in red.","breadcrumbs":"Technical Notes » Debugging » Code coverage analysis » 4. Generate the Coverage Report","id":"180","title":"4. Generate the Coverage Report"},"181":{"body":"","breadcrumbs":"Technical Notes » Debugging » Performance analysis » Performance Analysis","id":"181","title":"Performance Analysis"},"182":{"body":"","breadcrumbs":"Technical Notes » Debugging » Performance analysis » Android","id":"182","title":"Android"},"183":{"body":"Download and install Android GPU Inspector (AGI). See https://developer.android.com/agi. Profiling Before profiling the application or analyzing the performance in a consistent way, ideally the GPU frequency on the target hardware should get locked . In order to do this, you need to do the following: Ensure your device is OEM unlocked. If your phone is carrier-locked, you may need to wait a period, such as 60 or 90 days after activation to be eligible for unlocking. Some phones don't support this at all. You will need to enable developer options (e.g. Settings > About Phone and tap the Build number 7 times). You need to go to Settings > System > Developer options and toggle on \"OEM unlocking\". Next, you need to unlock the phone. You will need to install Android SDK Platform Tools on you computer, enable \"USB debugging\" in your phone's Settings > System > Developer options. Connect the phone to the computer via a USB cable and run from the command line: adb reboot bootloader\n# once the phone is in bootloader mode, run the following to begin the unlocking\n# process:\nfastboot flashing unlock A warning will appear on your phone's screen. Use the volume buttons to navigate and the power button to select the \"Unlock the bootloader\" option. The phone will perform a factory data reset and reboot with an unlocked bootloader. You would need to flash an image to the phone with root permissions, such as a *-userdebug or *-eng build. One way to do this is with the Android Flash Tool . Connect the tool to your device and find a build to flash ending in -userdebug or -eng. Once you have that selected run Install build. Shell into your device as root and configure the gpu frequency to be locked, e.g.: adb shell\nsu\n# navigate to the system GPU directory. this varies on different phones. One phone might have\n# it at /sys/class/kgsl/kgsl-3d0 and another might be in something similar, maybe with \"mali\" instead\n# of \"kgsl\". At the time of writing this for the device at hand it was /sys/devices/platform/1f000000.mali\ncd /sys/devices/platform/1f000000.mali\n# get the current available GPU governors and frequencies.\n# note that some systems may have these at gpu_available_governors and gpu_available_frequencies, but\n# the system at the time of writing this had available_governors and available_frequences\ncat available_governors\ncat available_frequencies\n# depending on the governors, you may want to set it prioritize performance over other things like\n# battery. Some systems allow you to do this with something like (although, for the device used at the\n# time of writing this did not have an equivalent option):\necho performance > gpu_governor\n# finally, lock your frequency in, usually to something high like 897 MHz. Some systems may have you\n# pipe the value to gpu_min_freq and gpu_max_freq, but the system used at the time of writing this had:\necho 940000 > hint_min_freq\necho 940000 > hint_max_freq\n# you can typically verify the GPU is running at that frequency consistently by running something like\n# the following a few times over time, which should show the frequency you want to lock the device to:\ncat cur_freq You may need to re-apply the hint_min_freq just before starting the profiling trace and check before and after that the frequency remained at the value expected. Some systems may adjust the frequency on you, but you may want to ensure the frequency remains the same through the analysis. The GPU frequency settings should be undone after restarting the device, but after you have done your app profiling, you can revert the state of the device, such as the OS build image, back to the way you had it initially, as needed. Build a release build of Filament with the applicable backend(s) enabled (+ any special flags for enabling sys strace. Nothing special is needed for Vulkan or WebGPU aside from building a release build with no flags) (debug builds for this are useless) # the following command assumes you are in the root filament directory\n# and ANDROID_HOME is exported (and possibly also CC and CXX on linux as needed)\n#\n# NOTE: to build with WebGPU support you need to explicitly include the -W flag\n# (it doesn't get compiled in by default), e.g.:\n# ./build.sh -W -p android,desktop -i release\n#\n# Note that you can speed this up a bit (and reduce disk space usage) by limiting the target to just # the ABI you plan on testing with the -q flag, e.g. -q arm64-v8a. If you do this, you\n# will need to update the android/gradle.properties file to specify the ABI(s) you are targeting\n# with the com.google.android.filament.abis property.\n# Thus, a build command that would target BOTH Vulkan AND WebGPU AND only target the ARM64 ABI would look something\n# like:\n# ./build.sh -W -q arm64-v8a -p android,desktop -i release\n./build.sh -p android,desktop -i release Connect your Android device to your computer via a USB cord with USB debugging enabled and configure the system property to default to the desired backend, e.g. (to determine how these numbers map to the backends, see the enum class Backend definition in filament/filament/backend/include/backend/DriverEnums.h ) : # to set the backend to Vulkan: adb shell setprop debug.filament.backend 2\n# to set the backend to WebGPU:\nadb shell setprop debug.filament.backend 4\n# to view the current property:\nadb shell getprop debug.filament.backend Build and run a sample, e.g. sample-gltf-viewer, on your Android device ( Android Studio recommended) . Run AGI and follow instructions to profile the app/system with trace capture(s). See https://developer.android.com/agi/start for more details to get started. We typically only run \"Capture System Profiler trace\" (not necessarily \"Capture Frame Profiler trace\") When configuring the trace: For both the WebGPU and Vulkan backends configure the profiler for the Vulkan API (since WebGPU should be using Vulkan under the hood as well) Running for ~1 seconds should suffice Hit the \"Configure\" button in Trace objects, select \"Switch to advanced mode\" and add: data_sources { config { name: \"track_event\" track_event_config { disabled_categories: \"*\" enabled_categories: \"filament/filament\" enabled_categories: \"filament/jobsystem\" enabled_categories: \"filament/gltfio\" } }\n} One you open the trace, zoom into a series of frames to get a sense of generally how long they typically take (use W, S, A and D keys and mouse wheel for navigation) and find a representative one. We are most interested in the performance of the FEngine::loop thread, how long it takes, overlap in activities/processes/commands, reduction in queue submissions, etc. Similarly, we can view GPU timeline as it relates to that. We want to see overlapping shader invocations and non-interrupted fragment shader runs.","breadcrumbs":"Technical Notes » Debugging » Performance analysis » Prerequisites","id":"183","title":"Prerequisites"},"184":{"body":"FrameGraph is a framework within Filament for computing resources needed to render a frame. The framework enables declaring dependencies between resources. For example, when rendering shadows, we would need to first compute and store the shadow map into a texture resource, and then the later color pass would then sample that texture to attenuate the final output color. That creates a dependency on the shadow map from the color pass. Filament uses FrameGraph to declare that dependency.","breadcrumbs":"Technical Notes » Framegraph » FrameGraph","id":"184","title":"FrameGraph"},"185":{"body":"","breadcrumbs":"Technical Notes » Framegraph » Details","id":"185","title":"Details"},"186":{"body":"The core of this framework is a class that defines a dependency graph — that is, the class defines nodes and connections between nodes. This class makes assumptions about the types of its nodes. Like many other classes within Filament, this class is without virtual function declaration to avoid paying the cost of virtual calls. This class has additional functions to detect whether there is a cycle in the graph, and it is able to cull unreachable nodes.","breadcrumbs":"Technical Notes » Framegraph » Dependency Graph","id":"186","title":"Dependency Graph"},"187":{"body":"A frame graph consists of two types of nodes Resource This represents a generic resource such as a texture 90% of the time, this is a texture. Pass This represents a \"computation/rendering process\" It takes a set of resources It outputs a set of resources Edges can be created in the following three directions: Resource → Pass = A read Pass → Resource = A write Resource → Resource = A resource/subresource relationship.","breadcrumbs":"Technical Notes » Framegraph » FrameGraph","id":"187","title":"FrameGraph"},"188":{"body":"To better understand FrameGraph, we consider the following graphical representation of a real graph. In this graph, blue nodes denote \"Resources\" and orange nodes denote \"Passes.\" Sample frame graph In this graph, we see that the \"Color Pass\" takes as input the \"Shadowmap\", which has edges going into it, meaning that it's a texture array. The output of the \"Color Pass\" are \"viewRenderTarget\" and \"Depth Buffer.\" Note that there is an outgoing edge from \"viewRenderTarget\", where the color buffer will be used as input in the post-processing passes. But since \"Depth Buffer\" is not relevant to the rest of the rendering, it does not have an outgoing edge. Since the graph is guaranteed to be acyclic, we can produce a dependency-respecting ordering of the nodes by traversal of the graph (e.g. topological sort).","breadcrumbs":"Technical Notes » Framegraph » An example","id":"188","title":"An example"},"189":{"body":"We take a snippet of in production code to look through the details of building a graph. struct StructurePassData { FrameGraphId depth; FrameGraphId picking;\n}; ... // generate depth pass at the requested resolution\nauto& structurePass = fg.addPass(\"Structure Pass\", [&](FrameGraph::Builder& builder, auto& data) { bool const isES2 = mEngine.getDriverApi().getFeatureLevel() == FeatureLevel::FEATURE_LEVEL_0; data.depth = builder.createTexture(\"Structure Buffer\", { .width = width, .height = height, .levels = uint8_t(levelCount), .format = isES2 ? TextureFormat::DEPTH24 : TextureFormat::DEPTH32F }); // workaround: since we have levels, this implies SAMPLEABLE (because of the gl // backend, which implements non-sampleables with renderbuffers, which don't have levels). // (should the gl driver revert to textures, in that case?) data.depth = builder.write(data.depth, FrameGraphTexture::Usage::DEPTH_ATTACHMENT | FrameGraphTexture::Usage::SAMPLEABLE); if (config.picking) { data.picking = builder.createTexture(\"Picking Buffer\", { .width = width, .height = height, .format = isES2 ? TextureFormat::RGBA8 : TextureFormat::RG32F }); data.picking = builder.write(data.picking, FrameGraphTexture::Usage::COLOR_ATTACHMENT); } builder.declareRenderPass(\"Structure Target\", { .attachments = { .color = { data.picking }, .depth = data.depth }, .clearFlags = TargetBufferFlags::COLOR0 | TargetBufferFlags::DEPTH }); }, [=, renderPass = pass](FrameGraphResources const& resources, auto const&, DriverApi&) mutable { Variant structureVariant(Variant::DEPTH_VARIANT); structureVariant.setPicking(config.picking); auto out = resources.getRenderPassInfo(); renderPass.setRenderFlags(structureRenderFlags); renderPass.setVariant(structureVariant); renderPass.appendCommands(mEngine, RenderPass::CommandTypeFlags::SSAO); renderPass.sortCommands(mEngine); renderPass.execute(mEngine, resources.getPassName(), out.target, out.params); }\n); The addPass method creates a node and it take in two lambda functions as its parameter. The first lambda sets up the resources that will be used in the execution of the Pass. This lambda is executed immediately and synchronously when addPass is called. The second lambda is the actual execution of the pass; it is executed when the graph has been completed and is traversed.","breadcrumbs":"Technical Notes » Framegraph » Example code","id":"189","title":"Example code"},"19":{"body":"Please see LICENSE .","breadcrumbs":"Introduction » License","id":"19","title":"License"},"190":{"body":"In the above, we see through a graph and code what a frame graph looks like and how to build it. We provide here a more detailed description of what it does: Manages the lifetime of the resources Know how the resources are allocated, when it is used, and when it can be freed Calculates the usage bit of the texture resource The usage bit is used to indicate what the resources are used for: for example, will it be blitted to or sampled from? Calculates the load/store bits of the rendertargets within a renderpass. For example, if we are rendering into a texture, we would want to mark it with the bit \"keep\" as oppose to \"discard\".","breadcrumbs":"Technical Notes » Framegraph » What does it do?","id":"190","title":"What does it do?"},"191":{"body":"In a previous version of FrameGraph, there were only edges between Resource and Pass. For example, a Pass and Pass edge would not make logical sense. The following iteration, allowed for edges between two Resource nodes to indicate that one is a subresource of another (i.e. a layer in a mip-mapped texture). There are two extra features of FrameGraph that are important but has a lot subtlety, and, incidentally, their inclusion added great complexity to the implementation Importing/exporting resources outside of the graph In most cases, the graph and its resources are \"alive\" for only for a frame. For techniques like TAA (Temporal Anti-aliasing), we need to be able to import past output into the current FrameGraph Future Work For CPU only passes, explore multi-threading and re-ordering of the Pass nodes A graphical debugger for online debugging session in the spirit of matdbg. \"RenderGraph\" might be a more fitting name for this framework.","breadcrumbs":"Technical Notes » Framegraph » Additional details","id":"191","title":"Additional details"},"192":{"body":"Filament has a collection of tests that can be run locally. Many of them are used for in our Continuation Integration flow on github .","breadcrumbs":"Technical Notes » Tests » Tests","id":"192","title":"Tests"},"193":{"body":"These are tests that ensure the Filament backend is working properly on various operating systems and graphics backends. The majority of these tests generate images that are then compared against a known golden image.","breadcrumbs":"Technical Notes » Tests » backend » Backend Unit Tests","id":"193","title":"Backend Unit Tests"},"194":{"body":"Run with -a to run with a specific backend, such as -avulkan for vulkan or -ametal for metal.","breadcrumbs":"Technical Notes » Tests » backend » Running with a specific graphics library","id":"194","title":"Running with a specific graphics library"},"195":{"body":"The expected images are stored as PNG files in the expected_images subdirectory of the test source code. When cmake is run it will copy this directory to the build output creating images/expected_images inside the same directory as the unit test binary. The unit tests will then write their resulting images into images/actual_images in order to make the tests easier to debug. If an image comparison test fails, it writes a diff image to images/diff_images where each pixel of the diff is white (255,255,255) if the comparison for the corresponding pixel succeeds and black (0,0,0) of the comparison for the corresponding pixel fails.","breadcrumbs":"Technical Notes » Tests » backend » Image comparisons","id":"195","title":"Image comparisons"},"196":{"body":"Inside the unit test source code directory there is a python script called move_actual_images_to_expected.py. It will display the actual and expected images side-by-side and copy the actual image into the source tree's expected_images directory if the user approves the change. Directories The -r flag is required and should be the directory where the test binary is. If not running the script from the directory it's in, -s should be the source code's expected_images directory. Configuring compare/move behavior The -c flag has the tool display the actual and expected images side-by-side. By default it does this by opening both with the OS's default behavior. -p can be used to specify a different terminal program. The -m flag has the tool move the actual image to overwrite the expected image in the source tree. If the images are also being compared then the move will only happen if the user approves the change. After updating the expected images, cmake will need to be run again to copy them to the binary's directory. Also, currently some platforms can't load images to compare and so have the hash hardcoded into the test source code, so for now those need to be updated by running the test and copying the value manually. Picking which tests to compare The -x flag causes the tool to check the test_detail.xml file and only process the images who failed a comparison. --gtest_output=xml needs to be passed to the test binary to generate this file. The -t argument takes a list of images to compare, provided as the file name without the .png suffix.","breadcrumbs":"Technical Notes » Tests » backend » Python utility for updating golden images and comparing results","id":"196","title":"Python utility for updating golden images and comparing results"},"197":{"body":"If a test depends on a feature that is unsupported by the current environment, it will start with the SKIP_IF macro. This will cause the test to not be run.","breadcrumbs":"Technical Notes » Tests » backend » Unsupported tests","id":"197","title":"Unsupported tests"},"198":{"body":"This directory (/test/backend) contains scripts to run Filament's backend tests using a software rasterizer (Mesa). This is useful for running tests in a continuous integration environment where a GPU might not be available. The test.sh script will: Build Mesa if needed. Build the backend tests. Run the tests using the OpenGL and Vulkan backends with Mesa.","breadcrumbs":"Technical Notes » Tests » CI: backend » Backend Tests","id":"198","title":"Backend Tests"},"199":{"body":"The test.sh script accepts the following flags: --gtest_filter: Filters the tests that are run. This is passed directly to the underlying gtest executable. --backend: Specifies which backend to test. Can be opengl, vulkan, or a comma-separated list (e.g., opengl,vulkan). Defaults to both.","breadcrumbs":"Technical Notes » Tests » CI: backend » Flags","id":"199","title":"Flags"},"2":{"body":"Android projects can simply declare Filament libraries as Maven dependencies: repositories { // ... mavenCentral()\n} dependencies { implementation 'com.google.android.filament:filament-android:1.69.4'\n} Here are all the libraries available in the group com.google.android.filament: Artifact Description filament-android The Filament rendering engine itself. filament-android-debug Debug version of filament-android. gltfio-android A glTF 2.0 loader for Filament, depends on filament-android. filament-utils-android KTX loading, Kotlin math, and camera utilities, depends on gltfio-android. filamat-android A runtime material builder/compiler. This library is large but contains a full shader compiler/validator/optimizer and supports both OpenGL and Vulkan.","breadcrumbs":"Introduction » Android","id":"2","title":"Android"},"20":{"body":"This is not an officially supported Google product.","breadcrumbs":"Introduction » Disclaimer","id":"20","title":"Disclaimer"},"200":{"body":"This tool (/test/renderdiff) is a collections of scripts to run gltf_viewer and produce headless renderings. This is mainly useful for continuous integration where GPUs are generally not available on cloud machines. To perform software rasterization, these scripts are centered around Mesa 's software rasterizers, but nothing bars us from using another rasterizer like SwiftShader . Additionally, we should be able to use GPUs where available (though this is more of a future work). The script render.py contains the core logic for taking input parameters (such as the test description file) and then running gltf_viewer to produce the renderings. In the test directory is a list of test descriptions that are specified in json. Please see sample.json to glean the structure.","breadcrumbs":"Technical Notes » Tests » CI: renderdiff » Rendering Difference Test","id":"200","title":"Rendering Difference Test"},"201":{"body":"The renderdiff project uses python extensively. To install the dependencies for producing renderings, do the following step Set up a virtual environment (from the root directory) python3 -m venv venv\n. ./venv/bin/activate Install the rendering dependencies pip install -r test/renderdiff/src/rendering_requirements.txt Install the viewer depdencies pip install -r test/renderdiff/src/viewer_requirements.txt For the commands in the following section, do not exit the virtual environment. Once you've completed all your work, you can exit with deactivate","breadcrumbs":"Technical Notes » Tests » CI: renderdiff » Setting up python","id":"201","title":"Setting up python"},"202":{"body":"To run the same presbumit as test-renderdiff , you can do bash test/renderdiff/local_test.sh This script will generate the renderings based on the current state of your repo. Additionally, it will also compare the generated images with corresponding images in the golden repo. To just render without running the test, you could use the following script bash test/renderdiff/generate.sh","breadcrumbs":"Technical Notes » Tests » CI: renderdiff » Running the test locally","id":"202","title":"Running the test locally"},"203":{"body":"You can control the behavior of the test scripts with the following flags passed to local_test.sh: --test_filter=: Run a subset of tests. The filter supports wildcards (*) to match test names. --no_rebuild: Skip rebuilding the gltf_viewer executable. --num_threads=: Set the number of threads for rendering. If not set, the system's default is used. For example, to run all MSAA tests without rebuilding and using 8 threads: bash test/renderdiff/local_test.sh --test_filter='MSAA.*.*' --no_rebuild --num_threads=8","breadcrumbs":"Technical Notes » Tests » CI: renderdiff » Command-line Options","id":"203","title":"Command-line Options"},"204":{"body":"The golden images are stored in a github repository: https://github.com/google/filament-assets. Filament team members should have access to write to the repository. A typical flow for updating the goldens is to upload your changed images into branch of filament-assets. This branch is paired with a PR or commit on the filament repo. As an example, imagine I am working on a PR, and I've uploaded my change, which is in a branch called my-pr-branch, to filament. This PR requires updating the golden. We would do it in the following fashion","breadcrumbs":"Technical Notes » Tests » CI: renderdiff » Update the golden images","id":"204","title":"Update the golden images"},"205":{"body":"Make sure you've completed the steps in 'Setting up python' Run interactive mode in the update_golden.py script. python3 test/renderdiff/src/update_golden.py This will guide you through a series of steps to push the changes to a remote branch on filament-assets.","breadcrumbs":"Technical Notes » Tests » CI: renderdiff » Using a script to update the golden repo","id":"205","title":"Using a script to update the golden repo"},"206":{"body":"Check out the golden repo git clone git@github.com:google/filament-assets.git Create a branch on the golden repo cd filament-assets\ngit switch -c my-pr-branch-golden Copy the new images to their appropriate place in filament-assets Push the filament-assets working branch to remote git push origin my-pr-branch-golden In the commit message of your working branch on filament, add the following line RDIFF_BRANCH=my-pr-branch-golden Doing the above has multiple effects: The presubmit test test-renderdiff will test against the provided branch of the golden repo (i.e. my-pr-branch-golden). If the PR is merged, then there is another workflow that will merge my-pr-branch-golden to the main branch of the golden repo.","breadcrumbs":"Technical Notes » Tests » CI: renderdiff » Manually updating the golden repo","id":"206","title":"Manually updating the golden repo"},"207":{"body":"Alternatively, if you are confident in your changes and want the CI to handle the update for you, you can use the following tag in your commit message: In the commit message of your working branch on filament, add the following line: RDIFF_ACCEPT_NEW_GOLDENS This has the following effects: The presubmit test test-renderdiff will be bypassed (it will not perform rendering or comparison). When the PR is merged, the postsubmit CI will automatically: Build Filament and generate the new images. Upload them to a temporary branch in filament-assets. Merge that branch into main.","breadcrumbs":"Technical Notes » Tests » CI: renderdiff » Automated update via commit message","id":"207","title":"Automated update via commit message"},"208":{"body":"We provide a viewer for looking at the result of a test run. The viewer is a webapp that can be used by pointing your browser to a localhost port. If you input the viewer with a PR or a directory, it will parse the test result and show the results and the rendered and/or golden images. Viewer To run the viewer of a test output directory that has been generated locally, you would run the following python3 test/renderdiff/src/viewer.py --diff=[test output] where [test output] is a directory containing the compare_results.json of the test run. For example, it could be out/renderdiff/diffs/presubmit for the standard path to the presubmit test output. To see the results of a Pull Request initiated test run, you would do the following python3 test/renderdiff/src/viewer.py --pr_number=[PR #] --github_token=[github token] where [PR #] is the numeric ID of your pull request, and the [github token] is an acess token that you (as a github user) needs to generate ( reference ). To see the results of a specific run, you would do the following python3 test/renderdiff/src/viewer.py --run_number=[RUN #] --github_token=[github token] where [RUN #] is the numeric ID of the run. You can find the run number in the URL of the GitHub Actions page. For example, in the URL https://github.com/google/filament/actions/runs/18023632663/job/51286323708?pr=9264, the run number is 18023632663.","breadcrumbs":"Technical Notes » Tests » CI: renderdiff » Viewing test results","id":"208","title":"Viewing test results"},"209":{"body":"Collection of README.md from the /libs folder.","breadcrumbs":"Technical Notes » Libraries » Libraries","id":"209","title":"Libraries"},"21":{"body":"","breadcrumbs":"Introduction » Build » Building Filament","id":"21","title":"Building Filament"},"210":{"body":"So you want to call glClear()?","breadcrumbs":"Technical Notes » Libraries » bluegl » BlueGL Mechanics","id":"210","title":"BlueGL Mechanics"},"211":{"body":"This step is only required if updating or modifying BlueGL. These artifacts should already be checked into the Filament repository. From the libs/bluegl folder, run: ./bluegl-gen.py The bluegl-gen.py script generates a set of files: assembly (proxy) files: BlueGLCore*.S header files: include/BlueGLDefines.h and include/bluegl/BlueGL.h a private header:include/private_BlueGL.h","breadcrumbs":"Technical Notes » Libraries » bluegl » Step 0: Run bluegl-gen.py","id":"211","title":"Step 0: Run bluegl-gen.py"},"212":{"body":"#include This headers adds a bunch of defines: ...\n#define glClear bluegl_glClear\n...","breadcrumbs":"Technical Notes » Libraries » bluegl » Step 1: Include the BlueGL defines header:","id":"212","title":"Step 1: Include the BlueGL defines header:"},"213":{"body":"#include \n#include This also includes the GL headers, like for you.","breadcrumbs":"Technical Notes » Libraries » bluegl » Step 2: Include the BlueGL header after the defines header:","id":"213","title":"Step 2: Include the BlueGL header after the defines header:"},"214":{"body":"Internally, the BlueGL library maintains a list of function pointers: void* __blue_glCore_glClear; During bluegl::bind(), each function gets assigned to the appropriate symbol loaded from the OS-specific GL shared library via dlopen, dlsym, and equivalents.","breadcrumbs":"Technical Notes » Libraries » bluegl » Step 3: Call bluegl::bind()","id":"214","title":"Step 3: Call bluegl::bind()"},"215":{"body":"Because of the prior #define, you'll actually be calling bluegl_glClear(). This is a trampoline function, defined in the BlueGLCore*.S assembly file (the exact implementation varies slightly on each platform): .private_extern _bluegl_glClear\n_bluegl_glClear: mov ___blue_glCore_glClear@GOTPCREL(%rip), %r11 jmp *(%r11) The invokes the __blue_glCore_glClear function, which was previously assigned to the actual GL function.","breadcrumbs":"Technical Notes » Libraries » bluegl » Step 4: Call glClear()","id":"215","title":"Step 4: Call glClear()"},"216":{"body":"","breadcrumbs":"Technical Notes » Libraries » bluevk » bluevk","id":"216","title":"bluevk"},"217":{"body":"To update the Vulkan headers, perform the following steps. First, find the latest version of the Vulkan headers here: https://github.com/KhronosGroup/Vulkan-Headers/tags Replace v1.3.232 with the latest version of the headers in the following commands. cd libs/bluevk\ncurl -OL https://github.com/KhronosGroup/Vulkan-Headers/archive/refs/tags/v1.3.232.zip\nunzip v1.3.232.zip\nrsync -r Vulkan-Headers-1.3.232/include/vulkan/ include/vulkan --delete\nrsync -r Vulkan-Headers-1.3.232/include/vk_video/ include/vk_video --delete\nrm include/vulkan/*.hpp\nrm -r Vulkan-Headers-1.3.232 v1.3.232.zip","breadcrumbs":"Technical Notes » Libraries » bluevk » Updating Vulkan headers","id":"217","title":"Updating Vulkan headers"},"218":{"body":"Capabilities Setup for Desktop Setup for Android Debugger Usage Architecture Overview C++ Server JavaScript Client HTTP Requests Wish List","breadcrumbs":"Technical Notes » Libraries » fgviewer » fgviewer","id":"218","title":"fgviewer"},"219":{"body":"fgviewer is a library and web application for real-time visualization of the frame graph in Filament. It displays active passes and resource usage, providing insights into the rendering pipeline.","breadcrumbs":"Technical Notes » Libraries » fgviewer » Capabilities","id":"219","title":"Capabilities"},"22":{"body":"To build Filament, you must first install the following tools: CMake 3.22.1 (or more recent) clang 16.0 (or more recent) ninja 1.10 (or more recent) Additional dependencies may be required for your operating system. Please refer to the appropriate section below. To build Filament for Android you must also install the following: Android Studio Flamingo or more recent Android SDK Android NDK 25.1 or higher Java 17","breadcrumbs":"Introduction » Build » Prerequisites","id":"22","title":"Prerequisites"},"220":{"body":"When using the easy build script, include the -t argument. For example: ./build.sh -ft debug gltf_viewer The t enables a CMake option called FILAMENT_ENABLE_FGVIEWER and the f ensures that CMake gets re-run so that the option is honored. Next, set an environment variable as follows. In Windows, use set instead of export. export FILAMENT_FGVIEWER_PORT=8050 Next, launch any app that links against a debug build of a Filament and point your web browser to http://localhost:8050. Skip ahead to Debugger Usage .","breadcrumbs":"Technical Notes » Libraries » fgviewer » Setup for Desktop","id":"220","title":"Setup for Desktop"},"221":{"body":"Rebuild Filament for Android after enabling a CMake option called FILAMENT_ENABLE_FGVIEWER. Note that CMake is invoked from several places for Android (both gradle and our easy build script), so one pragmatic and reliable way of doing this is to simply hack CMakeLists.txt and filament-android/CMakeLists.txt by unconditionally setting FILAMENT_ENABLE_FGVIEWER to ON. After rebuilding Filament with the option enabled, ensure that internet permissions are enabled in your app by adding the following into your manifest as a child of the element. #include using namespace filamat; int main(int argc, char** argv)\n{ // Must be called before any materials can be built. MaterialBuilder::init(); MaterialBuilder builder; builder .name(\"My material\") .material(\"void material (inout MaterialInputs material) {\" \" prepareMaterial(material);\" \" material.baseColor.rgb = float3(1.0, 0.0, 0.0);\" \"}\") .shading(MaterialBuilder::Shading::LIT) .targetApi(MaterialBuilder::TargetApi::ALL) .platform(MaterialBuilder::Platform::ALL); Package package = builder.build(); if (package.isValid()) { std::cout << \"Success!\" << std::endl; } // Call when finished building all materials to release internal MaterialBuilder resources. MaterialBuilder::shutdown(); return 0;\n} The directory should look like: |-- README.md\n|-- bin\n|-- docs\n|-- include\n|-- lib\n|-- main.cpp We'll use a platform-specific Makefile to compile and link main.cpp with Filamat's libraries. Copy your platform's Makefile below into a Makefile inside the same directory.","breadcrumbs":"Technical Notes » Libraries » filamat » Linking against Filamat","id":"230","title":"Linking against Filamat"},"231":{"body":"FILAMENT_LIBS=-lfilamat -lfilabridge -lshaders -lutils -lsmol-v\nCC=clang++ main: main.o $(CC) -Llib/x86_64/ -stdlib=libc++ main.o $(FILAMENT_LIBS) -lpthread -ldl -o main main.o: main.cpp $(CC) -Iinclude/ -std=c++20 -stdlib=libc++ -pthread -c main.cpp clean: rm -f main main.o .PHONY: clean","breadcrumbs":"Technical Notes » Libraries » filamat » Linux","id":"231","title":"Linux"},"232":{"body":"FILAMENT_LIBS=-lfilamat -lfilabridge -lshaders -lutils -lsmol-v\nCC=clang++ main: main.o $(CC) -Llib/x86_64/ main.o $(FILAMENT_LIBS) -o main main.o: main.cpp $(CC) -Iinclude/ -std=c++20 -c main.cpp clean: rm -f main main.o .PHONY: clean","breadcrumbs":"Technical Notes » Libraries » filamat » macOS","id":"232","title":"macOS"},"233":{"body":"Note that the static libraries distributed for Windows include several variants: mt, md, mtd, mdd. These correspond to the run-time library flags /MT, /MD, /MTd, and /MDd, respectively. Here we use the mt variant. When building Filamat from source, the USE_STATIC_CRT CMake option can be used to change the run-time library version. FILAMENT_LIBS=lib/x86_64/mt/filamat.lib lib/x86_64/mt/filabridge.lib lib/x86_64/mt/shaders.lib \\ lib/x86_64/mt/utils.lib lib/x86_64/mt/smol-v.lib\nCC=clang-cl.exe main.exe: main.obj $(CC) main.obj $(FILAMENT_LIBS) gdi32.lib user32.lib opengl32.lib main.obj: main.cpp $(CC) /MT /Iinclude/ /std:c++20 /c main.cpp clean: del main.exe main.obj .PHONY: clean","breadcrumbs":"Technical Notes » Libraries » filamat » Windows","id":"233","title":"Windows"},"234":{"body":"You should be able to invoke make and run the executable successfully: $ make\n$ ./main\nSuccess! On Windows, you'll need to open up a Visual Studio Native Tools Command Prompt and invoke nmake instead of make.","breadcrumbs":"Technical Notes » Libraries » filamat » Compiling","id":"234","title":"Compiling"},"235":{"body":"For simplicity, this demo doesn't do anything useful with the built material package. To use the material with Filament, pass the material package's data into a Filament Material builder: Package package = builder.build(); filament::Material* myMaterial = Material::Builder() .package(package.getData(), package.getSize()) .build(*engine); Note that this will require linking against Filament's libraries in addition to Filamat's.","breadcrumbs":"Technical Notes » Libraries » filamat » Using the Material with Filament","id":"235","title":"Using the Material with Filament"},"236":{"body":"The filamat_lite library is interchangeable with filamat, with a few caveats: Material compilation is only supported for the OpenGL backend. No shader-level optimization is performed. GLSL correctness is not checked. In addition, filamat_lite only performs a simple text match to determine which properties on the MaterialInputs structure are set. The material input variable must also always be refered to by the name material. void anotherFunction(inout MaterialInputs m) { // Incorrect! The MaterialInputs is being referred to by the name \"m\". m.metallic = 0.0;\n} void aFunction(inout MaterialInputs material) { // Works, but only because the variable name \"material\" is used. material.reflectance = 0.5;\n} // The MaterialInputs variable must be named material.\nvoid material(inout MaterialInputs material) { prepareMaterial(material); // Good. material.roughness = materialParams.roughness; material.baseColor.rgb = vec3(1.0, 0.0, 1.0); aFunction(material); anotherFunction(material);\n}","breadcrumbs":"Technical Notes » Libraries » filamat » Filamat Lite","id":"236","title":"Filamat Lite"},"237":{"body":"gltfio is a loader library that consumes gltf or glb content and produces Filament objects. For usage details, see the docstring for AssetLoader. gltfio has two plug-in interfaces, TextureProvider and MaterialProvider. Filament ships with several ready-to-go implementations described below. MaterialProvider creates Filament materials in response to certain glTF requirements. UbershaderProvider loads pre-built materials. JitShaderProvider builds materials at run time using the filamat library. TextureProvider creates and populates Filament Texture objects. StbProvider uses the STB library to read PNG and JPEG files. Ktx2Provider uses the BasisU library to read KTX2 files.","breadcrumbs":"Technical Notes » Libraries » gltfio » gltfio","id":"237","title":"gltfio"},"238":{"body":"UbershaderProvider is a ready-to-go implementation of the MaterialProvider interface that should be used in applications that need fast startup times. There is no material compilation that occurs at run time, but the shaders might be relatively large and complex. At load time, the ubershader loader consumes an ubershader archive which is a precompiled set of materials bundled with formal descriptions of the glTF features that they support. The uberz command line tool consumes a list of .spec and .filamat files and produces a single .uberz file. For details on these two file formats, see the README in libs/uberz.","breadcrumbs":"Technical Notes » Libraries » gltfio » UbershaderProvider","id":"238","title":"UbershaderProvider"},"239":{"body":"This library can be used to generate the reflections texture used by filament's IndirectLight class. It is similar to the cmgen tool except that all computations are performed on the GPU and are therefore significantly faster. cmgen however offers more functionalities. IBL Prefilter is designed entirely as a client of filament, that is, it only uses filament public APIs.","breadcrumbs":"Technical Notes » Libraries » iblprefilter » IBL Prefilter","id":"239","title":"IBL Prefilter"},"24":{"body":"We recommend using CLion to develop for Filament. Simply open the root directory's CMakeLists.txt in CLion to obtain a usable project.","breadcrumbs":"Introduction » Build » IDE","id":"24","title":"IDE"},"240":{"body":"The library is called libfilament-iblprefilter.a and its public headers can be found in .","breadcrumbs":"Technical Notes » Libraries » iblprefilter » Library and headers","id":"240","title":"Library and headers"},"241":{"body":"Expect a total processing time of about 100ms to 300ms for a 5-levels 256 x 256 cubemap with 1024 samples.","breadcrumbs":"Technical Notes » Libraries » iblprefilter » Performance","id":"241","title":"Performance"},"242":{"body":"#include \n#include using namespace filament; Engine* engine = Engine::create(); // create an IBLPrefilterContext, keep it around if several cubemap will be processed.\nIBLPrefilterContext context(engine); // create the specular (reflections) filter. This operation generates the kernel, so it's important\n// to keep it around if it will be reused for several cubemaps.\nIBLPrefilterContext::SpecularFilter filter(context); // launch the heaver computation. Expect 100-100ms on the GPU.\nTexture* texture = filter(environment_cubemap); IndirectLight* indirectLight = IndirectLight::Builder() .reflections(texture) .build(engine);","breadcrumbs":"Technical Notes » Libraries » iblprefilter » Example","id":"242","title":"Example"},"243":{"body":"Capabilities Setup for Desktop Setup for Android Debugger Usage Architecture Overview C++ Server JavaScript Client HTTP Requests WebSocket Messages Wish List Screenshot Material Chunks","breadcrumbs":"Technical Notes » Libraries » matdbg » matdbg","id":"243","title":"matdbg"},"244":{"body":"matdbg is a library and web application that enables debugging and live-editing of Filament shaders. At the time of this writing, the following capabilities are supported. OpenGL: Editing GLSL Metal: Editing MSL Vulkan: Editing transpiled GLSL, displaying disassembled SPIR-V WebGPU: Editing WGSL Note that a given material can be built with multiple backends, even though only one backend is active in a particular session. For example, if the current app is using Vulkan, it is still possible to inspect the Metal shaders, as long as the material has been built with Metal support included.","breadcrumbs":"Technical Notes » Libraries » matdbg » Capabilities","id":"244","title":"Capabilities"},"245":{"body":"When using the easy build script, include the -d argument. For example: ./build.sh -fd debug gltf_viewer The d enables a CMake option called FILAMENT_ENABLE_MATDBG and the f ensures that CMake gets re-run so that the option is honored. Next, set an environment variable as follows. In Windows, use set instead of export. export FILAMENT_MATDBG_PORT=8080 Next, launch any app that links against a debug build of a Filament and point your web browser to http://localhost:8080. Skip ahead to Debugger Usage .","breadcrumbs":"Technical Notes » Libraries » matdbg » Setup for Desktop","id":"245","title":"Setup for Desktop"},"246":{"body":"Rebuild Filament for Android after enabling a CMake option called FILAMENT_ENABLE_MATDBG. Note that CMake is invoked from several places for Android (both gradle and our easy build script), so one pragmatic and reliable way of doing this is to simply hack CMakeLists.txt and filament-android/CMakeLists.txt by unconditionally setting FILAMENT_ENABLE_MATDBG to ON. After rebuilding Filament with the option enabled, ensure that internet permissions are enabled in your app by adding the following into your manifest as a child of the element.
