# 相机系统

## 分类

- 核心框架

## 目的

管理多相机注册、相机堆栈排序、渲染顺序控制，为 UI、场景、特效等提供分层渲染能力。

---

## 核心类

| 类 | 职责 |
|---|---|
| `HFCameraManager` | 相机管理器单例，维护相机列表和主相机引用 |
| `HFMainCamera` | 主相机，管理 CameraStack |
| `AbsHFCameraItem` | 相机项抽象基类，子类实现具体相机逻辑 |

---

## 创建自定义相机

继承 `AbsHFCameraItem`，实现 `CameraItem` 和 `Weight` 属性：

```csharp
public class UIOverlayCamera : AbsHFCameraItem
{
    [SerializeField] private Camera uiCamera;
    [SerializeField] private int weight = 10;
    
    public override Camera CameraItem => uiCamera;
    public override int Weight => weight;
    
    protected override void OnInitialize()
    {
        base.OnInitialize();
        uiCamera.clearFlags = CameraClearFlags.Depth;
        uiCamera.depth = 100;
    }
}
```

---

## 相机堆栈架构

```text
HFMainCamera (主相机)
    │
    ├── CameraStack (相机堆栈)
    │       ├── CameraItem1 (Weight=10)
    │       ├── CameraItem2 (Weight=20)
    │       └── CameraItem3 (Weight=5)
    │
    └── 按 Weight 排序 → 渲染顺序控制
```

---

## 管理相机

```csharp
public class CameraController : MonoBehaviour
{
    void Start()
    {
        HFCameraManager cameraMgr = HFCameraManager.Instance;
        
        UIOverlayCamera uiCamera = GetComponent<UIOverlayCamera>();
        cameraMgr.AddCamera(uiCamera);
        
        Camera mainCam = cameraMgr.mainCamera.MainCamera;
    }
    
    void OnDestroy()
    {
        UIOverlayCamera uiCamera = GetComponent<UIOverlayCamera>();
        HFCameraManager.Instance.RemoveCamera(uiCamera);
    }
}
```

---

## 常用 API

| 方法 | 说明 |
|-----|------|
| `AddCamera(AbsHFCameraItem)` | 添加相机到堆栈 |
| `RemoveCamera(AbsHFCameraItem)` | 从堆栈移除相机 |
| `GetCamera(string cameraName)` | 获取指定名称相机 |

---

## 使用规则

- 相机项必须继承 `AbsHFCameraItem`。
- `Weight` 决定堆栈内渲染顺序，值越大越靠后渲染。
- 添加和移除相机需成对出现，避免残留。
- UI 相机通常使用 `CameraClearFlags.Depth` 和较高 depth。

---

## 相关模块

- [UI 窗口系统](../UI窗口系统/README.md)
- [资源管理](../资源管理/README.md)

---

## 文档关联

> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。

| 文档 | 关联原因 |
|---|---|
| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
| [modules/frameworks/UI窗口系统/README.md](../UI窗口系统/README.md) | UI 窗口系统常与相机系统协作 |
| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |