关于cesium:CesiumJS-源码杂谈-从光到-Uniform

10次阅读

共计 10899 个字符，预计需要花费 28 分钟才能阅读完成。

之前对实时渲染（RealTimeRendering）的殿堂就非常向往，也有简略理解过实时渲染中的光，无奈始终没能零碎学习。鉴于笔者曾经有一点 CesiumJS 源码根底，所以就抽了一个周末跟了跟 CesiumJS 中的光照初步，在简略的代码追踪后，发现想零碎学习光照材质，依然是须要 RTR 常识的，这次仅仅理解了光在 CesiumJS 底层中是如何从 API 传递到 WebGL 着色器中去的，为之后深入研究打下基础。

1. 有什么光

CesiumJS 反对的光的类型比拟少，默认场景光就一个太阳光：

// Scene 类构造函数中

this.light = new SunLight();

从下面这代码可知，CesiumJS 目前场景中只反对退出一个光源。

查阅 API，可得悉除了 SubLight 之外，还有一个 DirectionalLight，即方向光。

官网示例代码《Lighting》中就应用了方向光来模仿手电筒成果（flashLight）、月光成果（moonLight）、自定义光成果。

方向光比太阳光多进去一个必选的方向属性：

const flashLight = new DirectionalLight({direction: scene.camera.directionWC // 每帧都不一样，手电筒始终沿着相机眼帘照耀})

这个 direction 属性是一个单位向量即可（模长是 1）。

说起来归一化、规范化、标准化如同都能在网上找到与单位向量相似的意思，都是向量除以模长。

可见，CesiumJS 并没有内置点光源、聚光灯，须要本人写着色过程（请参考 Primitive API 或 CustomShader API）。

2. 光如何转换成 Uniform 以及何时被调用

既然 CesiumJS 反对的光只有一个，那么考察起来就简略了。先给论断：

光是作为 Uniform 值传递到着色器中的。 先查分明光是如何从 Scene.light 转至 Renderer 中的 uniform 的。

2.1. 对立值状态对象（UniformState）

在 Scene 渲染一帧的过程中，简直就在最顶部，Scene.js 模块内的函数 render 就每帧更新着 Context 对象的 uniformState 属性：

function render(scene) {
  const frameState = scene._frameState;

  const context = scene.context;
  const us = context.uniformState;

  // ...

  us.update(frameState);

  // ...
}

这个 uniformState 对象就是 CesiumJS 绝大多数对立值（Uniform）的封装汇合，它的更新办法就会更新来自帧状态对象（FrameState）的光参数：

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 对象蕴含的光状态信息，是什么时候被应用的呢？下一大节 2.2 就会介绍。

2.2. 上下文（Context）执行 DrawCommand

在 Scene 的更新过程中，最初 DrawCommand 对象被 Context 对象执行：

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 函数中，调用了 ShaderProgram 对象的 _setUniforms 办法，所有 Uniform 值在此将传入 WebGL 状态机中。

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

而这每一个 uniforms[i]，都是一个没有公开在 API 文档中的公有类，也就是接下来 2.3 大节中要介绍的 WebGL Uniform 值封装对象。

2.3. 对 WebGL Uniform 值的封装

进入 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 调用：

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. 主动对立值（AutomaticUniforms）

在 2.2 大节中有一个细节没有具体阐明，即 ShaderProgram 的 _setUniforms 办法中为什么能够间接调用每一个 uniforms[i] 的 set()？

回顾一下：

  • Scene.js 的 render 函数内，光的信息被 us.update(frameState) 更新至 UniformState 对象中；
  • ShaderProgram 的 _setUniforms 办法，调用 uniforms[i].set() 办法，更新每一个公有 Uniform 对象上的值到 WebGL 状态机中

是不是短少了点什么？

是的，UniformState 的值是如何赋予给 uniforms[i] 的？

这就不得不提及 ShaderProgram.js 模块中为以后着色器对象的 Uniform 分类过程了，查找模块中的 reinitialize 函数：

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 – 一个数组，每个元素都是 Uniform 的封装对象，例如 UniformFloatVec3 等，若同名，则与 _uniformsByName 中的值是同一个援用
  • _manualUniforms – 一个数组，每个元素都是 Uniform 的封装对象，例如 UniformFloatVec3 等，若同名，则与 _uniformsByName 中的值是同一个援用
  • _automaticUniforms – 一个数组，每个元素是一个 object 对象，示意要 CesiumJS 自动更新的 Uniform 的映射关联关系

举例，_automaticUniforms[i] 用 TypeScript 来形容，是这么一个对象：

type AutomaticUniformElement = {
  automaticUniform: AutomaticUniform
  uniform: UniformFloatVec3
}

而这个 _automaticUniforms 就领有自动更新 CesiumJS 外部状态的 Uniform 值的性能，例如咱们所需的光状态信息。

来看 AutomaticUniforms.js 模块的默认导出对象：

// 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 执行的时候，其实是对主动对立值有一个赋值的过程，而后才到各个 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 中
  // 是同一个援用在不同的地位，所以下面调用 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 执行 DrawCommand 过程中，ShaderProgram 的 _setUniforms 执行所有 uniforms 的 WebGL 设置，这其中就会对 CesiumJS 外部不须要手动更新的 Uniform 状态信息进行主动刷新
  • 而在 ShaderProgram 绑定前，早就会把这个着色器中的 uniform 进行分组，一组是惯例的 uniform 值，另一组则是须要依据 AutomaticUniform（主动对立值）更新的 uniform 值

说到底，光状态信息也不过是一种 Uniform，在最原始的 WebGL 学习教材中也是如此，只不过 CesiumJS 是一个更简单的状态机器，须要更多逻辑划分就是了。

3. 在着色器中如何应用

下面介绍完光的类型、在 CesiumJS 源码中如何转化成 Uniform 并刷入 WebGL，那么这一节就简略看看光的状态 Uniform 在着色器代码中都有哪些应用之处。

3.1. 点云

PointCloud.js 应用了 czm_lightColor。

找到 createShaders 函数上面这个分支：

// Version 1.104

function createShaders(pointCloud, frameState, style) {
  // ...
  if (usesNormals && 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";
  }
  // ...
}

显然，这段代码在拼凑顶点着色器代码，在 1.104 版本官网并没有扭转这种拼接着色器代码的模式。

着色代码的含意也很简略，将漫反射强度值乘上 czm_lightColor，把后果交给 color 的 xyz 重量。漫反射强度在这里限度了最大值 0.4。

漫反射强度来自内置 GLSL 函数 czm_getLambertDiffuse（参考 packages/engine/Source/Shaders/Builtin/Functions/getLambertDiffuse.glsl）

3.2. 冯氏着色法

Primitive API 材质对象的默认着色办法是 冯氏着色法（Phong），这个在 LearnOpenGL 网站上有具体介绍。

调用链：

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

除了 TexturedMaterialAppearanceFS 外，MaterialAppearance.js 还用了 BasicMaterialAppearanceFS、AllMaterialAppearanceFS 两个片元着色器，这俩也用到了 czm_phong 函数。

看看 czm_phong 函数本体：

// 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);
}

函数内后面的计算步骤是获取漫反射、高光值，走的是辅助函数，在这个文件内也能看到。

最初灯光 czm_lightColor 和材质的漫反射、兰伯特漫反射、材质辉光等因子一起相乘累加，失去最终的色彩值。

除了 phong.glsl 外，参加半透明计算的 czm_translucentPhong 函数（在 translucentPhong.glsl 文件中）在 OIT.js 模块中用于替换 czm_phong 函数。

3.3. 地球

在 Globe.js 中应用的 GlobeFS 片元着色器代码中应用到了 czm_lightColor，次要是 main 函数中：

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 函数钉死在 [0, 1] 区间内），而后将色彩、czm_lightColor、漫反射值和透明度一起计算出 finalColor，把最终色彩值交给下一步计算。

这里辨别了两个宏分支，受 TerrainProvider 影响，有趣味能够追一下 GlobeSurfaceTileProvider.js 模块中 addDrawCommandsForTile 函数中 hasVertexNormals 参数的获取。

3.4. 模型架构中的光着色阶段

在 1.97 大改的 Model API 中，PBR 着色法应用了 czm_lightColorHdr 变量。czm_lightColorHdr 也是主动对立值（AutomaticUniforms）的一个。

在 Model 的更新过程中，有一个 buildDrawCommands 的步骤，其中有一个函数 ModelRuntimePrimitive.prototype.configurePipeline 会增减 ModelRuntimePrimitive 上的着色阶段：

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

下面是其中一个阶段 —— LightingPipelineStage，最初在 ModelSceneGraph.prototype.buildDrawCommands 办法内会调用每一个 stage 的 process 办法，调用 shaderBuilder 构建出着色器对象所需的资料，进而构建出着色器对象。过程比较复杂，间接看其中 LightingPipelineStage.glsl 提供的阶段函数：

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;
}

进入 computePbrLighting 函数（同一个文件内）：

#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 变量作为灯光色彩，参加函数 czm_pbrLighting 计算出色彩值。

3.5. 后记

除了光色彩自身，我在着色器代码中看到被利用的还有光线的方向，次要是 czm_lightDirectionEC 等变量，光照材质仍需一个漫长的学习过程。

正文完
Cesium
发表至： Cesium
2023-04-16
 0
关于cesium:CesiumJS-更新日志-196-与-197-新构建工具-esbuild-体验及-Model-API-更替完成
关于cesium:Cesium加载广告牌二
关于cesium:Cesium-for-Unreal加载倾斜摄影
关于cesium:CesiumJS-2022^-原理4-最复杂的地球皮肤-影像与地形的渲染与下载过程