CesiumJS源碼雜談之從光到?Uniform

更新時間：2023年04月17日 08:49:23 作者：嶺南燈火

這篇文章主要為大家介紹了CesiumJS源碼雜談之從光到Uniform的使用示例解析，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進(jìn)步，早日升職加薪

引言

之前對實時渲染（RealTimeRendering）的殿堂就十分向往，也有簡單了解過實時渲染中的光，無奈一直沒能系統(tǒng)學(xué)習(xí)。鑒于筆者已經(jīng)有一點(diǎn) CesiumJS 源碼基礎(chǔ)，所以就抽了一個周末跟了跟 CesiumJS 中的光照初步，在簡單的代碼追蹤后，發(fā)現(xiàn)想系統(tǒng)學(xué)習(xí)光照材質(zhì)，仍然是需要 RTR 知識的，這次僅僅了解了光在 CesiumJS 底層中是如何從 API 傳遞到 WebGL 著色器中去的，為之后深入研究打下基礎(chǔ)。

1. 有什么光

CesiumJS 支持的光的類型比較少，默認(rèn)場景光就一個太陽光：

// Scene 類構(gòu)造函數(shù)中
this.light = new SunLight();

從上面這代碼可知，CesiumJS 目前場景中只支持加入一個光源。

查閱 API，可得知除了 SubLight 之外，還有一個 DirectionalLight，即方向光。

官方示例代碼《Lighting》中就使用了方向光來模擬手電筒效果（flashLight）、月光效果（moonLight）、自定義光效果。

方向光比太陽光多出來一個必選的方向?qū)傩裕?/p>

const flashLight = new DirectionalLight({
  direction: scene.camera.directionWC // 每幀都不一樣，手電筒一直沿著相機(jī)視線照射
})

這個 direction 屬性是一個單位向量即可（模長是 1）。

說起來歸一化、規(guī)范化、標(biāo)準(zhǔn)化好像都能在網(wǎng)上找到與單位向量類似的意思，都是向量除以模長。

可見，CesiumJS 并沒有內(nèi)置點(diǎn)光源、聚光燈，需要自己寫著色過程（請參考 Primitive API 或 CustomShader API）。

2. 光如何轉(zhuǎn)換成 Uniform 以及何時被調(diào)用

既然 CesiumJS 支持的光只有一個，那么調(diào)查起來就簡單了。先給結(jié)論：

光是作為 Uniform 值傳遞到著色器中的。 先查清楚光是如何從 Scene.light 轉(zhuǎn)至 Renderer 中的 uniform 的。

2.1. 統(tǒng)一值狀態(tài)對象（UniformState）

在 Scene 渲染一幀的過程中，幾乎就在最頂部，Scene.js 模塊內(nèi)的函數(shù) render 就每幀更新著 Context 對象的 uniformState 屬性：

function render(scene) {
  const frameState = scene._frameState;
  const context = scene.context;
  const us = context.uniformState;
  // ...
  us.update(frameState);
  // ...
}

這個 uniformState 對象就是 CesiumJS 絕大多數(shù)統(tǒng)一值（Uniform）的封裝集合，它的更新方法就會更新來自幀狀態(tài)對象（FrameState）的光參數(shù)：

UniformState.prototype.update = function (frameState) {
  // ...
  const light = defaultValue(frameState.light, defaultLight);
  if (light instanceof SunLight) { /**/ }
  else { /**/ }
  const lightColor = light.color;
  // 計算 HDR 光到 this._lightColor 上
  // ...
}

那么，這個掛在 Context 上的 uniformState 對象包含的光狀態(tài)信息，是什么時候被使用的呢？下一小節(jié) 2.2 就會介紹。

2.2. 上下文（Context）執(zhí)行 DrawCommand

在 Scene 的更新過程中，最后 DrawCommand 對象被 Context 對象執(zhí)行：

function continueDraw(context, drawCommand, shaderProgram, uniformMap) {
  // ...
  shaderProgram._setUniforms(
    uniformMap,
    context._us,
    context.validateShaderProgram
  )
  // ...
}
Context.prototype.draw = function (/* ... */) {
  // ...
  shaderProgram = defaultValue(shaderProgram, drawCommand._shaderProgram);
  uniformMap = defaultValue(uniformMap, drawCommand._uniformMap);
  beginDraw(this, framebuffer, passState, shaderProgram, renderState);
  continueDraw(this, drawCommand, shaderProgram, uniformMap);
}

就在 continueDraw 函數(shù)中，調(diào)用了 ShaderProgram 對象的 _setUniforms 方法，所有 Uniform 值在此將傳入 WebGL 狀態(tài)機(jī)中。

ShaderProgram.prototype._setUniforms = function (/**/) {
  // ...
  const uniforms = this._uniforms;
  len = uniforms.length;
  for (i = 0; i &lt; len; ++i) {
    uniforms[i].set();
  }
  // ...
}

而這每一個 uniforms[i]，都是一個沒有公開在 API 文檔中的私有類，也就是接下來 2.3 小節(jié)中要介紹的 WebGL Uniform 值封裝對象。

2.3. 對 WebGL Uniform 值的封裝

進(jìn)入 createUniforms.js 模塊：

// createUniforms.js
UniformFloat.prototype.set = function () { /* ... */ }
UniformFloatVec2.prototype.set = function () { /* ... */ }
UniformFloatVec3.prototype.set = function () { /* ... */ }
UniformFloatVec4.prototype.set = function () { /* ... */ }
UniformSampler.prototype.set = function () { /* ... */ }
UniformInt.prototype.set = function () { /* ... */ }
UniformIntVec2.prototype.set = function () { /* ... */ }
UniformIntVec3.prototype.set = function () { /* ... */ }
UniformIntVec4.prototype.set = function () { /* ... */ }
UniformMat2.prototype.set = function () { /* ... */ }
UniformMat3.prototype.set = function () { /* ... */ }
UniformMat4.prototype.set = function () { /* ... */ }

可以說把 WebGL uniform 的類型都封裝了一個私有類。

以表示光方向的 UniformFloatVec3 類為例，看看它的 WebGL 調(diào)用：

function UniformFloatVec3(gl, activeUniform, uniformName, location) {
  this.name = uniformName
  this.value = undefined
  this._value = undefined
  this._gl = gl
  this._location = location
}
UniformFloatVec3.prototype.set = function () {
  const v = this.value
  if (defined(v.red)) {
    if (!Color.equals(v, this._value)) {
      this._value = Color.clone(v, this._value)
      this._gl.uniform3f(this._location, v.red, v.green, v.blue)
    }
  } else if (defined(v.x)) {
    if (!Cartesian3.equals(v, this._value)) {
      this._value = Cartesian3.clone(v, this._value)
      this._gl.uniform3f(this._location, v.x, v.y, v.z)
    }
  } else {
    throw new DeveloperError(`Invalid vec3 value for uniform "${this.name}".`);
  }
}

2.4. 自動統(tǒng)一值（AutomaticUniforms）

在 2.2 小節(jié)中有一個細(xì)節(jié)沒有詳細(xì)說明，即 ShaderProgram 的 _setUniforms 方法中為什么可以直接調(diào)用每一個 uniforms[i] 的 set()？

回顧一下：

Scene.js 的 render 函數(shù)內(nèi)，光的信息被 us.update(frameState) 更新至 UniformState 對象中；
ShaderProgram 的 _setUniforms 方法，調(diào)用 uniforms[i].set() 方法，更新每一個私有 Uniform 對象上的值到 WebGL 狀態(tài)機(jī)中

是不是缺少了點(diǎn)什么？

是的，UniformState 的值是如何賦予給 uniforms[i] 的？

這就不得不提及 ShaderProgram.js 模塊中為當(dāng)前著色器對象的 Uniform 分類過程了，查找模塊中的 reinitialize 函數(shù)：

function reinitialize(shader) {
  // ...
  const uniforms = findUniforms(gl, program)
  const partitionedUniforms = partitionUniforms(
    shader,
    uniforms.uniformsByName
  )
  // ...
  shader._uniformsByName = uniforms.uniformsByName
  shader._uniforms = uniforms.uniform
  shader._automaticUniforms = partitionedUniforms.automaticUniforms
  shader._manualUniforms = partitionedUniforms.manualUniforms
  // ...
}

