@rtzh/engine 0.0.10 → 0.0.11

package/README.md

@@ -1,9 +1,69 @@
-# @rtzh/engine
-
-> ⚠️ 本项目是基于 CesiumJS 的 `@cesium/engine` 22.1.0 包修改而来的定制版本。
->
-> 原始项目来源：[CesiumGS/cesium](https://github.com/CesiumGS/cesium)
-
-## License
-
-[Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0.html). CesiumJS is free for both commercial and non-commercial use.
+# @rtzh/engine
+
+> ⚠️ 本项目是基于 CesiumJS 的 `@cesium/engine` 22.1.0 包修改而来的定制版本。
+>
+> 原始项目来源：[CesiumGS/cesium](https://github.com/CesiumGS/cesium)
+
+## License
+
+[Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0.html). CesiumJS is free for both commercial and non-commercial use.
+
+## 变更日志
+
+### 功能新增（Features）
+
+#### 模型及3D图块线框显示功能
+
+- 在 `Model` 类中新增 `showWireframe`、`hideWireframe` 和 `toggleWireframe` 方法，实现模型的线框渲染切换
+- 在 `Cesium3DTileset` 类中新增对应的线框显示方法，支持对整个3D图块集切换线框模式
+- 支持设置线框颜色及颜色混合模式
+- 支持链式调用以方便设置和切换线框状态
+- 对WebGL1环境添加提示，需启用 `enableDebugWireframe` 才能生效
+
+#### 基于重心坐标的线框调试模式支持
+
+- 在 `Model` 和 `Cesium3DTileset` 中新增 `debugWireframeMode` 属性，支持 `"lines"` 和 `"barycentric"` 两种模式切换
+- 新增 `debugWireframeColor`、`debugWireframeFillAlpha`、`debugWireframeLineWidth` 和 `debugWireframeOverlay` 属性，丰富线框渲染配置
+- 实现基于重心坐标的线框渲染管线，添加 `BarycentricWireframePipelineStage`
+- 修改顶点着色器(`ModelVS.glsl`)和片段着色器(`ModelFS.glsl`)以支持重心线框效果及叠加选项
+- 在 `WireframePipelineStage` 中增加对 barycentric 模式的跳过逻辑，避免重复渲染和冲突
+- 在 `Model3DTileContent` 中同步新线框调试属性，保证瓦片模型线框一致性
+- 兼容WebGL1和WebGL2环境，lines模式需启用 `enableDebugWireframe`，barycentric模式无需
+
+#### 线框扫描线和发光效果支持
+
+- 在 `Model` 和 `Cesium3DTileset` 中添加 `effects` 参数支持扫描线和发光配置
+- 实现扫描线方向、速度和发光强度的计算逻辑
+- 根据扫描线方向计算扫描范围和模型高度范围
+- 在 `Model3DTileContent` 中传递相关有线框效果参数
+- 修改片段着色器(`ModelFS.glsl`)添加扫描线高亮和发光效果的计算与混合
+- 修改顶点着色器(`ModelVS.glsl`)传递模型世界坐标，支持扫描线效果
+
+#### 点光源照明支持
+
+- 新增 `PointLight` 类描述点光源属性及构造方法
+- 在 `Scene` 中添加点光数组以支持额外光照
+- `UniformState` 中添加点光相关状态及自动uniform支持
+- `LightingPipelineStage` 新增点光相关宏定义和光照计算逻辑
+- `Model` 增加点光变化检测并触发绘制命令重建
+- 实现点光位置、颜色及范围等数据上传至GPU uniform数组
+- 维护点光数量限制为8并确保对应uniform数组长度匹配
+- 优化点光范围衰减和平滑过渡计算保障渲染效果
+- 在 `AutomaticUniforms.js` 中新增自动uniform以支持点光源数据传递到GLSL着色器
+- 在 `LightingStageFS.glsl` 中实现点光源光照计算代码，支持范围衰减和距离衰减
+- 在 `FrameState` 中新增 `pointLights` 字段以传递点光源信息
+
+### Bug修复（Fixes）
+
+- **优化 Model 的调试线框属性设置逻辑**
+  - 修正 `debugWireframeColor` 赋值时避免无效克隆和重复设置
+  - 添加 `debugWireframeFillAlpha` 赋值的重复值检测以减少无谓重绘
+  - 在 `Model3DTileContent` 中仅当 `debugWireframe` 开启时赋值相关调试线框属性
+  - 移除未启用 `debugWireframe` 时对 `model.color` 的无效赋值
+  - 统一默认的 `_debugWireframeScanAxis` 为 `Cartesian3(0, 0, 1)` 实例
+
+### 重构（Refactors）
+
+- 优化多个模块的代码结构和逻辑
+- 修正 Model 加载中 Feature ID 属性的类名称
+- 移除调试扫描线相关的多余高度变量和优化着色器逻辑

package/Source/Scene/Model/MaterialPipelineStage.js

@@ -65,6 +65,23 @@ MaterialPipelineStage.process = function (
   const hasClassification = defined(model.classificationType);
   const disableTextures = hasClassification;
 
+  // Collect the texture coordinate sets actually present in the geometry.
+  // Some models reference a texture whose UV set (e.g. TEXCOORD_0) does not
+  // exist on the mesh. If we still generate a `TEXCOORD_*` define for such a
+  // texture, the fragment shader would reference an undeclared
+  // `v_texCoord_n` varying and fail to compile, so those textures are skipped.
+  const texCoordSets = new Set();
+  const attributes = primitive.attributes;
+  for (let i = 0; i < attributes.length; i++) {
+    const attribute = attributes[i];
+    if (
+      attribute.semantic === VertexAttributeSemantic.TEXCOORD &&
+      defined(attribute.setIndex)
+    ) {
+      texCoordSets.add(attribute.setIndex);
+    }
+  }
+
   // When textures are loaded incrementally, fall back to a default 1x1 texture
   const { defaultTexture, defaultNormalTexture, defaultEmissiveTexture } =
     frameState.context;
@@ -77,6 +94,7 @@ MaterialPipelineStage.process = function (
     defaultNormalTexture,
     defaultEmissiveTexture,
     disableTextures,
+    texCoordSets,
   );
 
   if (defined(material.specularGlossiness)) {
@@ -86,6 +104,7 @@ MaterialPipelineStage.process = function (
       shaderBuilder,
       defaultTexture,
       disableTextures,
+      texCoordSets,
     );
   } else {
     if (
@@ -98,6 +117,7 @@ MaterialPipelineStage.process = function (
         shaderBuilder,
         defaultTexture,
         disableTextures,
+        texCoordSets,
       );
     }
     if (
@@ -110,6 +130,7 @@ MaterialPipelineStage.process = function (
         shaderBuilder,
         defaultTexture,
         disableTextures,
+        texCoordSets,
       );
     }
     if (
@@ -122,6 +143,7 @@ MaterialPipelineStage.process = function (
         shaderBuilder,
         defaultTexture,
         disableTextures,
+        texCoordSets,
       );
     }
     processMetallicRoughnessUniforms(
@@ -130,6 +152,7 @@ MaterialPipelineStage.process = function (
       shaderBuilder,
       defaultTexture,
       disableTextures,
+      texCoordSets,
     );
   }
 
@@ -272,7 +295,15 @@ function processTexture(
   uniformName,
   defineName,
   defaultTexture,
+  texCoordSets,
 ) {
+  // If the texture references a texture coordinate set that is not present in
+  // the geometry, skip it entirely. Otherwise the generated fragment shader
+  // would use an undeclared `v_texCoord_n` varying and fail to compile.
+  if (!texCoordSets.has(textureReader.texCoord)) {
+    return;
+  }
+
   // Add a uniform for the texture itself
   shaderBuilder.addUniform(
     "sampler2D",
@@ -333,6 +364,7 @@ function processMaterialUniforms(
   defaultNormalTexture,
   defaultEmissiveTexture,
   disableTextures,
+  texCoordSets,
 ) {
   const { emissiveFactor, emissiveTexture, normalTexture, occlusionTexture } =
     material;
@@ -363,6 +395,7 @@ function processMaterialUniforms(
         "u_emissiveTexture",
         "EMISSIVE",
         defaultEmissiveTexture,
+        texCoordSets,
       );
     }
   }
@@ -375,6 +408,7 @@ function processMaterialUniforms(
       "u_normalTexture",
       "NORMAL",
       defaultNormalTexture,
+      texCoordSets,
     );
   }
 
@@ -386,6 +420,7 @@ function processMaterialUniforms(
       "u_occlusionTexture",
       "OCCLUSION",
       defaultTexture,
+      texCoordSets,
     );
   }
 }
@@ -406,6 +441,7 @@ function processSpecularGlossinessUniforms(
   shaderBuilder,
   defaultTexture,
   disableTextures,
+  texCoordSets,
 ) {
   const {
     diffuseTexture,
@@ -429,6 +465,7 @@ function processSpecularGlossinessUniforms(
       "u_diffuseTexture",
       "DIFFUSE",
       defaultTexture,
+      texCoordSets,
     );
   }
 
@@ -459,6 +496,7 @@ function processSpecularGlossinessUniforms(
       "u_specularGlossinessTexture",
       "SPECULAR_GLOSSINESS",
       defaultTexture,
+      texCoordSets,
     );
   }
 
@@ -520,6 +558,7 @@ function processSpecularUniforms(
   shaderBuilder,
   defaultTexture,
   disableTextures,
+  texCoordSets,
 ) {
   const {
     specularTexture,
@@ -542,6 +581,7 @@ function processSpecularUniforms(
       "u_specularTexture",
       "SPECULAR",
       defaultTexture,
+      texCoordSets,
     );
   }
 
@@ -572,6 +612,7 @@ function processSpecularUniforms(
       "u_specularColorTexture",
       "SPECULAR_COLOR",
       defaultTexture,
+      texCoordSets,
     );
   }
 
@@ -616,6 +657,7 @@ function processAnisotropyUniforms(
   shaderBuilder,
   defaultTexture,
   disableTextures,
+  texCoordSets,
 ) {
   const { anisotropyStrength, anisotropyRotation, anisotropyTexture } =
     anisotropy;
@@ -634,6 +676,7 @@ function processAnisotropyUniforms(
       "u_anisotropyTexture",
       "ANISOTROPY",
       defaultTexture,
+      texCoordSets,
     );
   }
 
@@ -668,6 +711,7 @@ function processClearcoatUniforms(
   shaderBuilder,
   defaultTexture,
   disableTextures,
+  texCoordSets,
 ) {
   const {
     clearcoatFactor,
@@ -710,6 +754,7 @@ function processClearcoatUniforms(
       "u_clearcoatTexture",
       "CLEARCOAT",
       defaultTexture,
+      texCoordSets,
     );
   }
 
@@ -740,6 +785,7 @@ function processClearcoatUniforms(
       "u_clearcoatRoughnessTexture",
       "CLEARCOAT_ROUGHNESS",
       defaultTexture,
+      texCoordSets,
     );
   }
 
@@ -751,6 +797,7 @@ function processClearcoatUniforms(
       "u_clearcoatNormalTexture",
       "CLEARCOAT_NORMAL",
       defaultTexture,
+      texCoordSets,
     );
   }
 }
