Feat: support spherical harmonic

packages/core/src/lighting/AmbientLight.ts

@@ -1,4 +1,4 @@
-import { Color } from "@oasis-engine/math";
+import { Color, SphericalHarmonics3 } from "@oasis-engine/math";
 import { Scene } from "../Scene";
 import { Shader } from "../shader";
 import { ShaderMacro } from "../shader/ShaderMacro";
@@ -10,11 +10,11 @@ import { DiffuseMode } from "./enums/DiffuseMode";
  * Ambient light.
  */
 export class AmbientLight {
-  private static _diffuseMacro: ShaderMacro = Shader.getMacroByName("O3_USE_DIFFUSE_ENV");
+  private static _shMacro: ShaderMacro = Shader.getMacroByName("O3_USE_SH");
   private static _specularMacro: ShaderMacro = Shader.getMacroByName("O3_USE_SPECULAR_ENV");
 
   private static _diffuseColorProperty: ShaderProperty = Shader.getPropertyByName("u_envMapLight.diffuse");
-  private static _diffuseTextureProperty: ShaderProperty = Shader.getPropertyByName("u_env_diffuseSampler");
+  private static _diffuseSHProperty: ShaderProperty = Shader.getPropertyByName("u_env_sh");
   private static _diffuseIntensityProperty: ShaderProperty = Shader.getPropertyByName("u_envMapLight.diffuseIntensity");
   private static _specularTextureProperty: ShaderProperty = Shader.getPropertyByName("u_env_specularSampler");
   private static _specularIntensityProperty: ShaderProperty = Shader.getPropertyByName(
@@ -23,11 +23,13 @@ export class AmbientLight {
   private static _mipLevelProperty: ShaderProperty = Shader.getPropertyByName("u_envMapLight.mipMapLevel");
 
   private _scene: Scene;
+  private _diffuseSphericalHarmonics: SphericalHarmonics3;
   private _diffuseSolidColor: Color = new Color(0.212, 0.227, 0.259);
   private _diffuseIntensity: number = 1.0;
   private _specularReflection: TextureCubeMap;
   private _specularIntensity: number = 1.0;
   private _diffuseMode: DiffuseMode = DiffuseMode.SolidColor;
+  private _shArray: Float32Array = new Float32Array(27);
 
   /**
    * Diffuse mode of ambient light.
@@ -38,10 +40,10 @@ export class AmbientLight {
 
   set diffuseMode(value: DiffuseMode) {
     this._diffuseMode = value;
-    if (value === DiffuseMode.Texture) {
-      this._scene.shaderData.enableMacro(AmbientLight._diffuseMacro);
+    if (value === DiffuseMode.SphericalHarmonics) {
+      this._scene.shaderData.enableMacro(AmbientLight._shMacro);
     } else {
-      this._scene.shaderData.disableMacro(AmbientLight._diffuseMacro);
+      this._scene.shaderData.disableMacro(AmbientLight._shMacro);
     }
   }
 
@@ -59,6 +61,23 @@ export class AmbientLight {
     }
   }
 
+  /**
+   * Diffuse reflection spherical harmonics 3.
+   * @remarks Effective when diffuse reflection mode is `DiffuseMode.SphericalHarmonics`.
+   */
+  get diffuseSphericalHarmonics(): SphericalHarmonics3 {
+    return this._diffuseSphericalHarmonics;
+  }
+
+  set diffuseSphericalHarmonics(value: SphericalHarmonics3) {
+    this._diffuseSphericalHarmonics = value;
+    const shaderData = this._scene.shaderData;
+
+    if (value) {
+      shaderData.setFloatArray(AmbientLight._diffuseSHProperty, value.convertRadianceToIrradiance(this._shArray));
+    }
+  }
+
   /**
    * Diffuse reflection intensity.
    */
@@ -112,20 +131,4 @@ export class AmbientLight {
     shaderData.setFloat(AmbientLight._diffuseIntensityProperty, this._diffuseIntensity);
     shaderData.setFloat(AmbientLight._specularIntensityProperty, this._specularIntensity);
   }
-
-  //-----------------------------deprecated---------------------------------------
-
-  private _diffuseTexture: TextureCubeMap;
-
-  /**
-   * Diffuse cube texture.
-   */
-  get diffuseTexture(): TextureCubeMap {
-    return this._diffuseTexture;
-  }
-
-  set diffuseTexture(value: TextureCubeMap) {
-    this._diffuseTexture = value;
-    this._scene.shaderData.setTexture(AmbientLight._diffuseTextureProperty, value);
-  }
 }

packages/core/src/lighting/enums/DiffuseMode.ts

@@ -4,7 +4,11 @@
 export enum DiffuseMode {
   /** Solid color mode. */
   SolidColor,
-  /** Texture cube mode. */
-  Texture
-  // SphericalHarmonics
+
+  /**
+   * SH mode
+   * @remarks
+   * Use SH3 to represent irradiance environment maps efficiently, allowing for interactive rendering of diffuse objects under distant illumination.
+   */
+  SphericalHarmonics
 }

packages/core/src/shaderlib/pbr/envmap_light_frag_define.glsl

@@ -9,8 +9,8 @@ struct EnvMapLight {
 
 uniform EnvMapLight u_envMapLight;
 
-#ifdef O3_USE_DIFFUSE_ENV
-    uniform samplerCube u_env_diffuseSampler;
+#ifdef O3_USE_SH
+    uniform vec3 u_env_sh[9];
 #endif
 
 #ifdef O3_USE_SPECULAR_ENV

packages/core/src/shaderlib/pbr/ibl_diffuse_frag.glsl

@@ -1,21 +1,9 @@
-#if defined(RE_IndirectDiffuse)
-
-    vec3 irradiance = vec3(0);
-
-    #ifdef O3_USE_DIFFUSE_ENV
-        vec3 lightMapIrradiance = textureCube(u_env_diffuseSampler, geometry.normal).rgb * u_envMapLight.diffuseIntensity;
-    #else
-        vec3 lightMapIrradiance = u_envMapLight.diffuse * u_envMapLight.diffuseIntensity;
-    #endif
-
-    #ifndef PHYSICALLY_CORRECT_LIGHTS
-        lightMapIrradiance *= PI;
-    #endif
-
-    irradiance += lightMapIrradiance;
-
-    RE_IndirectDiffuse( irradiance, geometry, material, reflectedLight );
-
+#ifdef O3_USE_SH
+   vec3 irradiance = getLightProbeIrradiance(u_env_sh, normal) * u_envMapLight.diffuseIntensity;
+#else
+   vec3 irradiance = u_envMapLight.diffuse * u_envMapLight.diffuseIntensity;
 #endif
 
+RE_IndirectDiffuse_Physical( irradiance, geometry, material, reflectedLight );
+
 

packages/core/src/shaderlib/pbr/ibl_diffuse_frag_define.glsl

@@ -3,3 +3,22 @@ void RE_IndirectDiffuse_Physical( const in vec3 irradiance, const in GeometricCo
     reflectedLight.indirectDiffuse += irradiance * BRDF_Diffuse_Lambert( material.diffuseColor );
 
 }
+
+
+// sh need be pre-scaled in CPU.
+vec3 getLightProbeIrradiance(vec3 sh[9], vec3 normal){
+      vec3 result = sh[0] +
+
+            sh[1] * (normal.y) +
+            sh[2] * (normal.z) +
+            sh[3] * (normal.x) +
+
+            sh[4] * (normal.y * normal.x) +
+            sh[5] * (normal.y * normal.z) +
+            sh[6] * (3.0 * normal.z * normal.z - 1.0) +
+            sh[7] * (normal.z * normal.x) +
+            sh[8] * (normal.x * normal.x - normal.y * normal.y);
+
+    return max(result, vec3(0.0));
+
+}

packages/math/src/Color.ts

@@ -55,25 +55,31 @@ export class Color implements IClone {
    * @param left - The first color to add
    * @param right - The second color to add
    * @param out - The sum of two colors
+   * @returns The added color
    */
-  static add(left: Color, right: Color, out: Color): void {
+  static add(left: Color, right: Color, out: Color): Color {
     out.r = left.r + right.r;
     out.g = left.g + right.g;
     out.b = left.b + right.b;
     out.a = left.a + right.a;
+
+    return out;
   }
 
   /**
    * Scale a color by the given value.
    * @param left - The color to scale
    * @param s - The amount by which to scale the color
    * @param out - The scaled color
+   * @returns The scaled color
    */
-  static scale(left: Color, s: number, out: Color): void {
+  static scale(left: Color, s: number, out: Color): Color {
     out.r = left.r * s;
     out.g = left.g * s;
     out.b = left.b * s;
     out.a = left.a * s;
+
+    return out;
   }
 
   /** The red component of the color, 0~1. */
@@ -118,7 +124,7 @@ export class Color implements IClone {
   /**
    * Determines the sum of this color and the specified color.
    * @param color - The specified color
-   * @returns This color
+   * @returns The added color
    */
   add(color: Color): Color {
     this.r += color.r;
@@ -132,7 +138,7 @@ export class Color implements IClone {
   /**
    * Scale this color by the given value.
    * @param s - The amount by which to scale the color
-   * @returns This color
+   * @returns The scaled color
    */
   scale(s: number): Color {
     this.r *= s;