它把著色器對象上的 Uniform 全部找了出來，并分類為：

_uniformsByName - 一個字典對象，鍵名是著色器中 uniform 的變量名，值是 Uniform 的封裝對象，例如 UniformFloatVec3 等

_uniforms - 一個數(shù)組，每個元素都是 Uniform 的封裝對象，例如 UniformFloatVec3 等，若同名，則與 _uniformsByName 中的值是同一個引用

_manualUniforms - 一個數(shù)組，每個元素都是 Uniform 的封裝對象，例如 UniformFloatVec3 等，若同名，則與 _uniformsByName 中的值是同一個引用

_automaticUniforms - 一個數(shù)組，每個元素是一個 object 對象，表示要 CesiumJS 自動更新的 Uniform 的映射關(guān)聯(lián)關(guān)系

舉例，_automaticUniforms[i] 用 TypeScript 來描述，是這么一個對象：

type AutomaticUniformElement = {
  automaticUniform: AutomaticUniform
  uniform: UniformFloatVec3
}

而這個 _automaticUniforms 就擁有自動更新 CesiumJS 內(nèi)部狀態(tài)的 Uniform 值的功能，例如我們所需的光狀態(tài)信息。

來看 AutomaticUniforms.js 模塊的默認(rèn)導(dǎo)出對象：

// AutomaticUniforms.js
const AutomaticUniforms = {
  // ...
  czm_sunDirectionEC: new AutomaticUniform({ /**/ }),
  czm_sunDirectionWC: new AutomaticUniform({ /**/ }),
  czm_lightDirectionEC: new AutomaticUniform({ /**/ }),
  czm_lightDirectionWC: new AutomaticUniform({ /**/ }),
  czm_lightColor: new AutomaticUniform({
    size: 1,
    datatype: WebGLConstants.FLOAT_VEC3,
    getValue: function (uniformState) {
      return uniformState.lightColor;
    },
  }),
  czm_lightColorHdr:  new AutomaticUniform({ /**/ }),
  // ...
}
export default AutomaticUniforms

所以，在 ShaderProgram.prototype._setUniforms 執(zhí)行的時候，其實是對自動統(tǒng)一值有一個賦值的過程，然后才到各個 uniforms[i] 的 set() 過程：

ShaderProgram.prototype._setUniforms = function (
  uniformMap,
  uniformState,
  validate
) {
  let len;
  let i;
  // ...
  const automaticUniforms = this._automaticUniforms;
  len = automaticUniforms.length;
  for (i = 0; i < len; ++i) {
    const au = automaticUniforms[i];
    au.uniform.value = au.automaticUniform.getValue(uniformState);
  }
  // 譯者注：au.uniform 實際上也在 this._uniforms 中
  // 是同一個引用在不同的位置，所以上面調(diào)用 au.automaticUniform.getValue 
  // 之后，下面 uniforms[i].set() 就會使用的是 “自動更新” 的 uniform 值
  const uniforms = this._uniforms;
  len = uniforms.length;
  for (i = 0; i < len; ++i) {
    uniforms[i].set();
  }
  // ...
}

也許這個過程有些亂七八糟，那就再簡單梳理一次：

Scene 的 render 過程中，更新了 uniformState
Context 執(zhí)行 DrawCommand 過程中，ShaderProgram 的 _setUniforms 執(zhí)行所有 uniforms 的 WebGL 設(shè)置，這其中就會對 CesiumJS 內(nèi)部不需要手動更新的 Uniform 狀態(tài)信息進(jìn)行自動刷新
而在 ShaderProgram 綁定前，早就會把這個著色器中的 uniform 進(jìn)行分組，一組是常規(guī)的 uniform 值，另一組則是需要根據(jù) AutomaticUniform（自動統(tǒng)一值）更新的 uniform 值

說到底，光狀態(tài)信息也不過是一種 Uniform，在最原始的 WebGL 學(xué)習(xí)教材中也是如此，只不過 CesiumJS 是一個更復(fù)雜的狀態(tài)機(jī)器，需要更多邏輯劃分就是了。

3. 在著色器中如何使用

上面介紹完光的類型、在 CesiumJS 源碼中如何轉(zhuǎn)化成 Uniform 并刷入 WebGL，那么這一節(jié)就簡單看看光的狀態(tài) Uniform 在著色器代碼中都有哪些使用之處。

3.1. 點(diǎn)云

PointCloud.js 使用了 czm_lightColor。

找到 createShaders 函數(shù)下面這個分支：

// Version 1.104
function createShaders(pointCloud, frameState, style) {
  // ...
  if (usesNormals &amp;&amp; normalShading) {
    vs +=
      "    float diffuseStrength = czm_getLambertDiffuse(czm_lightDirectionEC, normalEC); \n" +
      "    diffuseStrength = max(diffuseStrength, 0.4); \n" + // Apply some ambient lighting
      "    color.xyz *= diffuseStrength * czm_lightColor; \n";
  }
  // ...
}

顯然，這段代碼在拼湊頂點(diǎn)著色器代碼，在 1.104 版本官方并沒有改變這種拼接著色器代碼的模式。

著色代碼的含義也很簡單，將漫反射強(qiáng)度值乘上 czm_lightColor，把結(jié)果交給 color 的 xyz 分量。漫反射強(qiáng)度在這里限制了最大值 0.4。

漫反射強(qiáng)度來自內(nèi)置 GLSL 函數(shù) czm_getLambertDiffuse（參考 packages/engine/Source/Shaders/Builtin/Functions/getLambertDiffuse.glsl）

3.2. 馮氏著色法

Primitive API 材質(zhì)對象的默認(rèn)著色方法是 馮氏著色法（Phong），這個在 LearnOpenGL 網(wǎng)站上有詳細(xì)介紹。

調(diào)用鏈：

MaterialAppearance.js
  ┗ TexturedMaterialAppearanceFS.js ← TexturedMaterialAppearanceFS.glsl
    ┗ phong.glsl → vec4 czm_phong()

除了 TexturedMaterialAppearanceFS 外，MaterialAppearance.js 還用了 BasicMaterialAppearanceFS、AllMaterialAppearanceFS 兩個片元著色器，這倆也用到了 czm_phong 函數(shù)。

看看 czm_phong 函數(shù)本體：

// phong.glsl
vec4 czm_phong(vec3 toEye, czm_material material, vec3 lightDirectionEC)
{
    // Diffuse from directional light sources at eye (for top-down)
    float diffuse = czm_private_getLambertDiffuseOfMaterial(vec3(0.0, 0.0, 1.0), material);
    if (czm_sceneMode == czm_sceneMode3D) {
        // (and horizon views in 3D)
        diffuse += czm_private_getLambertDiffuseOfMaterial(vec3(0.0, 1.0, 0.0), material);
    }
    float specular = czm_private_getSpecularOfMaterial(lightDirectionEC, toEye, material);
    // Temporary workaround for adding ambient.
    vec3 materialDiffuse = material.diffuse * 0.5;
    vec3 ambient = materialDiffuse;
    vec3 color = ambient + material.emission;
    color += materialDiffuse * diffuse * czm_lightColor;
    color += material.specular * specular * czm_lightColor;
    return vec4(color, material.alpha);
}

函數(shù)內(nèi)前面的計算步驟是獲取漫反射、高光值，走的是輔助函數(shù)，在這個文件內(nèi)也能看到。

最后燈光 czm_lightColor 和材質(zhì)的漫反射、蘭伯特漫反射、材質(zhì)輝光等因子一起相乘累加，得到最終的顏色值。

除了 phong.glsl 外，參與半透明計算的 czm_translucentPhong 函數(shù)（在 translucentPhong.glsl 文件中）在 OIT.js 模塊中用于替換 czm_phong 函數(shù)。

3.3. 地球

在 Globe.js 中使用的 GlobeFS 片元著色器代碼中使用到了 czm_lightColor，主要是 main 函數(shù)中：