@@ -771,6 +818,7 @@ function processMetallicRoughnessUniforms(
   shaderBuilder,
   defaultTexture,
   disableTextures,
+  texCoordSets,
 ) {
   shaderBuilder.addDefine(
     "USE_METALLIC_ROUGHNESS",
@@ -787,6 +835,7 @@ function processMetallicRoughnessUniforms(
       "u_baseColorTexture",
       "BASE_COLOR",
       defaultTexture,
+      texCoordSets,
     );
   }
 
@@ -822,6 +871,7 @@ function processMetallicRoughnessUniforms(
       "u_metallicRoughnessTexture",
       "METALLIC_ROUGHNESS",
       defaultTexture,
+      texCoordSets,
     );
   }
 

package/index.js

@@ -494,7 +494,6 @@ export { default as _shadersVector3DTilePolylinesVS } from './Source/Shaders/Vec
 export { default as _shadersVectorTileVS } from './Source/Shaders/VectorTileVS.js';
 export { default as _shadersViewportQuadFS } from './Source/Shaders/ViewportQuadFS.js';
 export { default as _shadersViewportQuadVS } from './Source/Shaders/ViewportQuadVS.js';
-export { default as CesiumWidget } from './Source/Widget/CesiumWidget.js';
 export { default as AlphaMode } from './Source/Scene/AlphaMode.js';
 export { default as Appearance } from './Source/Scene/Appearance.js';
 export { default as ArcGisBaseMapType } from './Source/Scene/ArcGisBaseMapType.js';
@@ -851,6 +850,7 @@ export { default as VoxelShapeType } from './Source/Scene/VoxelShapeType.js';
 export { default as VoxelTraversal } from './Source/Scene/VoxelTraversal.js';
 export { default as WebMapServiceImageryProvider } from './Source/Scene/WebMapServiceImageryProvider.js';
 export { default as WebMapTileServiceImageryProvider } from './Source/Scene/WebMapTileServiceImageryProvider.js';
+export { default as CesiumWidget } from './Source/Widget/CesiumWidget.js';
 export { default as _shadersAllMaterialAppearanceFS } from './Source/Shaders/Appearances/AllMaterialAppearanceFS.js';
 export { default as _shadersAllMaterialAppearanceVS } from './Source/Shaders/Appearances/AllMaterialAppearanceVS.js';
 export { default as _shadersBasicMaterialAppearanceFS } from './Source/Shaders/Appearances/BasicMaterialAppearanceFS.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rtzh/engine",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "description": "CesiumJS is a JavaScript library for creating 3D globes and 2D maps in a web browser without a plugin.",
   "keywords": [
     "3D",