docs(api): deepen OpenGL swap chain shader and framebuffer docs
This commit is contained in:
@@ -1,4 +1,4 @@
|
||||
# OpenGLFramebuffer::Bind
|
||||
# OpenGLFramebuffer::Bind()
|
||||
|
||||
```cpp
|
||||
void Bind();
|
||||
@@ -6,13 +6,19 @@ void Bind();
|
||||
|
||||
## 作用
|
||||
|
||||
把当前 FBO 绑定到 `GL_FRAMEBUFFER`。
|
||||
把当前对象的 FBO 绑定到 `GL_FRAMEBUFFER`。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 直接调用 `glBindFramebuffer(GL_FRAMEBUFFER, m_framebuffer)`。
|
||||
- 不区分 `READ_FRAMEBUFFER` 与 `DRAW_FRAMEBUFFER`。
|
||||
- 直接调用 `glBindFramebuffer(GL_FRAMEBUFFER, m_framebuffer)`
|
||||
- 不检查 `m_framebuffer` 是否为 `0`
|
||||
- 不保存旧绑定
|
||||
|
||||
## 设计说明
|
||||
|
||||
`OpenGLFramebuffer` 采用的是非常直接的 OpenGL 风格 API。它不隐藏全局状态切换，而是把“绑定哪个 FBO”这件事明确暴露给调用者。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Unbind](Unbind.md)
|
||||
- [GetFramebuffer](GetFramebuffer.md)
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# OpenGLFramebuffer::BindFramebuffer
|
||||
# OpenGLFramebuffer::BindFramebuffer()
|
||||
|
||||
```cpp
|
||||
static void BindFramebuffer(unsigned int framebuffer);
|
||||
@@ -6,12 +6,18 @@ static void BindFramebuffer(unsigned int framebuffer);
|
||||
|
||||
## 作用
|
||||
|
||||
静态辅助函数，把任意 framebuffer id 绑定到 `GL_FRAMEBUFFER`。
|
||||
以静态辅助函数形式绑定任意 FBO。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 直接调用 `glBindFramebuffer(GL_FRAMEBUFFER, framebuffer)`。
|
||||
- 直接执行 `glBindFramebuffer(GL_FRAMEBUFFER, framebuffer)`
|
||||
- 不依赖当前对象实例
|
||||
|
||||
## 适用场景
|
||||
|
||||
当上层已经持有原始 FBO ID，而不想再经过实例方法时，可以使用这个静态入口。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [UnbindFramebuffer](UnbindFramebuffer.md)
|
||||
- [GetFramebuffer](GetFramebuffer.md)
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# OpenGLFramebuffer::ClearColor
|
||||
# OpenGLFramebuffer::ClearColor()
|
||||
|
||||
```cpp
|
||||
void ClearColor(int attachmentIndex, float r, float g, float b, float a);
|
||||
@@ -10,16 +10,22 @@ void ClearColor(int attachmentIndex, float r, float g, float b, float a);
|
||||
|
||||
## 参数
|
||||
|
||||
- `attachmentIndex`: 颜色附件序号。
|
||||
- `r` / `g` / `b` / `a`: 清除颜色。
|
||||
- `attachmentIndex`: 颜色附件槽位
|
||||
- `r` / `g` / `b` / `a`: 清屏颜色
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 先绑定当前 FBO。
|
||||
- 调用 `glClearBufferfv(GL_COLOR, attachmentIndex, &r)` 执行清除。
|
||||
- 不恢复之前的 framebuffer 绑定状态。
|
||||
- 先把当前对象绑定到 `GL_FRAMEBUFFER`
|
||||
- 调用 `glClearBufferfv(GL_COLOR, attachmentIndex, &r)`
|
||||
- 依赖四个局部参数在栈上的连续布局，作为 RGBA 数组传入
|
||||
- 不恢复调用前的 FBO 绑定
|
||||
|
||||
## 注意事项
|
||||
|
||||
这是一条后端便捷接口，不是命令列表级的延迟录制命令。调用它会立即修改当前 OpenGL 状态。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ClearDepth](ClearDepth.md)
|
||||
- [ClearDepthStencil](ClearDepthStencil.md)
|
||||
- [Bind](Bind.md)
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# OpenGLFramebuffer::ClearDepth
|
||||
# OpenGLFramebuffer::ClearDepth()
|
||||
|
||||
```cpp
|
||||
void ClearDepth(float depth);
|
||||
@@ -6,13 +6,16 @@ void ClearDepth(float depth);
|
||||
|
||||
## 作用
|
||||
|
||||
清除当前 framebuffer 的深度附件。
|
||||
清除当前 FBO 的深度缓冲。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 先绑定当前 FBO。
|
||||
- 调用 `glClearDepth(depth)`，随后执行 `glClear(GL_DEPTH_BUFFER_BIT)`。
|
||||
- 绑定 `m_framebuffer`
|
||||
- 调用 `glClearDepth(depth)`
|
||||
- 再调用 `glClear(GL_DEPTH_BUFFER_BIT)`
|
||||
- 不恢复之前的 FBO 绑定
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ClearStencil](ClearStencil.md)
|
||||
- [ClearDepthStencil](ClearDepthStencil.md)
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# OpenGLFramebuffer::ClearDepthStencil
|
||||
# OpenGLFramebuffer::ClearDepthStencil()
|
||||
|
||||
```cpp
|
||||
void ClearDepthStencil(float depth, uint8_t stencil);
|
||||
@@ -6,13 +6,19 @@ void ClearDepthStencil(float depth, uint8_t stencil);
|
||||
|
||||
## 作用
|
||||
|
||||
同时清除深度和模板附件。
|
||||
同时清除深度和模板缓冲。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 先绑定当前 FBO。
|
||||
- 设置 `glClearDepth(depth)` 与 `glClearStencil(stencil)`。
|
||||
- 调用 `glClear(GL_DEPTH_BUFFER_BIT | GL_STENCIL_BUFFER_BIT)`。
|
||||
- 绑定 `m_framebuffer`
|
||||
- 调用 `glClearDepth(depth)`
|
||||
- 调用 `glClearStencil(stencil)`
|
||||
- 最后执行 `glClear(GL_DEPTH_BUFFER_BIT | GL_STENCIL_BUFFER_BIT)`
|
||||
- 不恢复旧绑定
|
||||
|
||||
## 设计说明
|
||||
|
||||
把深度与模板打包清除是很常见的 FBO 操作，尤其适合与 `DepthStencil` 附件语义对应。
|
||||
|
||||
## 相关文档
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# OpenGLFramebuffer::ClearStencil
|
||||
# OpenGLFramebuffer::ClearStencil()
|
||||
|
||||
```cpp
|
||||
void ClearStencil(uint8_t stencil);
|
||||
@@ -6,13 +6,16 @@ void ClearStencil(uint8_t stencil);
|
||||
|
||||
## 作用
|
||||
|
||||
清除当前 framebuffer 的模板附件。
|
||||
清除当前 FBO 的模板缓冲。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 先绑定当前 FBO。
|
||||
- 调用 `glClearStencil(stencil)`，随后执行 `glClear(GL_STENCIL_BUFFER_BIT)`。
|
||||
- 绑定 `m_framebuffer`
|
||||
- 调用 `glClearStencil(stencil)`
|
||||
- 调用 `glClear(GL_STENCIL_BUFFER_BIT)`
|
||||
- 不恢复之前的 FBO 绑定
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [ClearDepth](ClearDepth.md)
|
||||
- [ClearDepthStencil](ClearDepthStencil.md)
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# OpenGLFramebuffer::OpenGLFramebuffer
|
||||
# OpenGLFramebuffer::OpenGLFramebuffer()
|
||||
|
||||
```cpp
|
||||
OpenGLFramebuffer();
|
||||
@@ -6,13 +6,15 @@ OpenGLFramebuffer();
|
||||
|
||||
## 作用
|
||||
|
||||
构造一个空 FBO 包装对象。
|
||||
构造一个尚未创建 FBO 的帧缓冲对象。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 把 framebuffer id、宽高和 sample 数初始化为 `0 / 0 / 1`。
|
||||
- 不创建真实 OpenGL framebuffer。
|
||||
- 把 `m_framebuffer` 置为 `0`
|
||||
- 把 `m_width`、`m_height` 置为 `0`
|
||||
- 把 `m_samples` 初始化为 `1`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Initialize](Initialize.md)
|
||||
- [IsValid](IsValid.md)
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# OpenGLFramebuffer::~OpenGLFramebuffer
|
||||
# OpenGLFramebuffer::~OpenGLFramebuffer()
|
||||
|
||||
```cpp
|
||||
~OpenGLFramebuffer() override;
|
||||
@@ -6,13 +6,13 @@
|
||||
|
||||
## 作用
|
||||
|
||||
销毁对象并释放内部 FBO。
|
||||
析构并释放当前 FBO。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 析构函数调用 [`Shutdown`](Shutdown.md)。
|
||||
- 如果已经创建过 framebuffer，会执行 `glDeleteFramebuffers()`。
|
||||
- 析构函数直接调用 [Shutdown](Shutdown.md)
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Shutdown](Shutdown.md)
|
||||
- [OpenGLFramebuffer](OpenGLFramebuffer.md)
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# OpenGLFramebuffer::GetFramebuffer
|
||||
# OpenGLFramebuffer::GetFramebuffer()
|
||||
|
||||
```cpp
|
||||
unsigned int GetFramebuffer() const;
|
||||
@@ -6,13 +6,17 @@ unsigned int GetFramebuffer() const;
|
||||
|
||||
## 作用
|
||||
|
||||
返回内部保存的 OpenGL framebuffer id。
|
||||
返回底层 OpenGL FBO ID。
|
||||
|
||||
## 返回值
|
||||
## 当前实现行为
|
||||
|
||||
- 返回 `m_framebuffer`。
|
||||
- 直接返回成员 `m_framebuffer`
|
||||
|
||||
## 使用场景
|
||||
|
||||
当后端需要把这个对象与其他 OpenGL 专用代码联动，例如手动 `glBindFramebuffer`、调试 FBO 状态或组合命令列表内部逻辑时，这个方法很有用。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [GetNativeHandle](GetNativeHandle.md)
|
||||
- [BindFramebuffer](BindFramebuffer.md)
|
||||
- [Bind](Bind.md)
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# OpenGLFramebuffer::GetHeight
|
||||
# OpenGLFramebuffer::GetHeight()
|
||||
|
||||
```cpp
|
||||
uint32_t GetHeight() const override;
|
||||
@@ -6,12 +6,15 @@ uint32_t GetHeight() const override;
|
||||
|
||||
## 作用
|
||||
|
||||
返回 framebuffer 的逻辑高度。
|
||||
返回当前对象记录的 FBO 高度。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 返回内部记录的 `m_height`。
|
||||
- 返回 `static_cast<uint32_t>(m_height)`
|
||||
- 这个值在 [Initialize](Initialize.md) 成功进入时写入
|
||||
- [Shutdown](Shutdown.md) 后会重置为 `0`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [GetWidth](GetWidth.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# OpenGLFramebuffer::GetNativeHandle
|
||||
# OpenGLFramebuffer::GetNativeHandle()
|
||||
|
||||
```cpp
|
||||
void* GetNativeHandle() override;
|
||||
@@ -6,12 +6,18 @@ void* GetNativeHandle() override;
|
||||
|
||||
## 作用
|
||||
|
||||
返回原生 OpenGL framebuffer id。
|
||||
以统一 RHI 句柄形式返回底层 FBO。
|
||||
|
||||
## 返回值
|
||||
## 当前实现行为
|
||||
|
||||
- 返回 `m_framebuffer`，以 `void*` 形式暴露。
|
||||
- 把 `m_framebuffer` 转成 `uintptr_t`
|
||||
- 再转成 `void*` 返回
|
||||
|
||||
## 注意事项
|
||||
|
||||
这个句柄本质上是 OpenGL 对象名，不是独立的原生指针对象。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [GetFramebuffer](GetFramebuffer.md)
|
||||
- [IsValid](IsValid.md)
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# OpenGLFramebuffer::GetWidth
|
||||
# OpenGLFramebuffer::GetWidth()
|
||||
|
||||
```cpp
|
||||
uint32_t GetWidth() const override;
|
||||
@@ -6,13 +6,15 @@ uint32_t GetWidth() const override;
|
||||
|
||||
## 作用
|
||||
|
||||
返回 framebuffer 的逻辑宽度。
|
||||
返回当前对象记录的 FBO 宽度。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 返回内部记录的 `m_width`。
|
||||
- 该值来自初始化参数，而不是运行时向 OpenGL 查询。
|
||||
- 返回 `static_cast<uint32_t>(m_width)`
|
||||
- 宽度来自最近一次 [Initialize](Initialize.md) 成功进入时的参数
|
||||
- [Shutdown](Shutdown.md) 后会重置为 `0`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [GetHeight](GetHeight.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,47 +1,73 @@
|
||||
# OpenGLFramebuffer::Initialize
|
||||
# OpenGLFramebuffer::Initialize()
|
||||
|
||||
```cpp
|
||||
bool Initialize(const FramebufferDesc& desc);
|
||||
|
||||
bool Initialize(
|
||||
RHIRenderPass* renderPass,
|
||||
uint32_t width,
|
||||
uint32_t height,
|
||||
uint32_t colorAttachmentCount,
|
||||
RHIResourceView** colorAttachments,
|
||||
RHIResourceView* depthStencilAttachment) override;
|
||||
bool Initialize(RHIRenderPass* renderPass,
|
||||
uint32_t width,
|
||||
uint32_t height,
|
||||
uint32_t colorAttachmentCount,
|
||||
RHIResourceView** colorAttachments,
|
||||
RHIResourceView* depthStencilAttachment) override;
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
创建并填充一个 OpenGL framebuffer object。
|
||||
根据显式附件描述或统一 RHI 资源视图创建一个 OpenGL FBO。
|
||||
|
||||
## 当前实现行为
|
||||
## 重载 1: 原生 `FramebufferDesc`
|
||||
|
||||
### `Initialize(const FramebufferDesc& desc)`
|
||||
```cpp
|
||||
bool Initialize(const FramebufferDesc& desc);
|
||||
```
|
||||
|
||||
- 复制 `FramebufferDesc` 到内部成员。
|
||||
- 创建 FBO 并附着最多 `16` 个颜色附件。
|
||||
- 根据 depth / stencil 附件类型选择合适的 attachment point。
|
||||
- 如果没有颜色附件，会把 `glDrawBuffer` 和 `glReadBuffer` 设为 `GL_NONE`。
|
||||
- 调用 `glCheckFramebufferStatus(GL_FRAMEBUFFER)` 验证完整性。
|
||||
### 当前实现行为
|
||||
|
||||
### `Initialize(RHIRenderPass*, ...)`
|
||||
- 把 `width`、`height`、`samples` 和完整 `desc` 缓存到对象成员
|
||||
- 调用 `glGenFramebuffers` 创建 FBO
|
||||
- 绑定到 `GL_FRAMEBUFFER`
|
||||
- 最多处理前 `16` 个颜色附件
|
||||
- 根据附件的 `target`、`mipLevel`、`layer` 选择：
|
||||
- `glFramebufferTextureLayer`
|
||||
- `glFramebufferTexture1D`
|
||||
- `glFramebufferTexture2D`
|
||||
- `glFramebufferTexture`
|
||||
- 深度附件与模板附件会根据 `FramebufferAttachmentType` 决定挂到：
|
||||
- `GL_DEPTH_ATTACHMENT`
|
||||
- `GL_DEPTH_STENCIL_ATTACHMENT`
|
||||
- `GL_STENCIL_ATTACHMENT`
|
||||
- 有颜色附件时调用 `glDrawBuffers`
|
||||
- 无颜色附件时设置 `glDrawBuffer(GL_NONE)` 与 `glReadBuffer(GL_NONE)`
|
||||
- 最后做 `glCheckFramebufferStatus(GL_FRAMEBUFFER)` 完整性检查
|
||||
|
||||
- 当前忽略 `renderPass` 参数。
|
||||
- 从 `OpenGLResourceView::GetFramebufferAttachment()` 提取附件信息。
|
||||
- 同样创建 FBO、设置 draw buffer，并检查完整性。
|
||||
### 注意事项
|
||||
|
||||
## 返回值
|
||||
- `samples` 目前只被记录，不会驱动单独的多重采样附件创建逻辑
|
||||
- 如果完整性检查失败，函数返回 `false`，但对象释放仍依赖后续 [Shutdown](Shutdown.md) 或析构
|
||||
|
||||
- FBO 完整时返回 `true`。
|
||||
- `glCheckFramebufferStatus()` 不是 `GL_FRAMEBUFFER_COMPLETE` 时返回 `false`。
|
||||
## 重载 2: 统一 RHI 入口
|
||||
|
||||
## 当前限制
|
||||
```cpp
|
||||
bool Initialize(RHIRenderPass* renderPass,
|
||||
uint32_t width,
|
||||
uint32_t height,
|
||||
uint32_t colorAttachmentCount,
|
||||
RHIResourceView** colorAttachments,
|
||||
RHIResourceView* depthStencilAttachment) override;
|
||||
```
|
||||
|
||||
- 创建失败时不会在函数内部立即删除刚生成的 FBO id，通常由后续析构统一释放。
|
||||
### 当前实现行为
|
||||
|
||||
- `renderPass` 当前被显式忽略
|
||||
- 把尺寸写入成员，`m_samples` 固定设为 `1`
|
||||
- 从 `OpenGLResourceView` 中取出 `FramebufferAttachment` 描述
|
||||
- 使用与原生重载相同的 FBO 绑定和完整性检查流程
|
||||
|
||||
## 设计说明
|
||||
|
||||
这两个入口体现了当前 OpenGL 后端的一个核心思路：虽然 RHI 层保留了 render pass / resource view 抽象，但落到 OpenGL 时，真正起作用的仍然是“把哪些纹理附件挂到哪个 FBO 上”。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [IsValid](IsValid.md)
|
||||
- [OpenGLFramebuffer](OpenGLFramebuffer.md)
|
||||
- [OpenGLResourceView](../OpenGLResourceView/OpenGLResourceView.md)
|
||||
- [GetFramebuffer](GetFramebuffer.md)
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# OpenGLFramebuffer::IsValid
|
||||
# OpenGLFramebuffer::IsValid()
|
||||
|
||||
```cpp
|
||||
bool IsValid() const override;
|
||||
@@ -6,16 +6,17 @@ bool IsValid() const override;
|
||||
|
||||
## 作用
|
||||
|
||||
判断当前对象是否持有非零 FBO id。
|
||||
|
||||
## 返回值
|
||||
|
||||
- `m_framebuffer != 0` 时返回 `true`。
|
||||
判断对象是否已经持有一个非零 FBO。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 这是一个轻量检查，不会再次执行 `glCheckFramebufferStatus()`。
|
||||
- 直接检查 `m_framebuffer != 0`
|
||||
|
||||
## 注意事项
|
||||
|
||||
它不重新执行 `glCheckFramebufferStatus`，也不验证附件当前是否仍然完整。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Initialize](Initialize.md)
|
||||
- [GetFramebuffer](GetFramebuffer.md)
|
||||
|
||||
@@ -6,43 +6,59 @@
|
||||
|
||||
**头文件**: `XCEngine/RHI/OpenGL/OpenGLFramebuffer.h`
|
||||
|
||||
**描述**: OpenGL 后端的 framebuffer 对象封装，用于把颜色、深度、模板附件组织成一个可绑定的 FBO。
|
||||
**描述**: OpenGL 后端的帧缓冲对象封装器，用来把颜色、深度、模板附件组装成一个可绑定的 FBO。
|
||||
|
||||
## 概述
|
||||
## 概览
|
||||
|
||||
和 Vulkan / D3D12 的 render pass + framebuffer 分层不同，OpenGL 更偏向直接操作 framebuffer object。`OpenGLFramebuffer` 的职责，是把引擎内部的附件描述或资源视图组合成一个实际的 FBO，并提供基础的绑定与清屏操作。
|
||||
在现代显式 API 里，`RenderPass`、`Framebuffer`、附件 load/store 规则通常是分层设计的；而在 OpenGL 里，最核心的实体往往就是 FBO 本身。`OpenGLFramebuffer` 的职责正是把这两种模型接起来。
|
||||
|
||||
它可以理解为 OpenGL 后端里的“附件包”:
|
||||
当前类支持两种输入方式：
|
||||
|
||||
- 你先描述要挂哪些 texture / layer / mip。
|
||||
- 它负责创建 FBO、附着附件并检查完整性。
|
||||
- 命令列表或截图逻辑再在这个 FBO 上执行绘制、清理和 blit。
|
||||
- 直接使用 `FramebufferDesc`
|
||||
- 通过统一 RHI 的 `RHIResourceView` 列表构建
|
||||
|
||||
无论入口如何，最终落地行为都是“创建一个 FBO，然后把纹理/层级/数组切片按规则挂载上去”。
|
||||
|
||||
## 主要职责
|
||||
|
||||
- 创建并拥有底层 FBO
|
||||
- 维护宽高与采样数元数据
|
||||
- 把颜色、深度、模板附件挂到正确的 attachment point
|
||||
- 暴露 [Bind](Bind.md)、[Unbind](Unbind.md) 和清除辅助方法
|
||||
|
||||
## 当前实现的真实行为
|
||||
|
||||
### 两种初始化路径
|
||||
- 颜色附件最多处理 `16` 个
|
||||
- `renderPass` 参数当前不参与实际创建逻辑
|
||||
- `m_samples` 只做缓存，不驱动 MSAA FBO 特殊路径
|
||||
- 清除方法都会立即绑定当前 FBO，并且不恢复旧绑定
|
||||
- [IsValid](IsValid.md) 只检查 FBO ID 是否非零
|
||||
|
||||
- [`Initialize(const FramebufferDesc&)`](Initialize.md) 直接按 `FramebufferDesc` 组装附件。
|
||||
- [`Initialize(RHIRenderPass*, ...)`](Initialize.md) 从 `RHIResourceView` 数组提取附件信息。
|
||||
## 设计背景
|
||||
|
||||
### 附件绑定策略
|
||||
商业级引擎在 OpenGL 后端通常会把 FBO 当成“运行时组合点”，而不是硬搬 Vulkan/D3D12 的 render pass 规则。原因很现实：
|
||||
|
||||
- 最多处理 `16` 个颜色附件。
|
||||
- 根据 attachment 的 target / layer / mip，选择 `glFramebufferTexture1D`、`glFramebufferTexture2D`、`glFramebufferTextureLayer` 或 `glFramebufferTexture`。
|
||||
- 深度附件如果标记为 `DepthStencil`，会绑定到 `GL_DEPTH_STENCIL_ATTACHMENT`。
|
||||
- OpenGL 的原生对象就是 FBO
|
||||
- 附件绑定粒度高，组合方式灵活
|
||||
- 用 FBO 作为后端真实实体，最容易和统一 RHI 抽象做映射
|
||||
|
||||
### render pass 参数
|
||||
当前实现沿用了这种思路：RHI 继续保留更高层接口，OpenGL 后端则把真正的工作落在 FBO 组装上。
|
||||
|
||||
- `Initialize(RHIRenderPass*, ...)` 当前会忽略 `renderPass` 本身。
|
||||
- 也就是说，这个类在 OpenGL 后端更接近“附件集合对象”，而不是对 Vulkan / D3D12 render pass 语义的完全镜像。
|
||||
## 生命周期
|
||||
|
||||
- [OpenGLFramebuffer()](Constructor.md) 初始化为空对象
|
||||
- [Initialize](Initialize.md) 创建 FBO 并附着资源
|
||||
- [Bind](Bind.md) / [Unbind](Unbind.md) 用于直接切换绑定
|
||||
- [Shutdown](Shutdown.md) 删除 FBO 并重置尺寸缓存
|
||||
|
||||
## 当前限制
|
||||
|
||||
- `Clear*()` 系列函数会直接修改当前 FBO 绑定状态，不会恢复之前的 framebuffer。
|
||||
- `IsValid()` 只检查 FBO id 是否非零，不会再次验证完整性。
|
||||
- 创建失败时返回 `false`，但由调用方或析构来最终清理对象。
|
||||
- 没有 render pass load/store 语义建模
|
||||
- 没有自动恢复前一绑定状态
|
||||
- `samples` 目前没有形成完整的多重采样管理
|
||||
- 对附件兼容性的错误信息较少，只靠 `glCheckFramebufferStatus`
|
||||
|
||||
## 重点方法
|
||||
## 关键方法
|
||||
|
||||
- [Initialize](Initialize.md)
|
||||
- [Bind](Bind.md)
|
||||
@@ -52,6 +68,6 @@
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [OpenGL](../OpenGL.md)
|
||||
- [OpenGLRenderTargetView](../OpenGLRenderTargetView/OpenGLRenderTargetView.md)
|
||||
- [OpenGLDepthStencilView](../OpenGLDepthStencilView/OpenGLDepthStencilView.md)
|
||||
- [OpenGLResourceView](../OpenGLResourceView/OpenGLResourceView.md)
|
||||
- [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md)
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# OpenGLFramebuffer::Shutdown
|
||||
# OpenGLFramebuffer::Shutdown()
|
||||
|
||||
```cpp
|
||||
void Shutdown() override;
|
||||
@@ -6,13 +6,21 @@ void Shutdown() override;
|
||||
|
||||
## 作用
|
||||
|
||||
删除内部 framebuffer object 并重置尺寸状态。
|
||||
释放当前 FBO 并重置尺寸缓存。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 如果 `m_framebuffer != 0`，调用 `glDeleteFramebuffers()`。
|
||||
- 把宽高重置为 `0`，sample 数重置为 `1`。
|
||||
- 如果 `m_framebuffer != 0`，调用 `glDeleteFramebuffers(1, &m_framebuffer)`
|
||||
- 把 `m_framebuffer` 置为 `0`
|
||||
- 把 `m_width`、`m_height` 重置为 `0`
|
||||
- 把 `m_samples` 重置为 `1`
|
||||
- 不清空 `m_desc`
|
||||
|
||||
## 注意事项
|
||||
|
||||
如果上层还保留旧附件关系的语义，只看对象内部 `m_desc` 可能与当前 FBO 生命周期不同步，因为 `Shutdown()` 没有重置这份描述缓存。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Destructor](Destructor.md)
|
||||
- [IsValid](IsValid.md)
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# OpenGLFramebuffer::Unbind
|
||||
# OpenGLFramebuffer::Unbind()
|
||||
|
||||
```cpp
|
||||
void Unbind();
|
||||
@@ -6,12 +6,17 @@ void Unbind();
|
||||
|
||||
## 作用
|
||||
|
||||
解绑当前 framebuffer，把 `GL_FRAMEBUFFER` 绑定回默认 framebuffer `0`。
|
||||
把 `GL_FRAMEBUFFER` 绑定切回默认帧缓冲 `0`。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 直接调用 `glBindFramebuffer(GL_FRAMEBUFFER, 0)`。
|
||||
- 直接调用 `glBindFramebuffer(GL_FRAMEBUFFER, 0)`
|
||||
|
||||
## 设计说明
|
||||
|
||||
OpenGL 后端里“解绑 FBO”通常就意味着回到默认窗口帧缓冲，这和 D3D12/Vulkan 里“结束 render pass”不是一回事。文档里需要明确这层概念差异。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Bind](Bind.md)
|
||||
- [UnbindFramebuffer](UnbindFramebuffer.md)
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# OpenGLFramebuffer::UnbindFramebuffer
|
||||
# OpenGLFramebuffer::UnbindFramebuffer()
|
||||
|
||||
```cpp
|
||||
static void UnbindFramebuffer();
|
||||
@@ -6,12 +6,13 @@ static void UnbindFramebuffer();
|
||||
|
||||
## 作用
|
||||
|
||||
静态辅助函数，把 `GL_FRAMEBUFFER` 解绑回默认 framebuffer。
|
||||
静态解绑当前 `GL_FRAMEBUFFER`。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 直接调用 `glBindFramebuffer(GL_FRAMEBUFFER, 0)`。
|
||||
- 直接执行 `glBindFramebuffer(GL_FRAMEBUFFER, 0)`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [BindFramebuffer](BindFramebuffer.md)
|
||||
- [Unbind](Unbind.md)
|
||||
|
||||
@@ -1,35 +1,112 @@
|
||||
# OpenGLShader::Compile
|
||||
# OpenGLShader::Compile()
|
||||
|
||||
```cpp
|
||||
bool Compile(const void* sourceData, size_t sourceSize, const char* entryPoint, const char* target) override;
|
||||
bool Compile(const void* sourceData,
|
||||
size_t sourceSize,
|
||||
const char* entryPoint,
|
||||
const char* target) override;
|
||||
bool Compile(const char* vertexSource, const char* fragmentSource);
|
||||
bool Compile(const char* vertexSource, const char* fragmentSource, const char* geometrySource);
|
||||
bool Compile(const char* vertexSource,
|
||||
const char* fragmentSource,
|
||||
const char* geometrySource);
|
||||
bool Compile(const char* source, ShaderType type);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
从源码字符串编译并链接 OpenGL shader/program。
|
||||
把 GLSL 源码编译并链接成可用的 OpenGL program。
|
||||
|
||||
## 当前实现行为
|
||||
## 重载 1: 通用 RHI 入口
|
||||
|
||||
- `sourceData` 重载：
|
||||
- 只接受文本源码
|
||||
- 先用 `target` 推断 type
|
||||
- 若失败，再尝试根据 GLSL 源码特征启发式判断 type
|
||||
- graphics 多阶段重载：
|
||||
- 分别创建 shader object
|
||||
- 编译
|
||||
- attach 到同一个 program
|
||||
- link
|
||||
- `Compile(const char*, ShaderType)`：
|
||||
- 适合单阶段 program / compute path / 逐阶段 attach 逻辑
|
||||
```cpp
|
||||
bool Compile(const void* sourceData,
|
||||
size_t sourceSize,
|
||||
const char* entryPoint,
|
||||
const char* target) override;
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
### 当前实现行为
|
||||
|
||||
这里的“类型推断”是启发式的，不应视为稳定资产编译系统。
|
||||
- `sourceData == nullptr` 或 `sourceSize == 0` 时直接返回 `false`
|
||||
- `entryPoint` 被显式忽略
|
||||
- 把字节流拷贝成 `std::string`
|
||||
- 先尝试根据 `target` 解析 `ShaderType`
|
||||
- 若失败，再根据源码中的 GLSL 特征词推断：
|
||||
- `gl_Position` 推断为 Vertex
|
||||
- `gl_FragCoord` / `gl_FragColor` 等推断为 Fragment
|
||||
- `layout(local_size_x` 等推断为 Compute
|
||||
- `EmitVertex` / `gl_in[` 推断为 Geometry
|
||||
- 推断成功后，转发到 `Compile(const char*, ShaderType)`
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 这条路径只支持 GLSL 文本，不负责 HLSL 到 GLSL 的翻译
|
||||
- 类型推断本质上是启发式逻辑，不是强约束编译管线
|
||||
|
||||
## 重载 2: 顶点 + 片元
|
||||
|
||||
```cpp
|
||||
bool Compile(const char* vertexSource, const char* fragmentSource);
|
||||
```
|
||||
|
||||
### 当前实现行为
|
||||
|
||||
- 创建 `GL_VERTEX_SHADER` 与 `GL_FRAGMENT_SHADER`
|
||||
- 分别 `glShaderSource`、`glCompileShader`
|
||||
- 任一阶段编译失败时直接返回 `false`
|
||||
- 编译通过后创建新的 `m_program`
|
||||
- attach 两个 shader 并 link
|
||||
- link 成功后删除临时 shader 对象
|
||||
- 把 `m_uniformsCached` 置为 `false`
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 这条路径不会更新 `m_type`
|
||||
- 如果对象之前已经持有旧 `m_program`，当前实现不会先 `Shutdown()`，因此重复编译不属于严格意义上的“就地重编译”
|
||||
- 失败路径没有对所有临时 OpenGL 对象做完整清理
|
||||
|
||||
## 重载 3: 顶点 + 片元 + 几何
|
||||
|
||||
```cpp
|
||||
bool Compile(const char* vertexSource,
|
||||
const char* fragmentSource,
|
||||
const char* geometrySource);
|
||||
```
|
||||
|
||||
### 当前实现行为
|
||||
|
||||
- 与双阶段重载流程相同，只是额外创建并编译 `GL_GEOMETRY_SHADER`
|
||||
- link 成功后删除 vertex / fragment / geometry 三个 shader 对象
|
||||
- 同样会把 `m_uniformsCached` 置为 `false`
|
||||
|
||||
## 重载 4: 单阶段编译
|
||||
|
||||
```cpp
|
||||
bool Compile(const char* source, ShaderType type);
|
||||
```
|
||||
|
||||
### 当前实现行为
|
||||
|
||||
- 按 `type` 创建对应 shader：
|
||||
- Vertex
|
||||
- Fragment
|
||||
- Geometry
|
||||
- Compute
|
||||
- TessControl
|
||||
- TessEvaluation
|
||||
- 若 `m_program == 0`，先创建 program
|
||||
- attach 当前阶段 shader 并立即 link
|
||||
- 成功后删除临时 shader
|
||||
- 把 `m_type` 设置为传入的 `type`
|
||||
- 把 `m_uniformsCached` 置为 `false`
|
||||
|
||||
### 设计说明
|
||||
|
||||
这条路径允许“先创建 program，再逐阶段 attach + link”的简单装配流程，所以 `OpenGLDevice::CreateShader(...)` 的通用 GLSL 路径可以只给一份源码，再由 `target` / 内容推断阶段类型。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [CompileFromFile](CompileFromFile.md)
|
||||
- [Use](Use.md)
|
||||
- [CompileCompute](CompileCompute.md)
|
||||
- [GetType](GetType.md)
|
||||
- [OpenGLShader](OpenGLShader.md)
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# OpenGLShader::CompileCompute
|
||||
# OpenGLShader::CompileCompute()
|
||||
|
||||
```cpp
|
||||
bool CompileCompute(const char* computeSource);
|
||||
@@ -6,16 +6,30 @@ bool CompileCompute(const char* computeSource);
|
||||
|
||||
## 作用
|
||||
|
||||
编译并链接一个 compute program。
|
||||
编译并链接一个 compute shader program。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 创建 `GL_COMPUTE_SHADER`
|
||||
- 编译后 attach 到新 program
|
||||
- link
|
||||
- 成功后把 `m_type` 设为 `ShaderType::Compute`
|
||||
- 传入 `computeSource` 后执行编译
|
||||
- 编译失败则返回 `false`
|
||||
- 创建新的 `m_program`
|
||||
- attach compute shader 并 link
|
||||
- link 成功后删除临时 shader 对象
|
||||
- 把 `m_type` 设置为 `ShaderType::Compute`
|
||||
- 把 `m_uniformsCached` 置为 `false`
|
||||
|
||||
## 设计说明
|
||||
|
||||
虽然 [Compile](Compile.md) 的单阶段重载也能处理 `ShaderType::Compute`，但 `CompileCompute()` 提供了更直接、更少推断步骤的入口，适合作为后端专用工具方法使用。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 和其他编译入口一样，当前实现不会先销毁旧 `m_program`
|
||||
- 失败日志通过标准输出打印，而不是引擎统一日志系统
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Compile](Compile.md)
|
||||
- [Use](Use.md)
|
||||
- [GetType](GetType.md)
|
||||
|
||||
@@ -1,33 +1,75 @@
|
||||
# OpenGLShader::CompileFromFile
|
||||
# OpenGLShader::CompileFromFile()
|
||||
|
||||
```cpp
|
||||
bool CompileFromFile(const wchar_t* filePath, const char* entryPoint, const char* target) override;
|
||||
bool CompileFromFile(const wchar_t* filePath,
|
||||
const char* entryPoint,
|
||||
const char* target) override;
|
||||
bool CompileFromFile(const char* vertexPath, const char* fragmentPath);
|
||||
bool CompileFromFile(const char* vertexPath, const char* fragmentPath, const char* geometryPath);
|
||||
bool CompileFromFile(const char* vertexPath,
|
||||
const char* fragmentPath,
|
||||
const char* geometryPath);
|
||||
```
|
||||
|
||||
## 作用
|
||||
|
||||
从文件读取 GLSL 源码并构建 OpenGL program。
|
||||
从文件读取 GLSL 源码并编译成可用 program。
|
||||
|
||||
## 当前实现行为
|
||||
## 重载 1: 通用 RHI 文件入口
|
||||
|
||||
- `wchar_t*` 重载：
|
||||
- 把路径转为窄字符串
|
||||
- 根据 `target` 或文件扩展名推断 shader type
|
||||
- 读取整个文件
|
||||
- 走单阶段 `Compile(source, type)` 路径
|
||||
- 多文件 graphics 重载：
|
||||
- 分别读取顶点/片元/几何着色器文件
|
||||
- 再执行多阶段编译和链接
|
||||
```cpp
|
||||
bool CompileFromFile(const wchar_t* filePath,
|
||||
const char* entryPoint,
|
||||
const char* target) override;
|
||||
```
|
||||
|
||||
## 失败路径
|
||||
### 当前实现行为
|
||||
|
||||
- 文件打不开返回 `false`
|
||||
- 无法推断 shader type 返回 `false`
|
||||
- 任一编译或链接失败返回 `false`
|
||||
- `filePath == nullptr` 时直接返回 `false`
|
||||
- `entryPoint` 被忽略
|
||||
- 使用内部 `NarrowAscii()` 把 `wchar_t*` 路径逐字符截断成窄字符
|
||||
- 打开文本文件并读入完整源码
|
||||
- 优先根据 `target` 推断 shader 类型
|
||||
- 若 `target` 不能提供信息，再根据文件扩展名推断：
|
||||
- `.vert` / `.vs.glsl`
|
||||
- `.frag` / `.fs.glsl`
|
||||
- `.geom` / `.gs.glsl`
|
||||
- `.comp` / `.cs.glsl`
|
||||
- `.tesc`
|
||||
- `.tese`
|
||||
- 推断成功后转发到 [Compile](Compile.md) 的单阶段重载
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 路径转换是 ASCII 风格截断，不适合复杂宽字符路径
|
||||
- 没有 include 处理、宏展开或 shader 预处理阶段
|
||||
|
||||
## 重载 2: 顶点 + 片元文件
|
||||
|
||||
```cpp
|
||||
bool CompileFromFile(const char* vertexPath, const char* fragmentPath);
|
||||
```
|
||||
|
||||
### 当前实现行为
|
||||
|
||||
- 分别读取两个文件
|
||||
- 任一文件打不开则返回 `false`
|
||||
- 读入后调用 `Compile(vertexSource, fragmentSource)`
|
||||
|
||||
## 重载 3: 顶点 + 片元 + 几何文件
|
||||
|
||||
```cpp
|
||||
bool CompileFromFile(const char* vertexPath,
|
||||
const char* fragmentPath,
|
||||
const char* geometryPath);
|
||||
```
|
||||
|
||||
### 当前实现行为
|
||||
|
||||
- 与双文件重载相同，只是增加 geometry 文件读取
|
||||
- 读入成功后调用三阶段 [Compile](Compile.md)
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Compile](Compile.md)
|
||||
- [CompileCompute](CompileCompute.md)
|
||||
- [GetType](GetType.md)
|
||||
- [OpenGLShader](OpenGLShader.md)
|
||||
|
||||
@@ -1,28 +1,24 @@
|
||||
# OpenGLShader::OpenGLShader()
|
||||
|
||||
构造对象。
|
||||
|
||||
```cpp
|
||||
OpenGLShader();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
构造一个尚未编译 program 的 shader 对象。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 把 `m_program` 置为 `0`
|
||||
- 把 `m_uniformsCached` 置为 `false`
|
||||
- `m_type` 依赖成员默认值，初始为 `ShaderType::Vertex`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLShader.h>
|
||||
## 注意事项
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLShader object;
|
||||
}
|
||||
```
|
||||
初始 `m_type` 并不意味着对象已经拥有 vertex shader program；它只是默认成员值。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLShader.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [IsValid](IsValid.md)
|
||||
- [Compile](Compile.md)
|
||||
|
||||
@@ -1,29 +1,19 @@
|
||||
# OpenGLShader::~OpenGLShader()
|
||||
|
||||
销毁对象并释放相关资源。
|
||||
|
||||
```cpp
|
||||
~OpenGLShader() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
销毁 shader 对象并释放其 program。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLShader.h>
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLShader object;
|
||||
// 对象离开作用域时会自动触发析构。
|
||||
}
|
||||
```
|
||||
- 析构函数直接调用 [Shutdown](Shutdown.md)
|
||||
- 如果 `m_program != 0`，会在 `Shutdown()` 中执行 `glDeleteProgram`
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLShader.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
- [OpenGLShader](OpenGLShader.md)
|
||||
|
||||
@@ -1,30 +1,23 @@
|
||||
# OpenGLShader::GetID
|
||||
|
||||
获取相关状态或对象。
|
||||
# OpenGLShader::GetID()
|
||||
|
||||
```cpp
|
||||
unsigned int GetID() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回底层 OpenGL program ID。
|
||||
|
||||
**返回：** `unsigned int` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接返回 `m_program`
|
||||
- `0` 表示当前没有成功创建 program
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLShader.h>
|
||||
## 使用场景
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLShader object;
|
||||
// 根据上下文补齐参数后调用 OpenGLShader::GetID(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
集成测试、后端专用工具和 [OpenGLPipelineState](../OpenGLPipelineState/OpenGLPipelineState.md) 会直接消费这个值，把它传给 `glUseProgram` 或 [AttachShader](../OpenGLPipelineState/AttachShader.md)。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLShader.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetNativeHandle](GetNativeHandle.md)
|
||||
- [Use](Use.md)
|
||||
|
||||
@@ -1,30 +1,23 @@
|
||||
# OpenGLShader::GetNativeHandle
|
||||
|
||||
获取相关状态或对象。
|
||||
# OpenGLShader::GetNativeHandle()
|
||||
|
||||
```cpp
|
||||
void* GetNativeHandle() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
以统一 RHI 句柄形式返回底层 program。
|
||||
|
||||
**返回：** `void*` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 把 `m_program` 转成 `uintptr_t`
|
||||
- 再转成 `void*` 返回
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLShader.h>
|
||||
## 注意事项
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLShader object;
|
||||
// 根据上下文补齐参数后调用 OpenGLShader::GetNativeHandle(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
这个“native handle”本质上就是 OpenGL program ID，而不是独立的 COM/驱动对象指针。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLShader.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetID](GetID.md)
|
||||
- [IsValid](IsValid.md)
|
||||
|
||||
@@ -1,30 +1,26 @@
|
||||
# OpenGLShader::GetType
|
||||
|
||||
获取相关状态或对象。
|
||||
# OpenGLShader::GetType()
|
||||
|
||||
```cpp
|
||||
ShaderType GetType() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回对象当前记录的 shader 类型。
|
||||
|
||||
**返回：** `ShaderType` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接返回成员 `m_type`
|
||||
- `CompileCompute()` 会把它设为 `Compute`
|
||||
- `Compile(const char*, ShaderType)` 会把它设为传入类型
|
||||
- 顶点/片元或顶点/片元/几何这两类图形 program 重载不会更新它
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLShader.h>
|
||||
## 注意事项
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLShader object;
|
||||
// 根据上下文补齐参数后调用 OpenGLShader::GetType(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
这意味着 `GetType()` 对“完整 graphics program”并不是强语义描述。一个已经成功编译的 vertex + fragment program，`GetType()` 仍可能保持默认的 `Vertex`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLShader.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [Compile](Compile.md)
|
||||
- [CompileCompute](CompileCompute.md)
|
||||
- [OpenGLShader](OpenGLShader.md)
|
||||
|
||||
@@ -1,31 +1,25 @@
|
||||
# OpenGLShader::GetUniformInfo
|
||||
|
||||
获取相关状态或对象。
|
||||
# OpenGLShader::GetUniformInfo()
|
||||
|
||||
```cpp
|
||||
const UniformInfo* GetUniformInfo(const char* name) const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `name` - 参数语义详见头文件声明。
|
||||
按名称查询单个 uniform 的反射信息。
|
||||
|
||||
**返回：** `const UniformInfo*` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 先调用 [GetUniformInfos](GetUniformInfos.md) 对应的缓存流程
|
||||
- 对 `m_uniformInfos` 做线性遍历
|
||||
- 名称匹配成功时返回指向缓存元素的指针
|
||||
- 否则返回 `nullptr`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLShader.h>
|
||||
## 设计说明
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLShader object;
|
||||
// 根据上下文补齐参数后调用 OpenGLShader::GetUniformInfo(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
这里强调的是“足够可用的查询接口”，而不是高性能反射数据库。对于运行时材质系统来说，通常在 program 创建后查询少量 uniform 信息已经够用。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLShader.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetUniformInfos](GetUniformInfos.md)
|
||||
- [GetUniformLocation](GetUniformLocation.md)
|
||||
|
||||
@@ -1,30 +1,34 @@
|
||||
# OpenGLShader::GetUniformInfos
|
||||
|
||||
获取相关状态或对象。
|
||||
# OpenGLShader::GetUniformInfos()
|
||||
|
||||
```cpp
|
||||
const std::vector<UniformInfo>& GetUniformInfos() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回当前 program 的 uniform 反射结果集合。
|
||||
|
||||
**返回：** `const std::vector<UniformInfo>&` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 首次调用时执行 `CacheUniformInfos()`
|
||||
- 通过 `glGetProgramInterfaceiv(..., GL_UNIFORM, GL_ACTIVE_RESOURCES, ...)` 枚举 uniform
|
||||
- 对每个资源读取：
|
||||
- 名称长度
|
||||
- 类型
|
||||
- 偏移
|
||||
- 数组大小
|
||||
- 根据部分常见 GL 类型估算 `size`
|
||||
- 把结果缓存到 `m_uniformInfos`
|
||||
- 后续调用直接返回缓存
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLShader.h>
|
||||
## 需要特别注意
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLShader object;
|
||||
// 根据上下文补齐参数后调用 OpenGLShader::GetUniformInfos(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- `bindPoint` 当前使用的是枚举到的资源索引，不等同于显式 layout binding
|
||||
- `size` 只覆盖部分常见标量、向量、矩阵类型，其他类型可能得到 `0`
|
||||
- 这套缓存会在成功编译后重置，并在 [Shutdown](Shutdown.md) 时清空
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLShader.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetUniformInfo](GetUniformInfo.md)
|
||||
- [GetUniformLocation](GetUniformLocation.md)
|
||||
- [OpenGLShader](OpenGLShader.md)
|
||||
|
||||
@@ -1,31 +1,24 @@
|
||||
# OpenGLShader::GetUniformLocation
|
||||
|
||||
获取相关状态或对象。
|
||||
# OpenGLShader::GetUniformLocation()
|
||||
|
||||
```cpp
|
||||
int GetUniformLocation(const char* name) const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `name` - 参数语义详见头文件声明。
|
||||
查询指定 uniform 在 program 中的位置。
|
||||
|
||||
**返回：** `int` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接调用 `glGetUniformLocation(m_program, name)`
|
||||
- 不依赖反射缓存
|
||||
- 返回 OpenGL 原生位置值
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLShader.h>
|
||||
## 适用场景
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLShader object;
|
||||
// 根据上下文补齐参数后调用 OpenGLShader::GetUniformLocation(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
当上层已经知道要设置哪个 uniform，并且只想直接调用 `glUniform*` 时，这个方法比先走 [GetUniformInfo](GetUniformInfo.md) 更直接。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLShader.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [Use](Use.md)
|
||||
- [GetUniformInfo](GetUniformInfo.md)
|
||||
|
||||
@@ -1,30 +1,22 @@
|
||||
# OpenGLShader::IsValid
|
||||
|
||||
查询当前状态。
|
||||
# OpenGLShader::IsValid()
|
||||
|
||||
```cpp
|
||||
bool IsValid() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
判断当前对象是否已经持有一个非零的 OpenGL program。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接检查 `m_program != 0`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLShader.h>
|
||||
## 注意事项
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLShader object;
|
||||
// 根据上下文补齐参数后调用 OpenGLShader::IsValid(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
它只验证“是否有 program ID”，不验证链接结果是否仍然可用，也不检查 program 是否匹配当前上下文状态。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLShader.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetID](GetID.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
|
||||
@@ -6,42 +6,70 @@
|
||||
|
||||
**头文件**: `XCEngine/RHI/OpenGL/OpenGLShader.h`
|
||||
|
||||
**描述**: OpenGL 后端的着色器/程序封装，负责 GLSL 编译、链接、基础反射和 program 使用。
|
||||
**描述**: OpenGL 后端的 shader / program 封装器，负责 GLSL 源码读取、编译、链接，以及一套轻量级的 uniform 反射查询。
|
||||
|
||||
## 概览
|
||||
|
||||
`OpenGLShader` 同时承担了“单阶段 shader 编译器”和“完整 graphics/compute program 封装器”两种职责：
|
||||
`OpenGLShader` 当前同时承担两类职责：
|
||||
|
||||
- 多阶段 graphics program：通过顶点/片元或顶点/片元/几何路径构建
|
||||
- 单阶段 shader：通过 `Compile(const void*, size_t, ...)` 或 `Compile(const char*, ShaderType)` 推断类型后编译并链接
|
||||
- compute program：通过 [`CompileCompute`](CompileCompute.md) 构建
|
||||
- 单阶段 shader 的编译入口
|
||||
- 完整 graphics / compute program 的最终持有者
|
||||
|
||||
它不是“离线 shader 资产系统”，也不是“可复用的原生 shader object 缓存”。当前实现更偏向运行时直接把 GLSL 文本编译成 program，然后尽快给命令列表和管线状态对象使用。
|
||||
|
||||
## 主要能力
|
||||
|
||||
- 直接从字符串编译 vertex / fragment / geometry / compute
|
||||
- 从文件读取 GLSL 源码
|
||||
- 通过 `target`、扩展名或源码内容推断阶段类型
|
||||
- 暴露 program ID 给后端专用路径
|
||||
- 懒加载 uniform 反射信息
|
||||
|
||||
## 当前实现的真实行为
|
||||
|
||||
- [`CompileFromFile`](CompileFromFile.md) 会根据 `target` 或文件扩展名推断 shader type
|
||||
- [`Compile`](Compile.md) 的 `sourceData` 路径会根据 `target` 或 GLSL 源码特征猜测 shader type
|
||||
- `Compile(const char*, ShaderType)` 会把 shader attach 到 `m_program` 上并立即 link
|
||||
- `GetUniformInfos()` 通过 `glGetProgramInterfaceiv(GL_UNIFORM, ...)` 做反射
|
||||
- `Use()` 只是 `glUseProgram(m_program)`
|
||||
- [CompileFromFile](CompileFromFile.md) 的通用 RHI 入口会忽略 `entryPoint`
|
||||
- [Compile](Compile.md) 的通用 RHI 入口同样忽略 `entryPoint`
|
||||
- 单文件 / 单源码编译路径依赖启发式类型推断
|
||||
- 图形 program 的双阶段/三阶段重载不会更新 `m_type`
|
||||
- 失败日志通过 `std::cout` 输出
|
||||
- 当前实现不保证“重复编译同一对象”时的资源清理完整性
|
||||
|
||||
## 设计说明
|
||||
## 设计背景
|
||||
|
||||
当前实现追求的是“足够统一、足够易用”，而不是做一套完整的 shader asset pipeline。因此类型推断里存在明显的启发式逻辑，文档里必须明确说明，不应把它误解成强约束编译系统。
|
||||
在跨后端 RHI 里，D3D12/Vulkan 往往会把 shader bytecode、pipeline 创建和反射拆得更细；而 OpenGL 更常见的运行时模型是“把 GLSL 文本直接交给驱动编译”。`OpenGLShader` 采用的是后一种思路：
|
||||
|
||||
- 先保证最短路径可编译、可绑定、可调试
|
||||
- 再通过 `GetUniformInfos()` 提供最基本的反射
|
||||
- 把复杂的 shader 资产管线留给更高层系统未来扩展
|
||||
|
||||
这种设计对原型阶段、测试样例和教学型 API 文档尤其友好，因为调用链短、可见性高。
|
||||
|
||||
## 生命周期
|
||||
|
||||
- [OpenGLShader()](Constructor.md) 初始化为空 program
|
||||
- 通过 [Compile](Compile.md)、[CompileFromFile](CompileFromFile.md) 或 [CompileCompute](CompileCompute.md) 创建 program
|
||||
- 通过 [Use](Use.md) 绑定到当前上下文
|
||||
- 通过 [GetUniformInfos](GetUniformInfos.md) / [GetUniformLocation](GetUniformLocation.md) 查询反射信息
|
||||
- [Shutdown](Shutdown.md) 删除 program 并清空缓存
|
||||
|
||||
## 当前限制
|
||||
|
||||
- `Compile(const void*, size_t, ...)` 只处理 GLSL 文本，不负责 HLSL 到 GLSL 转译
|
||||
- shader type 推断带启发式性质，失败时会直接返回 `false`
|
||||
- 链接错误和编译错误当前主要输出到标准输出
|
||||
- 只支持 GLSL 文本编译
|
||||
- 没有 include、宏预处理、变体缓存或离线编译
|
||||
- `GetType()` 对图形 program 不是严格可靠的语义来源
|
||||
- 失败路径的临时对象清理较粗糙
|
||||
- 路径窄化逻辑不适合复杂 Unicode 文件名
|
||||
|
||||
## 重点公共方法
|
||||
## 关键方法
|
||||
|
||||
- [CompileFromFile](CompileFromFile.md)
|
||||
- [Compile](Compile.md)
|
||||
- [CompileFromFile](CompileFromFile.md)
|
||||
- [CompileCompute](CompileCompute.md)
|
||||
- [Use](Use.md)
|
||||
- [GetUniformInfos](GetUniformInfos.md)
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [OpenGLDevice](../OpenGLDevice/OpenGLDevice.md)
|
||||
- [OpenGLPipelineState](../OpenGLPipelineState/OpenGLPipelineState.md)
|
||||
- [OpenGLCommandList](../OpenGLCommandList/OpenGLCommandList.md)
|
||||
|
||||
@@ -1,30 +1,26 @@
|
||||
# OpenGLShader::Shutdown
|
||||
|
||||
关闭并清理内部状态。
|
||||
# OpenGLShader::Shutdown()
|
||||
|
||||
```cpp
|
||||
void Shutdown() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLShader.h`，当前页面用于固定 `OpenGLShader` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
释放当前 program 和 uniform 缓存。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 如果 `m_program != 0`，调用 `glDeleteProgram(m_program)`
|
||||
- 把 `m_program` 置为 `0`
|
||||
- 清空 `m_uniformInfos`
|
||||
- 把 `m_uniformsCached` 置为 `false`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLShader.h>
|
||||
## 设计说明
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLShader object;
|
||||
// 根据上下文补齐参数后调用 OpenGLShader::Shutdown(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
对于 `OpenGLShader`，`Shutdown()` 不只是释放 GPU program，也是把反射缓存完全作废。任何新的编译结果都应该重新建立 uniform 视图。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLShader.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [Destructor](Destructor.md)
|
||||
- [Compile](Compile.md)
|
||||
- [GetUniformInfos](GetUniformInfos.md)
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# OpenGLShader::Use
|
||||
# OpenGLShader::Use()
|
||||
|
||||
```cpp
|
||||
void Use() const;
|
||||
@@ -6,13 +6,19 @@ void Use() const;
|
||||
|
||||
## 作用
|
||||
|
||||
把当前 shader program 设为活动 program。
|
||||
把当前 program 绑定为活动 shader program。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
直接调用 `glUseProgram(m_program)`。
|
||||
- 直接执行 `glUseProgram(m_program)`
|
||||
- 不检查 `m_program` 是否为 `0`
|
||||
- 不做上下文切换
|
||||
|
||||
## 何时使用
|
||||
|
||||
在后端专用 OpenGL 代码里，`Use()` 是最直接的 program 绑定方式。若走统一 RHI 流程，则更常见的入口是 [OpenGLPipelineState::Bind](../OpenGLPipelineState/Bind.md)。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [Compile](Compile.md)
|
||||
- [OpenGLPipelineState::Bind](../OpenGLPipelineState/Bind.md)
|
||||
- [GetID](GetID.md)
|
||||
- [OpenGLPipelineState](../OpenGLPipelineState/OpenGLPipelineState.md)
|
||||
|
||||
@@ -1,28 +1,25 @@
|
||||
# OpenGLSwapChain::OpenGLSwapChain()
|
||||
|
||||
构造对象。
|
||||
|
||||
```cpp
|
||||
OpenGLSwapChain();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
构造一个尚未绑定窗口与设备的 OpenGL 交换链包装对象。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 把 `m_device`、`m_hwnd`、`m_backBufferTexture` 置为 `nullptr`
|
||||
- 把 `m_width`、`m_height` 置为 `0`
|
||||
- 不创建 OpenGL 上下文
|
||||
- 不分配默认帧缓冲，也不创建纹理
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
|
||||
## 设计说明
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLSwapChain object;
|
||||
}
|
||||
```
|
||||
构造函数保持“零成本”，真正的窗口接入与资源分配都放在 [Initialize](Initialize.md) 中完成。这种分层更适合测试，也更符合引擎里“先 new，再显式 Initialize”的对象生命周期。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLSwapChain.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [OpenGLSwapChain](OpenGLSwapChain.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,29 +1,24 @@
|
||||
# OpenGLSwapChain::~OpenGLSwapChain()
|
||||
|
||||
销毁对象并释放相关资源。
|
||||
|
||||
```cpp
|
||||
~OpenGLSwapChain() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
销毁对象，并尝试释放当前交换链包装器持有的资源。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 析构函数内部直接调用 [Shutdown](Shutdown.md)
|
||||
- 如果 `m_backBufferTexture` 仍然存在，会在 `Shutdown()` 中被删除
|
||||
- 不会主动查询窗口系统状态，也不会销毁窗口本身
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
|
||||
## 使用建议
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLSwapChain object;
|
||||
// 对象离开作用域时会自动触发析构。
|
||||
}
|
||||
```
|
||||
如果上层已经显式调用过 `Shutdown()`，析构时再次进入该流程也是安全的，因为实现对空指针做了保护。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLSwapChain.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [Shutdown](Shutdown.md)
|
||||
- [OpenGLSwapChain](OpenGLSwapChain.md)
|
||||
|
||||
@@ -1,30 +1,30 @@
|
||||
# OpenGLSwapChain::GetCurrentBackBuffer
|
||||
|
||||
获取相关状态或对象。
|
||||
# OpenGLSwapChain::GetCurrentBackBuffer()
|
||||
|
||||
```cpp
|
||||
RHITexture* GetCurrentBackBuffer() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回当前对外暴露的 back buffer 纹理对象。
|
||||
|
||||
**返回：** `RHITexture*` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接返回成员 `m_backBufferTexture`
|
||||
- 返回类型是 `RHITexture*`，但实际对象类型是 `OpenGLTexture`
|
||||
- 如果尚未初始化或已经关闭，返回值可能为 `nullptr`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
|
||||
## 设计说明
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLSwapChain object;
|
||||
// 根据上下文补齐参数后调用 OpenGLSwapChain::GetCurrentBackBuffer(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
OpenGL 默认窗口帧缓冲本身不适合作为统一的 `RHITexture` 直接暴露，所以当前后端维护了一张代理纹理。上层渲染代码、RTV 创建、截图流程都通过这张纹理继续复用跨后端接口。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 这不是 Win32/WGL 默认帧缓冲句柄本身
|
||||
- [Present](Present.md) 只有在这张纹理有效且资源状态满足当前实现约定时，才会把它 blit 到默认帧缓冲
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLSwapChain.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [Present](Present.md)
|
||||
- [OpenGLTexture](../OpenGLTexture/OpenGLTexture.md)
|
||||
- [OpenGLSwapChain](OpenGLSwapChain.md)
|
||||
|
||||
@@ -1,30 +1,29 @@
|
||||
# OpenGLSwapChain::GetCurrentBackBufferIndex
|
||||
|
||||
获取相关状态或对象。
|
||||
# OpenGLSwapChain::GetCurrentBackBufferIndex()
|
||||
|
||||
```cpp
|
||||
uint32_t GetCurrentBackBufferIndex() const override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回当前 back buffer 索引。
|
||||
|
||||
**返回：** `uint32_t` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 固定返回 `0`
|
||||
- 不随 [Present](Present.md) 调用变化
|
||||
- 不维护真正的双缓冲或多缓冲轮换状态
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
|
||||
## 设计说明
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLSwapChain object;
|
||||
// 根据上下文补齐参数后调用 OpenGLSwapChain::GetCurrentBackBufferIndex(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
这是为了满足 `RHISwapChain` 统一接口而保留的占位实现。对 OpenGL 后端来说，当前对象更像“单一窗口呈现入口”，而不是真实的多缓冲交换链。
|
||||
|
||||
## 注意事项
|
||||
|
||||
如果上层逻辑假设索引会像 D3D12/Vulkan 一样轮换，就会得到错误结论。当前 OpenGL 路径应视为单 back buffer 语义。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLSwapChain.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetCurrentBackBuffer](GetCurrentBackBuffer.md)
|
||||
- [Present](Present.md)
|
||||
- [OpenGLSwapChain](OpenGLSwapChain.md)
|
||||
|
||||
@@ -1,30 +1,24 @@
|
||||
# OpenGLSwapChain::GetHeight
|
||||
|
||||
获取相关状态或对象。
|
||||
# OpenGLSwapChain::GetHeight()
|
||||
|
||||
```cpp
|
||||
int GetHeight() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回交换链对象当前缓存的高度。
|
||||
|
||||
**返回：** `int` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接返回成员 `m_height`
|
||||
- 这个值来源于 [Initialize](Initialize.md) 或 [Resize](Resize.md)
|
||||
- 不会实时查询窗口客户区尺寸
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
|
||||
## 注意事项
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLSwapChain object;
|
||||
// 根据上下文补齐参数后调用 OpenGLSwapChain::GetHeight(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
由于 [Resize](Resize.md) 只更新缓存值而不重建内部纹理，所以这里返回的高度可能与 `m_backBufferTexture` 实际尺寸不一致。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLSwapChain.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetWidth](GetWidth.md)
|
||||
- [Resize](Resize.md)
|
||||
|
||||
@@ -1,30 +1,24 @@
|
||||
# OpenGLSwapChain::GetNativeHandle
|
||||
|
||||
获取相关状态或对象。
|
||||
# OpenGLSwapChain::GetNativeHandle()
|
||||
|
||||
```cpp
|
||||
void* GetNativeHandle() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回底层原生窗口句柄。
|
||||
|
||||
**返回：** `void*` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接返回 `m_hwnd`
|
||||
- 在 Win32 路径下，这个值本质上是 `HWND`
|
||||
- 返回值类型被擦除为 `void*`，以便匹配通用 RHI 接口
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
|
||||
## 设计说明
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLSwapChain object;
|
||||
// 根据上下文补齐参数后调用 OpenGLSwapChain::GetNativeHandle(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
对于显式图形 API，`GetNativeHandle()` 往往返回 swap chain 或平台 surface。当前 OpenGL 实现里更有价值的原生对象是窗口本身，因为真正的呈现由窗口上下文和系统 `SwapBuffers` 驱动。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLSwapChain.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [SwapBuffers](SwapBuffers.md)
|
||||
- [OpenGLSwapChain](OpenGLSwapChain.md)
|
||||
|
||||
@@ -1,30 +1,24 @@
|
||||
# OpenGLSwapChain::GetWidth
|
||||
|
||||
获取相关状态或对象。
|
||||
# OpenGLSwapChain::GetWidth()
|
||||
|
||||
```cpp
|
||||
int GetWidth() const;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
返回交换链对象当前缓存的宽度。
|
||||
|
||||
**返回：** `int` - 返回值语义详见头文件声明。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 直接返回成员 `m_width`
|
||||
- 这个值由 [Initialize](Initialize.md) 和 [Resize](Resize.md) 写入
|
||||
- 不会主动同步窗口系统或内部纹理的真实宽度
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
|
||||
## 注意事项
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLSwapChain object;
|
||||
// 根据上下文补齐参数后调用 OpenGLSwapChain::GetWidth(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
在当前实现里，它表示“逻辑呈现尺寸”，不是严格意义上的默认帧缓冲查询结果。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLSwapChain.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetHeight](GetHeight.md)
|
||||
- [Resize](Resize.md)
|
||||
|
||||
@@ -1,34 +1,50 @@
|
||||
# OpenGLSwapChain::Initialize
|
||||
|
||||
初始化内部状态。
|
||||
# OpenGLSwapChain::Initialize()
|
||||
|
||||
```cpp
|
||||
bool Initialize(OpenGLDevice* device, HWND window, int width, int height);
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `device` - 参数语义详见头文件声明。
|
||||
- `window` - 参数语义详见头文件声明。
|
||||
- `width` - 参数语义详见头文件声明。
|
||||
- `height` - 参数语义详见头文件声明。
|
||||
把交换链包装器绑定到指定的 OpenGL 设备和窗口，并按需创建 back buffer 代理纹理。
|
||||
|
||||
**返回：** `bool` - 返回值语义详见头文件声明。
|
||||
## 参数
|
||||
|
||||
**示例：**
|
||||
- `device`: 呈现所依赖的 `OpenGLDevice`
|
||||
- `window`: Win32 窗口句柄
|
||||
- `width`: 初始宽度
|
||||
- `height`: 初始高度
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
|
||||
## 返回值
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLSwapChain object;
|
||||
// 根据上下文补齐参数后调用 OpenGLSwapChain::Initialize(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
`bool`。当前实现始终返回 `true`。
|
||||
|
||||
## 当前实现行为
|
||||
|
||||
- 直接缓存 `device`、`window`、`width`、`height`
|
||||
- 如果 `m_backBufferTexture` 为空，则 new 一个 `OpenGLTexture`
|
||||
- 纹理固定按以下参数初始化：
|
||||
- 类型 `OpenGLTextureType::Texture2D`
|
||||
- 尺寸 `width x height`
|
||||
- `depth = 1`
|
||||
- `mipLevels = 1`
|
||||
- 格式 `OpenGLFormat::RGBA8`
|
||||
- 初始数据 `nullptr`
|
||||
- 不会检查 `device` 或 `window` 是否为空
|
||||
- 不会调用 `MakeContextCurrent()`
|
||||
- 不会检查 `OpenGLTexture::Initialize(...)` 的返回值
|
||||
|
||||
## 设计说明
|
||||
|
||||
这里创建的是“供引擎上层引用的 back buffer 代理纹理”，不是 WGL 默认帧缓冲本体。这样做可以让 `GetCurrentBackBuffer()`、截图和资源视图创建继续沿用统一的纹理接口。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 如果对象已经初始化过，再次调用不会自动重建纹理
|
||||
- 因此重复初始化到新尺寸时，缓存的 `m_width` / `m_height` 可能和旧纹理尺寸不一致
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLSwapChain.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetCurrentBackBuffer](GetCurrentBackBuffer.md)
|
||||
- [Resize](Resize.md)
|
||||
- [OpenGLTexture](../OpenGLTexture/OpenGLTexture.md)
|
||||
|
||||
@@ -6,38 +6,75 @@
|
||||
|
||||
**头文件**: `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`
|
||||
|
||||
**描述**: 定义 `XCEngine/RHI/OpenGL` 子目录中的 `OpenGLSwapChain` public API。
|
||||
**描述**: Win32 OpenGL 后端的交换链包装器；它把默认窗口帧缓冲与一个可选的 back buffer 代理纹理统一到 `RHISwapChain` 抽象下。
|
||||
|
||||
## 概述
|
||||
## 概览
|
||||
|
||||
`OpenGLSwapChain.h` 是 `XCEngine/RHI/OpenGL` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
|
||||
在 D3D12 或 Vulkan 里，swap chain 往往意味着“由驱动管理的多张呈现图像”。当前 `OpenGLSwapChain` 不是这种模型。
|
||||
|
||||
## 声明概览
|
||||
它的真实工作方式更接近：
|
||||
|
||||
| 声明 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `PresentMode` | `enum class` | 头文件中的公开声明。 |
|
||||
| `SurfaceFormat` | `enum class` | 头文件中的公开声明。 |
|
||||
| `OpenGLSwapChain` | `class` | 继承自 `RHISwapChain` 的公开声明。 |
|
||||
- 窗口系统拥有默认帧缓冲
|
||||
- 引擎另外维护一张 `OpenGLTexture` 作为 `GetCurrentBackBuffer()` 的返回对象
|
||||
- [Present](Present.md) 视情况把这张纹理 blit 到默认帧缓冲
|
||||
- 最后调用 Win32 `SwapBuffers`
|
||||
|
||||
## 公共方法
|
||||
这种设计的重点不是模拟一份完整的显式 API 交换链，而是让上层渲染框架、测试基架和截图工具继续通过统一的 `RHISwapChain` 接口工作。
|
||||
|
||||
| 方法 | 描述 |
|
||||
|------|------|
|
||||
| [OpenGLSwapChain()](Constructor.md) | 构造对象。 |
|
||||
| [~OpenGLSwapChain()](Destructor.md) | 销毁对象并释放相关资源。 |
|
||||
| [Initialize](Initialize.md) | 初始化内部状态。 |
|
||||
| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
|
||||
| [Present](Present.md) | 公开方法，详见头文件声明。 |
|
||||
| [SwapBuffers](SwapBuffers.md) | 公开方法，详见头文件声明。 |
|
||||
| [Resize](Resize.md) | 公开方法，详见头文件声明。 |
|
||||
| [GetCurrentBackBufferIndex](GetCurrentBackBufferIndex.md) | 获取相关状态或对象。 |
|
||||
| [GetCurrentBackBuffer](GetCurrentBackBuffer.md) | 获取相关状态或对象。 |
|
||||
| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
|
||||
| [GetWidth](GetWidth.md) | 获取相关状态或对象。 |
|
||||
| [GetHeight](GetHeight.md) | 获取相关状态或对象。 |
|
||||
## 主要职责
|
||||
|
||||
- 记录 `OpenGLDevice*`、`HWND` 和当前逻辑尺寸
|
||||
- 按需创建一张 `RGBA8` 的 back buffer 代理纹理
|
||||
- 对外暴露 [GetCurrentBackBuffer](GetCurrentBackBuffer.md) 与 [GetCurrentBackBufferIndex](GetCurrentBackBufferIndex.md)
|
||||
- 在 [Present](Present.md) 中把代理纹理复制到默认帧缓冲
|
||||
- 通过 [SwapBuffers](SwapBuffers.md) 调用系统呈现
|
||||
|
||||
## 当前实现的真实行为
|
||||
|
||||
- 只覆盖 Win32 路径，`GetNativeHandle()` 返回 `HWND`
|
||||
- `PresentMode` / `SurfaceFormat` 两个枚举当前只停留在头文件层面，没有参与实际创建流程
|
||||
- [GetCurrentBackBufferIndex](GetCurrentBackBufferIndex.md) 永远返回 `0`
|
||||
- [Resize](Resize.md) 只更新缓存宽高，不重建 `m_backBufferTexture`
|
||||
- [Present](Present.md) 忽略 `syncInterval` 与 `flags`
|
||||
- 当 `m_backBufferTexture` 不满足当前约定条件时，`Present()` 只会直接交换默认窗口缓冲
|
||||
- [Shutdown](Shutdown.md) 释放代理纹理并断开设备/窗口引用，但不会把宽高清零
|
||||
|
||||
## 设计背景
|
||||
|
||||
OpenGL 的默认窗口帧缓冲由上下文和窗口系统维护，不能像显式 API 那样把每一张 back buffer 都作为标准资源对象稳定暴露。当前实现采用“代理纹理 + Present 时复制”的策略，主要收益有两点：
|
||||
|
||||
- 上层系统仍然可以把 back buffer 当作 `RHITexture` 使用
|
||||
- 资源视图、截图、离屏渲染等路径可以复用统一的纹理与视图抽象
|
||||
|
||||
这是一种很典型的跨后端工程折中：先保证 API 统一和可用性，再逐步增强平台特性。
|
||||
|
||||
## 生命周期
|
||||
|
||||
- [OpenGLSwapChain()](Constructor.md) 把成员初始化为空状态
|
||||
- [Initialize](Initialize.md) 缓存设备/窗口并创建代理纹理
|
||||
- 渲染期间通过 [GetCurrentBackBuffer](GetCurrentBackBuffer.md) 暴露纹理给 RTV、截图和测试流程
|
||||
- [Present](Present.md) 负责把代理纹理内容提交到默认窗口帧缓冲
|
||||
- [Shutdown](Shutdown.md) 释放代理纹理
|
||||
|
||||
## 当前限制
|
||||
|
||||
- 不是实际多缓冲 swap chain
|
||||
- 不提供轮换帧索引
|
||||
- 不支持真正的 vsync / mailbox / fifo 策略切换
|
||||
- `Resize()` 与内部纹理尺寸可能失配
|
||||
- 缺少严格的错误处理和状态校验
|
||||
|
||||
## 关键方法
|
||||
|
||||
- [Initialize](Initialize.md)
|
||||
- [Present](Present.md)
|
||||
- [SwapBuffers](SwapBuffers.md)
|
||||
- [Resize](Resize.md)
|
||||
- [GetCurrentBackBuffer](GetCurrentBackBuffer.md)
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [当前目录](../OpenGL.md) - 返回 `OpenGL` 平行目录
|
||||
- [API 总索引](../../../../main.md) - 返回顶层索引
|
||||
- [OpenGL](../OpenGL.md)
|
||||
- [OpenGLDevice](../OpenGLDevice/OpenGLDevice.md)
|
||||
- [OpenGLTexture](../OpenGLTexture/OpenGLTexture.md)
|
||||
- [OpenGLScreenshot](../OpenGLScreenshot/OpenGLScreenshot.md)
|
||||
|
||||
@@ -1,32 +1,47 @@
|
||||
# OpenGLSwapChain::Present
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
# OpenGLSwapChain::Present()
|
||||
|
||||
```cpp
|
||||
void Present(uint32_t syncInterval = 1, uint32_t flags = 0) override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `syncInterval` - 参数语义详见头文件声明。
|
||||
- `flags` - 参数语义详见头文件声明。
|
||||
把当前可呈现内容提交到窗口系统。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 参数
|
||||
|
||||
**示例：**
|
||||
- `syncInterval`: 保留给统一接口；当前未使用
|
||||
- `flags`: 保留给统一接口；当前未使用
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
|
||||
## 当前实现行为
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLSwapChain object;
|
||||
// 根据上下文补齐参数后调用 OpenGLSwapChain::Present(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 先忽略 `syncInterval` 和 `flags`
|
||||
- 如果 `m_device` 非空，先调用 `m_device->MakeContextCurrent()`
|
||||
- 然后检查是否满足“从代理纹理 blit 到默认帧缓冲”的条件：
|
||||
- `m_backBufferTexture != nullptr`
|
||||
- `m_backBufferTexture->GetID() != 0`
|
||||
- `m_backBufferTexture->GetState() != ResourceStates::Common`
|
||||
- 如果满足条件：
|
||||
- 创建临时 `GL_READ_FRAMEBUFFER`
|
||||
- 把代理纹理挂到 `GL_COLOR_ATTACHMENT0`
|
||||
- 设置 `glReadBuffer(GL_COLOR_ATTACHMENT0)`
|
||||
- 把绘制目标切回默认帧缓冲 `0`
|
||||
- 调用 `glBlitFramebuffer(...)` 复制颜色内容
|
||||
- 删除临时 FBO
|
||||
- 无论是否走 blit 路径，最后都会调用 Win32 `::SwapBuffers(m_device->GetPresentationDC())`
|
||||
|
||||
## 设计说明
|
||||
|
||||
这里的关键点是：当前 OpenGL 后端允许上层先渲染到一张普通纹理，再在 Present 阶段把纹理内容搬回默认窗口帧缓冲。这种结构更容易和跨后端 `RHITexture` / `RHIResourceView` 抽象保持一致。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 当前没有真正实现垂直同步控制
|
||||
- `MakeContextCurrent()` 的返回值没有被检查
|
||||
- 如果代理纹理仍处于 `ResourceStates::Common`，实现会跳过 blit，直接交换默认窗口缓冲
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLSwapChain.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [SwapBuffers](SwapBuffers.md)
|
||||
- [GetCurrentBackBuffer](GetCurrentBackBuffer.md)
|
||||
- [OpenGLScreenshot](../OpenGLScreenshot/OpenGLScreenshot.md)
|
||||
|
||||
@@ -1,32 +1,36 @@
|
||||
# OpenGLSwapChain::Resize
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
# OpenGLSwapChain::Resize()
|
||||
|
||||
```cpp
|
||||
void Resize(uint32_t width, uint32_t height) override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：**
|
||||
- `width` - 参数语义详见头文件声明。
|
||||
- `height` - 参数语义详见头文件声明。
|
||||
更新交换链对象记录的逻辑尺寸。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 参数
|
||||
|
||||
**示例：**
|
||||
- `width`: 新宽度
|
||||
- `height`: 新高度
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
|
||||
## 当前实现行为
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLSwapChain object;
|
||||
// 根据上下文补齐参数后调用 OpenGLSwapChain::Resize(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
- 仅把 `m_width` 更新为 `width`
|
||||
- 仅把 `m_height` 更新为 `height`
|
||||
- 不重建 `m_backBufferTexture`
|
||||
- 不调用任何 Win32 或 OpenGL 窗口尺寸同步逻辑
|
||||
|
||||
## 设计说明
|
||||
|
||||
当前实现把 `Resize()` 当成“状态通知”而不是“完整重建流程”。这对最小可运行后端足够，但和商业引擎里真正的 swap chain 重建仍有明显差距。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 调用后 [GetWidth](GetWidth.md) / [GetHeight](GetHeight.md) 会变化
|
||||
- 但 `GetCurrentBackBuffer()` 返回纹理的真实尺寸可能仍是旧值
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLSwapChain.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [GetWidth](GetWidth.md)
|
||||
- [GetHeight](GetHeight.md)
|
||||
- [Initialize](Initialize.md)
|
||||
|
||||
@@ -1,30 +1,31 @@
|
||||
# OpenGLSwapChain::Shutdown
|
||||
|
||||
关闭并清理内部状态。
|
||||
# OpenGLSwapChain::Shutdown()
|
||||
|
||||
```cpp
|
||||
void Shutdown() override;
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
释放交换链包装器当前持有的资源。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 如果 `m_backBufferTexture` 非空，则 `delete` 它
|
||||
- 把 `m_backBufferTexture` 置为 `nullptr`
|
||||
- 把 `m_hwnd` 置为 `nullptr`
|
||||
- 把 `m_device` 置为 `nullptr`
|
||||
- 不会修改 `m_width` 和 `m_height`
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
|
||||
## 设计说明
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLSwapChain object;
|
||||
// 根据上下文补齐参数后调用 OpenGLSwapChain::Shutdown(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
`Shutdown()` 只负责对象自己拥有的资源。窗口和 OpenGL 上下文都不由这个类创建，也就不在这里销毁。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 调用后 [GetCurrentBackBuffer](GetCurrentBackBuffer.md) 会返回 `nullptr`
|
||||
- 如果上层希望对象回到完全“未初始化”状态，还需要自行重置尺寸语义
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLSwapChain.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [Destructor](Destructor.md)
|
||||
- [GetCurrentBackBuffer](GetCurrentBackBuffer.md)
|
||||
|
||||
@@ -1,30 +1,25 @@
|
||||
# OpenGLSwapChain::SwapBuffers
|
||||
|
||||
公开方法，详见头文件声明。
|
||||
# OpenGLSwapChain::SwapBuffers()
|
||||
|
||||
```cpp
|
||||
void SwapBuffers();
|
||||
```
|
||||
|
||||
该方法声明于 `XCEngine/RHI/OpenGL/OpenGLSwapChain.h`，当前页面用于固定 `OpenGLSwapChain` 类目录下的方法级 canonical 路径。
|
||||
## 作用
|
||||
|
||||
**参数：** 无。
|
||||
直接调用窗口系统的缓冲交换函数。
|
||||
|
||||
**返回：** `void` - 无返回值。
|
||||
## 当前实现行为
|
||||
|
||||
**示例：**
|
||||
- 如果 `m_device` 非空，则执行 `::SwapBuffers(m_device->GetPresentationDC())`
|
||||
- 不做额外 blit
|
||||
- 不切换上下文
|
||||
- 不处理同步策略
|
||||
|
||||
```cpp
|
||||
#include <XCEngine/RHI/OpenGL/OpenGLSwapChain.h>
|
||||
## 何时使用
|
||||
|
||||
void Example() {
|
||||
XCEngine::RHI::OpenGLSwapChain object;
|
||||
// 根据上下文补齐参数后调用 OpenGLSwapChain::SwapBuffers(...)。
|
||||
(void)object;
|
||||
}
|
||||
```
|
||||
这是比 [Present](Present.md) 更底层的调用。当前代码里真正对外暴露的统一入口仍然是 `Present()`；`SwapBuffers()` 更适合作为内部辅助方法或调试使用。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [返回类总览](OpenGLSwapChain.md)
|
||||
- [返回模块目录](../OpenGL.md)
|
||||
- [Present](Present.md)
|
||||
- [GetNativeHandle](GetNativeHandle.md)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# API 文档重构状态
|
||||
|
||||
**生成时间**: `2026-03-28 00:49:41`
|
||||
**生成时间**: `2026-03-28 01:09:27`
|
||||
|
||||
**来源**: `docs/api/_tools/audit_api_docs.py`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user