2026-03-26 16:45:24 +08:00
|
|
|
# LightComponent
|
|
|
|
|
|
|
|
|
|
**命名空间**: `XCEngine::Components`
|
|
|
|
|
|
|
|
|
|
**类型**: `class`
|
|
|
|
|
|
|
|
|
|
**头文件**: `XCEngine/Components/LightComponent.h`
|
|
|
|
|
|
2026-03-27 16:15:00 +08:00
|
|
|
**描述**: 保存基础灯光类型、颜色、强度、范围、聚光角和阴影标记等参数。
|
|
|
|
|
|
|
|
|
|
## 角色概述
|
|
|
|
|
|
|
|
|
|
`LightComponent` 是当前对象系统中的基础光源配置组件。和 [CameraComponent](../CameraComponent/CameraComponent.md) 类似，它本身是轻量数据容器：
|
|
|
|
|
|
|
|
|
|
- 它不拥有 GPU 资源
|
|
|
|
|
- 它不负责生成阴影贴图
|
|
|
|
|
- 它不直接执行光照计算
|
|
|
|
|
|
|
|
|
|
它的价值在于把“这个对象应被解释成什么灯光”这件事挂在 `GameObject` 上，便于场景、编辑器和后续渲染管线统一消费。
|
|
|
|
|
|
|
|
|
|
## 当前实现行为
|
|
|
|
|
|
|
|
|
|
### 1. 这是一个可序列化的数据组件
|
|
|
|
|
|
|
|
|
|
当前实现提供：
|
|
|
|
|
|
|
|
|
|
- 灯光类型 `LightType`
|
|
|
|
|
- 颜色 `Color`
|
|
|
|
|
- 强度 `Intensity`
|
|
|
|
|
- 范围 `Range`
|
|
|
|
|
- 聚光角 `SpotAngle`
|
|
|
|
|
- 阴影标记 `CastsShadows`
|
|
|
|
|
- 文本序列化/反序列化
|
|
|
|
|
|
|
|
|
|
没有 `Update()`，也没有直接面向渲染后端的执行逻辑。
|
|
|
|
|
|
|
|
|
|
### 2. 关键数值会被 clamp
|
|
|
|
|
|
|
|
|
|
按当前 `.cpp` 实现：
|
|
|
|
|
|
|
|
|
|
- `SetIntensity()` 限制为 `>= 0.0f`
|
|
|
|
|
- `SetRange()` 限制为 `>= 0.001f`
|
|
|
|
|
- `SetSpotAngle()` 限制为 `1.0f ~ 179.0f`
|
|
|
|
|
|
|
|
|
|
这些行为已被 `tests/Components/test_camera_light_component.cpp` 覆盖。
|
|
|
|
|
|
|
|
|
|
## 设计理解
|
|
|
|
|
|
|
|
|
|
把灯光做成组件，而不是做成一个脱离对象树的单独系统，有几个直接好处：
|
|
|
|
|
|
|
|
|
|
- 可以直接复用 `TransformComponent` 决定光源位置和朝向
|
|
|
|
|
- 编辑器层级里“哪个对象是灯”非常直观
|
|
|
|
|
- 场景保存/加载时，灯光和对象树天然同生命周期
|
|
|
|
|
|
|
|
|
|
这也是多数商业引擎采用的思路。
|
|
|
|
|
|
|
|
|
|
## 与 Transform 的关系
|
|
|
|
|
|
|
|
|
|
`LightComponent` 自身不保存位置与朝向。当前 API 的空间语义来自宿主对象：
|
|
|
|
|
|
|
|
|
|
- `Directional` 灯通常依赖对象旋转表示方向
|
|
|
|
|
- `Point` / `Spot` 灯通常依赖对象位置
|
|
|
|
|
|
|
|
|
|
因此在上层使用时，应该把灯光参数和宿主 `Transform` 一起看待，而不是孤立看这个组件。
|
|
|
|
|
|
|
|
|
|
## 序列化语义
|
|
|
|
|
|
|
|
|
|
当前会写出：
|
|
|
|
|
|
|
|
|
|
- `type`
|
|
|
|
|
- `color`
|
|
|
|
|
- `intensity`
|
|
|
|
|
- `range`
|
|
|
|
|
- `spotAngle`
|
|
|
|
|
- `shadows`
|
|
|
|
|
|
|
|
|
|
这意味着 `LightComponent` 已属于当前场景系统中可以完整持久化的内建组件。
|
|
|
|
|
|
|
|
|
|
## 线程语义
|
|
|
|
|
|
|
|
|
|
- 当前实现没有内部加锁。
|
|
|
|
|
- 默认应在主线程配置路径使用。
|
|
|
|
|
|
|
|
|
|
## 当前实现限制
|
|
|
|
|
|
|
|
|
|
- 这里只描述光源参数，不代表当前渲染管线已经完整消费了所有高级灯光特性。
|
|
|
|
|
- 文档没有把它写成“完整商业级光照系统”，因为从当前代码看，它更接近基础参数容器。
|
|
|
|
|
- 没有在当前取证范围里看到专门的阴影系统或复杂光照调度与它强绑定。
|
|
|
|
|
|
|
|
|
|
## 相关方法
|
|
|
|
|
|
|
|
|
|
- [GetLightType](GetLightType.md)
|
|
|
|
|
- [SetLightType](SetLightType.md)
|
|
|
|
|
- [GetColor](GetColor.md)
|
|
|
|
|
- [SetColor](SetColor.md)
|
|
|
|
|
- [GetIntensity](GetIntensity.md)
|
|
|
|
|
- [SetIntensity](SetIntensity.md)
|
|
|
|
|
- [GetRange](GetRange.md)
|
|
|
|
|
- [SetRange](SetRange.md)
|
|
|
|
|
- [GetSpotAngle](GetSpotAngle.md)
|
|
|
|
|
- [SetSpotAngle](SetSpotAngle.md)
|
|
|
|
|
- [GetCastsShadows](GetCastsShadows.md)
|
|
|
|
|
- [SetCastsShadows](SetCastsShadows.md)
|
|
|
|
|
- [Serialize](Serialize.md)
|
|
|
|
|
- [Deserialize](Deserialize.md)
|
2026-03-26 16:45:24 +08:00
|
|
|
|
|
|
|
|
## 相关文档
|
|
|
|
|
|
2026-03-27 16:15:00 +08:00
|
|
|
- [当前模块](../Components.md)
|
|
|
|
|
- [GameObject](../GameObject/GameObject.md)
|
|
|
|
|
- [TransformComponent](../TransformComponent/TransformComponent.md)
|
|
|
|
|
- [API 总索引](../../../main.md)
|
