XCEngine/docs/api/XCEngine/Rendering/RenderSurface/SetAutoTransitionEnabled.md

# RenderSurface::SetAutoTransitionEnabled

设置是否让部分渲染路径自动切换颜色附件状态。

```cpp
void SetAutoTransitionEnabled(bool enabled);
```

## 2026-04-10 更新

- 当前这个开关不再只服务少数颜色路径；多条 Rendering pass 都会在它为 `true` 时按 `RenderSurface` 上记录的约定插入 barrier。
- 自动切换涉及的不只是 color，部分 pass 也会读取
  [GetDepthStateBefore](GetDepthStateBefore.md) /
  [GetDepthStateAfter](GetDepthStateAfter.md)
  来接管 depth 附件。
- `RenderSurface` 自身并不执行 barrier；它只保存契约。真正的状态切换仍发生在具体 pass 的执行路径里。

## 参数

- `enabled` - `true` 表示允许读取 `colorStateBefore / colorStateAfter` 并自动插入颜色附件 barrier；`false` 表示由调用方或 pass 自己管理。

## 当前语义

- `BuiltinForwardPipeline::Render()` 和 `BuiltinObjectIdPass::Render()` 会读取这个开关。
- 打开时，它们会把颜色附件从 [GetColorStateBefore](GetColorStateBefore.md) 过渡到 `RenderTarget`，结束后再过渡到 [GetColorStateAfter](GetColorStateAfter.md)。
- 关闭时，这两条路径仍会继续渲染，但默认假设调用方已经保证目标颜色资源处于正确状态。

## 当前实现边界

- 这个开关不处理深度附件状态。
- 它也不会阻止其他 pass 显式做自己的 barrier。编辑器 overlay pass 就会无视该开关，直接把颜色附件从 `GetColorStateAfter()` 切到 `RenderTarget` 并在结束后切回去。

## 相关文档

- [RenderSurface](RenderSurface.md)
- [IsAutoTransitionEnabled](IsAutoTransitionEnabled.md)
- [SetColorStateBefore](SetColorStateBefore.md)
- [SetColorStateAfter](SetColorStateAfter.md)