@realsee/five/ai_guides/features/parameter.md

Realsee Renderer SDK

# Parameter (配置系统)

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

## Schema

> **Definition**: [Parameter](../../five/model/parameter.d.ts)

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

### Parameter Categories (参数分类)

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

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

### Parameter Class API

#### 1. Getting Values (获取值)

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

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

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

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

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

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

#### 2. Methods (方法)

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

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

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

#### 3. Version (版本标识)

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

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

## Concepts

### 树形继承关系 (Hierarchy)

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

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

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

> **Global Configuration (全局设置)**:
> 若需修改所有模型的默认表现（如统一调暗亮度、统一设置显存上限），**请直接配置 `five.modelScene.parameter`**。它是继承链的根节点，其设置会向下传递给所有 Model 和 ViewLayer。
>
> **Why modelScene? (生命周期优势)**:
> `Model` 实例是跟随 Work 加载生命周期的（需 `five.load(work)` 后才能访问，且切换 Work 会销毁重建）。
> 相比之下，`ModelScene` 是常驻对象。因此，**使用 `modelScene` 进行配置更安全且持久**，既无需等待 Work 加载完成，也无需担心切换 Work 导致配置丢失。

## Examples

### 1. 基础配置 (Basic Usage)

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

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

### 2. 局部覆盖 (Override)

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

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

### 3. 重置配置 (Reset)

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

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

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

### 4. 获取配置 (Get Value)

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

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

## Related

*   [Material Parameters](./material.md): 材质与外观参数详情。
*   [3DTile Parameters](./3dtile.md): 性能与加载参数详情。
*   [Model](./model.md): Parameter 的宿主。

---

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