void main() {
// ...
#ifdef ENABLE_VERTEX_LIGHTING
    float diffuseIntensity = clamp(czm_getLambertDiffuse(czm_lightDirectionEC, normalize(v_normalEC)) * u_lambertDiffuseMultiplier + u_vertexShadowDarkness, 0.0, 1.0);
    vec4 finalColor = vec4(color.rgb * czm_lightColor * diffuseIntensity, color.a);
#elif defined(ENABLE_DAYNIGHT_SHADING)
    float diffuseIntensity = clamp(czm_getLambertDiffuse(czm_lightDirectionEC, normalEC) * 5.0 + 0.3, 0.0, 1.0);
    diffuseIntensity = mix(1.0, diffuseIntensity, fade);
    vec4 finalColor = vec4(color.rgb * czm_lightColor * diffuseIntensity, color.a);
#else
    vec4 finalColor = color;
#endif
// ...
}

同樣是先獲取蘭伯特漫反射值（使用 clamp 函數(shù)釘死在 [0, 1] 區(qū)間內(nèi)），然后將顏色、czm_lightColor、漫反射值和透明度一起計算出 finalColor，把最終顏色值交給下一步計算。

這里區(qū)分了兩個宏分支，受 TerrainProvider 影響，有興趣可以追一下 GlobeSurfaceTileProvider.js 模塊中 addDrawCommandsForTile 函數(shù)中 hasVertexNormals 參數(shù)的獲取。

3.4. 模型架構(gòu)中的光著色階段

在 1.97 大改的 Model API 中，PBR 著色法使用了 czm_lightColorHdr 變量。czm_lightColorHdr 也是自動統(tǒng)一值（AutomaticUniforms）的一個。

在 Model 的更新過程中，有一個 buildDrawCommands 的步驟，其中有一個函數(shù) ModelRuntimePrimitive.prototype.configurePipeline 會增減 ModelRuntimePrimitive 上的著色階段：

ModelRuntimePrimitive.prototype.configurePipeline = function (frameState) {
  // ...
  pipelineStages.push(LightingPipelineStage);
  // ...
}

上面是其中一個階段 —— LightingPipelineStage，最后在 ModelSceneGraph.prototype.buildDrawCommands 方法內(nèi)會調(diào)用每一個 stage 的 process 方法，調(diào)用 shaderBuilder 構(gòu)建出著色器對象所需的材料，進(jìn)而構(gòu)建出著色器對象。過程比較復(fù)雜，直接看其中 LightingPipelineStage.glsl 提供的階段函數(shù)：

void lightingStage(inout czm_modelMaterial material, ProcessedAttributes attributes)
{
    // Even though the lighting will only set the diffuse color,
    // pass all other properties so further stages have access to them.
    vec3 color = vec3(0.0);
    #ifdef LIGHTING_PBR
    color = computePbrLighting(material, attributes);
    #else // unlit
    color = material.diffuse;
    #endif
    #ifdef HAS_POINT_CLOUD_COLOR_STYLE
    // The colors resulting from point cloud styles are adjusted differently.
    color = czm_gammaCorrect(color);
    #elif !defined(HDR)
    // If HDR is not enabled, the frame buffer stores sRGB colors rather than
    // linear colors so the linear value must be converted.
    color = czm_linearToSrgb(color);
    #endif
    material.diffuse = color;
}

進(jìn)入 computePbrLighting 函數(shù)（同一個文件內(nèi)）：

#ifdef LIGHTING_PBR
vec3 computePbrLighting(czm_modelMaterial inputMaterial, ProcessedAttributes attributes)
{
    // ...
    #ifdef USE_CUSTOM_LIGHT_COLOR
    vec3 lightColorHdr = model_lightColorHdr;
    #else
    vec3 lightColorHdr = czm_lightColorHdr;
    #endif
    vec3 color = inputMaterial.diffuse;
    #ifdef HAS_NORMALS
    color = czm_pbrLighting(
        attributes.positionEC,
        inputMaterial.normalEC,
        czm_lightDirectionEC,
        lightColorHdr,
        pbrParameters
    );
        #ifdef USE_IBL_LIGHTING
        color += imageBasedLightingStage(
            attributes.positionEC,
            inputMaterial.normalEC,
            czm_lightDirectionEC,
            lightColorHdr,
            pbrParameters
        );
        #endif
    #endif
   // ...
}
#endif

故，存在 USE_CUSTOM_LIGHT_COLOR 宏時才會使用 czm_lightColorHdr 變量作為燈光顏色，參與函數(shù) czm_pbrLighting 計算出顏色值。