Parameter (配置系统)

• Summary: Five 用于控制三维模型渲染表现的核心配置系统，采用树形继承设计。
• Schema: 是所有配置项的容器，通过继承机制管理 Material 和 3DTile 等子配置。
• Concepts: Hierarchy (树形继承), Override (覆盖), Resolution (解析)。
• Examples: 全局配置、局部覆盖、参数重置。

Schema

Definition: Parameter

Parameter 类是配置的入口。它并不直接包含所有配置字段的定义，而是将它们组织在不同的接口中。

Parameter Categories (参数分类)

为了便于理解，我们将参数分为两大类：

Category	Description	Link
Material & Appearance	控制“长什么样”。包括材质、颜色、楼层显示、阴影、点云样式等。	Material Params
3DTile & Performance	控制“怎么加载”。包括 LOD (细节层级)、显存配额、网络并发、SSE 阈值等。	3DTile Params

Parameter Class API

1. Getting Values (获取值)

获取参数值不使用 get() 方法，而是直接访问属性。

• Direct Access (直接访问): 获取当前 Parameter 实例上设置的值。如果未设置，返回 undefined。
• Resolve Value (计算最终值): 获取经过树形继承计算后的最终生效值。
  • 如果不传参，则基于默认值计算 (Default -> Current)。
  • 如果传入上游 Parameter，则基于默认值 + 上游 Parameter 计算 (Default -> Upstream -> Current)。

// 方式 A: 直接访问 (获取当前层级配置)
const currentVal = parameter.maxMemoryUsage;

// 方式 B: 计算最终值 (包含继承逻辑)

// 1. 基础用法：仅继承默认值
const finalVal = parameter.resolveValue().maxMemoryUsage;

// 2. 进阶用法：指定继承源 (例如 ViewLayer 继承自 Model)
const inheritedVal = viewLayerParam.resolveValue(parentParameter).maxMemoryUsage;
Copy

2. Methods (方法)

Parameter 实例提供了以下核心方法来管理配置：

class Parameter {
  /**
   * 设置配置项
   * @param key 参数名 (如 'opacity', 'maxMemoryUsage')
   * @param value 参数值
   */
  set(key: string, value: any): void;

  /**
   * 重置配置项（移除当前层级的设置，恢复继承上游的值）
   * @param keys 要重置的参数名列表
   */
  reset(...keys: string[]): void;

  /**
   * 获取经过继承计算后的最终值（每次调用创建新对象）
   * @param upstream 上游 Parameter 对象列表（通常由引擎自动传入）
   */
  resolveValue(...upstream: Parameter[]): ResolvedParameterValue;

  /**
   * 获取经过继承计算后的最终值（复用 target 对象，避免重复创建）
   * 适用于高频调用场景（如逐帧更新），可显著减少 GC 压力。
   * @param target 用于写入结果的已有对象，其属性会被重置为默认值后重新赋值
   * @param upstream 上游 Parameter 对象列表
   */
  static resolveValueTo(
    target: Partial<ResolvedParameterValue>,
    ...upstream: Partial<ParameterValue>[]
  ): ResolvedParameterValue;
}
Copy

resolveValue() 内部已委托给 resolveValueTo({}, ...)，两者计算逻辑一致，区别仅在于是否复用对象。

3. Version (版本标识)

ResolvedParameterValue 通过 versionNumber: number 标识当前配置的版本。引擎内部使用整数哈希（而非字符串拼接）计算版本号，用于高效的脏检查。

interface ResolvedParameterValue extends ParameterValue {
  /** 整数哈希，输入参数变化时值会改变，用于脏检查 */
  versionNumber: number;
}
Copy

Concepts

树形继承关系 (Hierarchy)

Parameter 遵循 “就近原则” (Override) 的继承逻辑。

1. ViewLayer Parameter: 最具体，优先级最高。通常对应一个具体的 .gltf 文件或数据块。
2. Model Parameter: 覆盖该 Model 下的所有 ViewLayer。一个 Model 可能包含多个 ViewLayer (如 Mesh 层和 PointCloud 层)。
3. ModelScene Parameter: 全局默认值，优先级最低。影响整个场景。

graph TD
  Scene[ModelScene.parameter] -->|Inherit| Model[Model.parameter]
  Model -->|Inherit| Layer1[ViewLayer.parameter]
  Model -->|Inherit| Layer2[ViewLayer.parameter]
Copy

Global Configuration (全局设置): 若需修改所有模型的默认表现（如统一调暗亮度、统一设置显存上限），请直接配置 five.modelScene.parameter。它是继承链的根节点，其设置会向下传递给所有 Model 和 ViewLayer。

Why modelScene? (生命周期优势): Model 实例是跟随 Work 加载生命周期的（需 five.load(work) 后才能访问，且切换 Work 会销毁重建）。 相比之下，ModelScene 是常驻对象。因此，使用 modelScene 进行配置更安全且持久，既无需等待 Work 加载完成，也无需担心切换 Work 导致配置丢失。

Examples

1. 基础配置 (Basic Usage)

// 1. 设置全局最大显存 (影响所有模型)
five.modelScene.parameter.set('maxMemoryUsage', 512);

// 2. 设置全局半透明
five.modelScene.parameter.set('opacity', 0.5);
Copy

2. 局部覆盖 (Override)

// 场景中大部分模型不产生阴影
five.modelScene.parameter.set('castShadow', false);

// 但让特定的“主角”模型产生阴影
const heroModel = five.models[0];
heroModel.parameter.set('castShadow', true);
Copy

3. 重置配置 (Reset)

// 假设之前设置了 opacity
five.modelScene.parameter.set('opacity', 0.5);

// ... 一段时间后 ...

// 移除该设置，恢复默认值 (或继承值)
five.modelScene.parameter.reset('opacity');
Copy

4. 获取配置 (Get Value)

// 获取当前对象上的配置（如果未设置，则为 undefined）
const ownOpacity = five.modelScene.parameter.opacity;

// 获取最终生效的配置（计算继承链后的值）
const finalOpacity = five.modelScene.parameter.resolveValue().opacity;
Copy

Related

• Material Parameters: 材质与外观参数详情。
• 3DTile Parameters: 性能与加载参数详情。
• Model: Parameter 的宿主。

---

tags: [配置, 参数, 继承, 覆盖, 全局配置, 局部配置, parameter, config, hierarchy, api, set, reset, modelScene]
Copy