diff --git a/docs/api/rhi/d3d12/fence/index.md b/docs/api/rhi/d3d12/fence/index.md index 40d32cdb..5b9a66bd 100644 --- a/docs/api/rhi/d3d12/fence/index.md +++ b/docs/api/rhi/d3d12/fence/index.md @@ -64,12 +64,12 @@ fence.Shutdown(); ## 相关文档 -- [Initialize](methods/initialize.md) -- [Shutdown](methods/shutdown.md) -- [Signal](methods/signal.md) -- [Wait](methods/wait.md) -- [GetCompletedValue](methods/get-completed-value.md) -- [IsSignaled](methods/is-signaled.md) -- [GetEventHandle](methods/get-event-handle.md) -- [GetNativeHandle](methods/get-native-handle.md) -- [GetFence](methods/get-fence.md) +- [Initialize](../../../threading/task-system/initialize.md) +- [Shutdown](../../../threading/task-system/shutdown.md) +- [Signal](../../command-queue/signal.md) +- [Wait](../../../threading/task-group/wait.md) +- [GetCompletedValue](../../command-queue/get-completed-value.md) +- [IsSignaled](../../fence/is-signaled.md) +- [GetEventHandle](get-event-handle.md) +- [GetNativeHandle](../../buffer/get-native-handle.md) +- [GetFence](get-fence.md) diff --git a/docs/api/rhi/d3d12/texture/destructor.md b/docs/api/rhi/d3d12/texture/destructor.md index d7675fb3..cce36b2a 100644 --- a/docs/api/rhi/d3d12/texture/destructor.md +++ b/docs/api/rhi/d3d12/texture/destructor.md @@ -39,4 +39,4 @@ O(n) - 取决于资源释放时间 ## 相关文档 - [D3D12Texture](texture.md) - 类总览 -- [Shutdown](../../../texture/shutdown.md) - 关闭纹理 +- [Shutdown](../../../threading/task-system/shutdown.md) - 关闭纹理 diff --git a/docs/api/rhi/framebuffer/framebuffer.md b/docs/api/rhi/framebuffer/framebuffer.md new file mode 100644 index 00000000..2ebc407a --- /dev/null +++ b/docs/api/rhi/framebuffer/framebuffer.md @@ -0,0 +1,54 @@ +# RHIFramebuffer + +**命名空间**: `XCEngine::RHI` + +**类型**: `class (abstract)` + +**头文件**: `XCEngine/RHI/RHIFramebuffer.h` + +**描述**: 帧缓冲抽象接口，封装渲染目标帧缓冲的创建和管理。 + +## 概述 + +`RHIFramebuffer` 是 RHI 抽象层的帧缓冲接口，用于管理渲染目标（Render Target）的帧缓冲对象。它代表一个可用的帧缓冲结构，包含颜色附件、深度附件和模板附件。不同图形 API 后端（OpenGL、D3D12）通过实现此接口提供各自的帧缓冲管理机制。 + +帧缓冲是渲染管线中的核心对象，用于： +- 存储渲染操作的颜色、深度、模板数据 +- 作为纹理输入传递给后续渲染步骤 +- 支持多重渲染目标（MRT）和延迟渲染 + +## 公共方法 + +| 方法 | 描述 | +|------|------| +| [`Initialize`](initialize.md) | 初始化帧缓冲 | +| [`Shutdown`](shutdown.md) | 关闭帧缓冲 | +| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | +| [`GetWidth`](get-width.md) | 获取帧缓冲宽度 | +| [`GetHeight`](get-height.md) | 获取帧缓冲高度 | +| [`IsValid`](is-valid.md) | 检查帧缓冲是否有效 | + +## 使用示例 + +```cpp +#include +#include + +// 通过 RHIDevice 创建帧缓冲 +RHIFramebuffer* framebuffer = device->CreateFramebuffer( + renderPass, + width, height, + colorAttachmentCount, + colorAttachments, + depthStencilAttachment +); + +if (framebuffer && framebuffer->IsValid()) { + // 使用帧缓冲进行渲染 + framebuffer->Shutdown(); +} +``` + +## 相关文档 + +- [RHIRenderPass](../render-pass/render-pass.md) - 渲染通道接口 diff --git a/docs/api/rhi/framebuffer/get-height.md b/docs/api/rhi/framebuffer/get-height.md new file mode 100644 index 00000000..9511c116 --- /dev/null +++ b/docs/api/rhi/framebuffer/get-height.md @@ -0,0 +1,17 @@ +# RHIFramebuffer::GetHeight + +获取帧缓冲的高度。 + +```cpp +virtual uint32_t GetHeight() const = 0; +``` + +**返回：** `uint32_t` - 帧缓冲高度（像素） + +**线程安全：** ✅ + +**示例：** + +```cpp +uint32_t height = framebuffer->GetHeight(); +``` diff --git a/docs/api/rhi/framebuffer/get-native-handle.md b/docs/api/rhi/framebuffer/get-native-handle.md new file mode 100644 index 00000000..c8eae108 --- /dev/null +++ b/docs/api/rhi/framebuffer/get-native-handle.md @@ -0,0 +1,25 @@ +# RHIFramebuffer::GetNativeHandle + +获取帧缓冲的原生句柄。 + +```cpp +virtual void* GetNativeHandle() = 0; +``` + +返回底层图形 API 的帧缓冲句柄。不同后端返回不同类型： +- OpenGL: 返回 `GLuint`（帧缓冲对象 ID） +- D3D12: 返回 `ID3D12Resource*` 指针 + +**返回：** `void*` - 原生句柄 + +**线程安全：** ❌ + +**示例：** + +```cpp +void* handle = framebuffer->GetNativeHandle(); +#ifdef XCENGINE_OPENGL + GLuint fbo = static_cast(reinterpret_cast(handle)); + glBindFramebuffer(GL_FRAMEBUFFER, fbo); +#endif +``` diff --git a/docs/api/rhi/framebuffer/get-width.md b/docs/api/rhi/framebuffer/get-width.md new file mode 100644 index 00000000..bdb84cf2 --- /dev/null +++ b/docs/api/rhi/framebuffer/get-width.md @@ -0,0 +1,17 @@ +# RHIFramebuffer::GetWidth + +获取帧缓冲的宽度。 + +```cpp +virtual uint32_t GetWidth() const = 0; +``` + +**返回：** `uint32_t` - 帧缓冲宽度（像素） + +**线程安全：** ✅ + +**示例：** + +```cpp +uint32_t width = framebuffer->GetWidth(); +``` diff --git a/docs/api/rhi/framebuffer/initialize.md b/docs/api/rhi/framebuffer/initialize.md new file mode 100644 index 00000000..b93a31e4 --- /dev/null +++ b/docs/api/rhi/framebuffer/initialize.md @@ -0,0 +1,49 @@ +# RHIFramebuffer::Initialize + +初始化帧缓冲对象。 + +```cpp +virtual bool Initialize( + class RHIRenderPass* renderPass, + uint32_t width, + uint32_t height, + uint32_t colorAttachmentCount, + RHIResourceView** colorAttachments, + RHIResourceView* depthStencilAttachment +) = 0; +``` + +根据指定的渲染通道和附件配置，创建并初始化帧缓冲对象。 + +**参数：** +- `renderPass` - 关联的渲染通道对象 +- `width` - 帧缓冲宽度（像素） +- `height` - 帧缓冲高度（像素） +- `colorAttachmentCount` - 颜色附件数量 +- `colorAttachments` - 颜色附件资源视图数组 +- `depthStencilAttachment` - 深度模板附件资源视图，可为 `nullptr` + +**返回：** `bool` - 初始化成功返回 `true`，失败返回 `false` + +**线程安全：** ❌ + +**注意：** +- `width` 和 `height` 必须大于 0 +- `colorAttachments` 数组长度必须与 `colorAttachmentCount` 匹配 +- 所有附件的尺寸必须与指定的 `width`、`height` 一致 +- 帧缓冲创建后，其尺寸不可更改，需调用 `Shutdown` 后重新初始化 + +**示例：** + +```cpp +// 创建带有颜色和深度附件的帧缓冲 +RHIResourceView* colorViews[1] = { colorRTView }; +RHIResourceView* depthView = depthStencilView; + +bool success = framebuffer->Initialize( + renderPass, + 1920, 1080, + 1, colorViews, + depthView +); +``` diff --git a/docs/api/rhi/framebuffer/is-valid.md b/docs/api/rhi/framebuffer/is-valid.md new file mode 100644 index 00000000..e13a9a4f --- /dev/null +++ b/docs/api/rhi/framebuffer/is-valid.md @@ -0,0 +1,27 @@ +# RHIFramebuffer::IsValid + +检查帧缓冲是否有效。 + +```cpp +virtual bool IsValid() const = 0; +``` + +判断帧缓冲是否已正确初始化且可用于渲染操作。 + +**返回：** `bool` - 帧缓冲有效返回 `true`，无效返回 `false` + +**线程安全：** ✅ + +**注意：** +- 返回 `false` 可能原因：未初始化、初始化失败、已被 `Shutdown` +- 在调用 `Initialize` 前调用此方法会返回 `false` + +**示例：** + +```cpp +if (framebuffer->IsValid()) { + // 执行渲染操作 +} else { + // 处理无效帧缓冲 +} +``` diff --git a/docs/api/rhi/framebuffer/shutdown.md b/docs/api/rhi/framebuffer/shutdown.md new file mode 100644 index 00000000..968d998d --- /dev/null +++ b/docs/api/rhi/framebuffer/shutdown.md @@ -0,0 +1,21 @@ +# RHIFramebuffer::Shutdown + +关闭帧缓冲并释放相关资源。 + +```cpp +virtual void Shutdown() = 0; +``` + +销毁帧缓冲对象，释放底层图形 API 资源。调用后，帧缓冲不再有效，需要重新调用 `Initialize` 才能使用。 + +**线程安全：** ❌ + +**注意：** +- 调用此方法后，帧缓冲对象仍可被安全地重复调用 `Shutdown` +- 确保在帧缓冲未被任何活跃渲染操作使用时调用 + +**示例：** + +```cpp +framebuffer->Shutdown(); +``` diff --git a/docs/api/rhi/opengl/README.md b/docs/api/rhi/opengl/README.md index a2e4a91a..f3ec7d3a 100644 --- a/docs/api/rhi/opengl/README.md +++ b/docs/api/rhi/opengl/README.md @@ -22,5 +22,5 @@ OpenGL 后端已创建以下组件文件夹和文档： ## 相关文档 -- [OpenGL 后端总览](overview.md) -- [RHI 抽象层](overview.md) +- [OpenGL 后端总览](opengl.md) +- [RHI 抽象层](opengl.md) diff --git a/docs/api/rhi/opengl/buffer/buffer.md b/docs/api/rhi/opengl/buffer/buffer.md index 15286729..dc5adf34 100644 --- a/docs/api/rhi/opengl/buffer/buffer.md +++ b/docs/api/rhi/opengl/buffer/buffer.md @@ -34,5 +34,5 @@ ## 相关文档 -- [OpenGL 后端总览](../overview.md) +- [OpenGL 后端总览](../opengl.md) - [RHIBuffer](../../buffer/buffer.md) - 抽象缓冲区接口 diff --git a/docs/api/rhi/opengl/command-list/command-list.md b/docs/api/rhi/opengl/command-list/command-list.md index 478e18cb..0d6d9d2c 100644 --- a/docs/api/rhi/opengl/command-list/command-list.md +++ b/docs/api/rhi/opengl/command-list/command-list.md @@ -111,5 +111,5 @@ delete cmdList; ## 相关文档 -- [OpenGL 后端总览](../overview.md) +- [OpenGL 后端总览](../opengl.md) - [RHICommandList](../../command-list/command-list.md) - 抽象命令列表接口 diff --git a/docs/api/rhi/opengl/command-queue/command-queue.md b/docs/api/rhi/opengl/command-queue/command-queue.md index c9b66b0e..d706be84 100644 --- a/docs/api/rhi/opengl/command-queue/command-queue.md +++ b/docs/api/rhi/opengl/command-queue/command-queue.md @@ -26,5 +26,5 @@ OpenGL 采用立即模式（Immediate Mode）渲染，与 D3D12 的命令列表 ## 相关文档 -- [OpenGL 后端总览](../overview.md) +- [OpenGL 后端总览](../opengl.md) - [RHICommandQueue](../../command-queue/command-queue.md) - 抽象命令队列接口 \ No newline at end of file diff --git a/docs/api/rhi/opengl/depth-stencil-view/depth-stencil-view.md b/docs/api/rhi/opengl/depth-stencil-view/depth-stencil-view.md index 1960a8be..faa2953d 100644 --- a/docs/api/rhi/opengl/depth-stencil-view/depth-stencil-view.md +++ b/docs/api/rhi/opengl/depth-stencil-view/depth-stencil-view.md @@ -44,4 +44,4 @@ ## 相关文档 -- [OpenGL 后端总览](../overview.md) +- [OpenGL 后端总览](../opengl.md) diff --git a/docs/api/rhi/opengl/device/device.md b/docs/api/rhi/opengl/device/device.md index a753b783..5f9cc728 100644 --- a/docs/api/rhi/opengl/device/device.md +++ b/docs/api/rhi/opengl/device/device.md @@ -102,5 +102,5 @@ if (device.InitializeWithExistingWindow(existingWindow)) { ## 相关文档 -- [OpenGL 后端总览](../overview.md) +- [OpenGL 后端总览](../opengl.md) - [RHIDevice](../../device/device.md) - 抽象设备接口 diff --git a/docs/api/rhi/opengl/fence/fence.md b/docs/api/rhi/opengl/fence/fence.md index 5177b033..f55e142f 100644 --- a/docs/api/rhi/opengl/fence/fence.md +++ b/docs/api/rhi/opengl/fence/fence.md @@ -70,5 +70,5 @@ fence.Reset(); ## 相关文档 -- [OpenGL 后端总览](../overview.md) +- [OpenGL 后端总览](../opengl.md) - [RHIFence](../../fence/fence.md) - 抽象栅栏接口 diff --git a/docs/api/rhi/opengl/opengl.md b/docs/api/rhi/opengl/opengl.md index 3dcedf24..c8483083 100644 --- a/docs/api/rhi/opengl/opengl.md +++ b/docs/api/rhi/opengl/opengl.md @@ -38,4 +38,4 @@ ## 相关文档 - [RHI 模块总览](../rhi.md) - RHI 模块总览 -- [D3D12 后端](overview.md) +- [D3D12 后端](../../d3d12/d3d12.md) diff --git a/docs/api/rhi/opengl/pipeline-state/pipeline-state.md b/docs/api/rhi/opengl/pipeline-state/pipeline-state.md index 4092e172..a93531ca 100644 --- a/docs/api/rhi/opengl/pipeline-state/pipeline-state.md +++ b/docs/api/rhi/opengl/pipeline-state/pipeline-state.md @@ -37,5 +37,5 @@ ## 相关文档 -- [OpenGL 后端总览](../overview.md) +- [OpenGL 后端总览](../opengl.md) - [RHIPipelineState](../../pipeline-state/pipeline-state.md) - 抽象管线状态接口 diff --git a/docs/api/rhi/opengl/render-target-view/render-target-view.md b/docs/api/rhi/opengl/render-target-view/render-target-view.md index ed80d144..bebfa3a5 100644 --- a/docs/api/rhi/opengl/render-target-view/render-target-view.md +++ b/docs/api/rhi/opengl/render-target-view/render-target-view.md @@ -85,4 +85,4 @@ void RenderToCubemap() { ## 相关文档 -- [OpenGL 后端总览](../overview.md) +- [OpenGL 后端总览](../opengl.md) diff --git a/docs/api/rhi/opengl/sampler/sampler.md b/docs/api/rhi/opengl/sampler/sampler.md index 130911ba..1f268e4a 100644 --- a/docs/api/rhi/opengl/sampler/sampler.md +++ b/docs/api/rhi/opengl/sampler/sampler.md @@ -68,5 +68,5 @@ if (sampler.Initialize(desc)) { ## 相关文档 -- [OpenGL 后端总览](../overview.md) +- [OpenGL 后端总览](../opengl.md) - [RHISampler](../../sampler/sampler.md) - 抽象采样器接口 diff --git a/docs/api/rhi/opengl/shader/get-id.md b/docs/api/rhi/opengl/shader/get-id.md index 6b8bfb65..d628f61a 100644 --- a/docs/api/rhi/opengl/shader/get-id.md +++ b/docs/api/rhi/opengl/shader/get-id.md @@ -20,4 +20,4 @@ glUseProgram(programId); ## 相关文档 - [OpenGLShader 总览](shader.md) - 返回类总览 -- [GetNativeHandle](../../buffer/get-native-handle.md) - 原生句柄 +- [GetNativeHandle](../../shader/get-native-handle.md) - 原生句柄 diff --git a/docs/api/rhi/opengl/shader/shader.md b/docs/api/rhi/opengl/shader/shader.md index 339b45f9..7c29390f 100644 --- a/docs/api/rhi/opengl/shader/shader.md +++ b/docs/api/rhi/opengl/shader/shader.md @@ -47,11 +47,11 @@ |------|------| | [`GetUniformLocation`](get-uniform-location.md) | 获取 uniform 位置 | | [`GetID`](get-id.md) | 获取着色器 ID | -| [`GetNativeHandle`](../../buffer/get-native-handle.md) | 获取原生句柄 | +| [`GetNativeHandle`](../../shader/get-native-handle.md) | 获取原生句柄 | | [`IsValid`](../../shader/is-valid.md) | 检查是否有效 | | [`GetType`](../../shader/get-type.md) | 获取着色器类型 | ## 相关文档 -- [OpenGL 后端总览](../overview.md) +- [OpenGL 后端总览](../opengl.md) - [RHIShader](../../shader/shader.md) - 抽象着色器接口 diff --git a/docs/api/rhi/opengl/swap-chain/swap-chain.md b/docs/api/rhi/opengl/swap-chain/swap-chain.md index b6a3262b..a6fbbf62 100644 --- a/docs/api/rhi/opengl/swap-chain/swap-chain.md +++ b/docs/api/rhi/opengl/swap-chain/swap-chain.md @@ -72,5 +72,5 @@ swapChain.Shutdown(); ## 相关文档 -- [OpenGL 后端总览](../overview.md) +- [OpenGL 后端总览](../opengl.md) - [RHISwapChain](../../swap-chain/swap-chain.md) - 抽象交换链接口 diff --git a/docs/api/rhi/opengl/texture/texture.md b/docs/api/rhi/opengl/texture/texture.md index f0300c26..8f071c17 100644 --- a/docs/api/rhi/opengl/texture/texture.md +++ b/docs/api/rhi/opengl/texture/texture.md @@ -38,5 +38,5 @@ ## 相关文档 -- [OpenGL 后端总览](../overview.md) +- [OpenGL 后端总览](../opengl.md) - [RHITexture](../../texture/texture.md) - 抽象纹理接口 diff --git a/docs/api/rhi/opengl/vertex-array/vertex-array.md b/docs/api/rhi/opengl/vertex-array/vertex-array.md index 5200da88..6510db5e 100644 --- a/docs/api/rhi/opengl/vertex-array/vertex-array.md +++ b/docs/api/rhi/opengl/vertex-array/vertex-array.md @@ -64,5 +64,5 @@ vao.Shutdown(); ## 相关文档 -- [OpenGL 后端总览](../overview.md) +- [OpenGL 后端总览](../opengl.md) - [VertexAttribute 结构体](vertex-attribute.md) diff --git a/docs/api/rhi/render-pass/get-color-attachment-count.md b/docs/api/rhi/render-pass/get-color-attachment-count.md new file mode 100644 index 00000000..32cf30e0 --- /dev/null +++ b/docs/api/rhi/render-pass/get-color-attachment-count.md @@ -0,0 +1,17 @@ +# RHIRenderPass::GetColorAttachmentCount + +获取颜色附件的数量。 + +```cpp +virtual uint32_t GetColorAttachmentCount() const = 0; +``` + +**返回：** `uint32_t` - 颜色附件数量 + +**线程安全：** ✅ + +**示例：** + +```cpp +uint32_t count = renderPass->GetColorAttachmentCount(); +``` diff --git a/docs/api/rhi/render-pass/get-color-attachments.md b/docs/api/rhi/render-pass/get-color-attachments.md new file mode 100644 index 00000000..70106a25 --- /dev/null +++ b/docs/api/rhi/render-pass/get-color-attachments.md @@ -0,0 +1,27 @@ +# RHIRenderPass::GetColorAttachments + +获取颜色附件描述数组。 + +```cpp +virtual const AttachmentDesc* GetColorAttachments() const = 0; +``` + +返回渲染通道初始化时配置的颜色附件描述数组。数组长度可通过 `GetColorAttachmentCount()` 获取。 + +**返回：** `const AttachmentDesc*` - 颜色附件描述数组指针 + +**线程安全：** ✅ + +**注意：** +- 返回的指针在渲染通道生命周期内有效 +- 不要尝试修改返回的描述数据 + +**示例：** + +```cpp +const AttachmentDesc* attachments = renderPass->GetColorAttachments(); +for (uint32_t i = 0; i < renderPass->GetColorAttachmentCount(); ++i) { + Format format = attachments[i].format; + // 处理每个附件配置 +} +``` diff --git a/docs/api/rhi/render-pass/get-depth-stencil-attachment.md b/docs/api/rhi/render-pass/get-depth-stencil-attachment.md new file mode 100644 index 00000000..1f8f469d --- /dev/null +++ b/docs/api/rhi/render-pass/get-depth-stencil-attachment.md @@ -0,0 +1,27 @@ +# RHIRenderPass::GetDepthStencilAttachment + +获取深度模板附件描述。 + +```cpp +virtual const AttachmentDesc* GetDepthStencilAttachment() const = 0; +``` + +返回渲染通道初始化时配置的深度模板附件描述。如果渲染通道未配置深度模板附件，返回 `nullptr`。 + +**返回：** `const AttachmentDesc*` - 深度模板附件描述指针，未配置时返回 `nullptr` + +**线程安全：** ✅ + +**注意：** +- 返回的指针在渲染通道生命周期内有效 +- 不要尝试修改返回的描述数据 + +**示例：** + +```cpp +const AttachmentDesc* depthStencil = renderPass->GetDepthStencilAttachment(); +if (depthStencil != nullptr) { + Format format = depthStencil->format; + // 处理深度模板配置 +} +``` diff --git a/docs/api/rhi/render-pass/get-native-handle.md b/docs/api/rhi/render-pass/get-native-handle.md new file mode 100644 index 00000000..a4e87ed7 --- /dev/null +++ b/docs/api/rhi/render-pass/get-native-handle.md @@ -0,0 +1,23 @@ +# RHIRenderPass::GetNativeHandle + +获取渲染通道的原生句柄。 + +```cpp +virtual void* GetNativeHandle() = 0; +``` + +返回底层图形 API 的渲染通道句柄。 + +**返回：** `void*` - 原生句柄 + +**线程安全：** ❌ + +**注意：** +- OpenGL 实现返回 `nullptr`（OpenGL 使用 FBO 绑定状态而非句柄） +- D3D12 实现返回平台相关的渲染通道对象 + +**示例：** + +```cpp +void* handle = renderPass->GetNativeHandle(); +``` diff --git a/docs/api/rhi/render-pass/initialize.md b/docs/api/rhi/render-pass/initialize.md new file mode 100644 index 00000000..c01a4071 --- /dev/null +++ b/docs/api/rhi/render-pass/initialize.md @@ -0,0 +1,43 @@ +# RHIRenderPass::Initialize + +初始化渲染通道对象。 + +```cpp +virtual bool Initialize( + uint32_t colorAttachmentCount, + const AttachmentDesc* colorAttachments, + const AttachmentDesc* depthStencilAttachment +) = 0; +``` + +根据指定的附件配置创建并初始化渲染通道对象。 + +**参数：** +- `colorAttachmentCount` - 颜色附件数量 +- `colorAttachments` - 颜色附件描述数组，长度必须等于 `colorAttachmentCount` +- `depthStencilAttachment` - 深度模板附件描述，可为 `nullptr`（如果不需要深度模板） + +**返回：** `bool` - 初始化成功返回 `true`，失败返回 `false` + +**线程安全：** ❌ + +**注意：** +- `colorAttachmentCount` 必须大于 0 +- 每个 `AttachmentDesc` 的 `format` 必须指定为有效的 `Format` 枚举值 +- 渲染通道创建后不可修改其配置 + +**示例：** + +```cpp +AttachmentDesc colorDesc; +colorDesc.format = Format::RGBA8_UNORM; +colorDesc.loadOp = LoadAction::Clear; +colorDesc.storeOp = StoreAction::Store; + +AttachmentDesc depthDesc; +depthDesc.format = Format::D24_UNORM_S8_UINT; +depthDesc.loadOp = LoadAction::Clear; +depthDesc.storeOp = StoreAction::Store; + +RHIRenderPass* pass = device->CreateRenderPass(1, &colorDesc, &depthDesc); +``` diff --git a/docs/api/rhi/render-pass/render-pass.md b/docs/api/rhi/render-pass/render-pass.md new file mode 100644 index 00000000..93a06e80 --- /dev/null +++ b/docs/api/rhi/render-pass/render-pass.md @@ -0,0 +1,79 @@ +# RHIRenderPass + +**命名空间**: `XCEngine::RHI` + +**类型**: `class (abstract)` + +**头文件**: `XCEngine/RHI/RHIRenderPass.h` + +**描述**: 渲染通道抽象接口，定义了渲染操作所需的附件配置和加载/存储行为。 + +## 概述 + +`RHIRenderPass` 是 RHI 抽象层的渲染通道接口，用于描述渲染操作所需的附件配置。每个渲染通道定义了： +- 颜色附件的数量和格式 +- 深度/模板附件（可选） +- 每个附件的加载操作（LoadAction） +- 每个附件的存储操作（StoreAction） +- 清除值（ClearValue） + +渲染通道是延迟渲染和多渲染目标（MRT）等高级渲染技术的基础，它允许 GPU 预先知道帧缓冲配置，从而优化内存访问。 + +## AttachmentDesc 结构体 + +```cpp +struct AttachmentDesc { + Format format = Format::Unknown; + LoadAction loadOp = LoadAction::Undefined; + StoreAction storeOp = StoreAction::Store; + LoadAction stencilLoadOp = LoadAction::Undefined; + StoreAction stencilStoreOp = StoreAction::Undefined; + ClearValue clearValue; +}; +``` + +| 成员 | 类型 | 描述 | +|------|------|------| +| `format` | `Format` | 附件的像素格式 | +| `loadOp` | `LoadAction` | 渲染前颜色数据的加载操作 | +| `storeOp` | `StoreAction` | 渲染后颜色数据的存储操作 | +| `stencilLoadOp` | `LoadAction` | 渲染前模板数据的加载操作 | +| `stencilStoreOp` | `StoreAction` | 渲染后模板数据的存储操作 | +| `clearValue` | `ClearValue` | 清除颜色值 | + +## 公共方法 + +| 方法 | 描述 | +|------|------| +| [`Initialize`](initialize.md) | 初始化渲染通道 | +| [`Shutdown`](shutdown.md) | 关闭渲染通道 | +| [`GetNativeHandle`](get-native-handle.md) | 获取原生句柄 | +| [`GetColorAttachmentCount`](get-color-attachment-count.md) | 获取颜色附件数量 | +| [`GetColorAttachments`](get-color-attachments.md) | 获取颜色附件描述数组 | +| [`GetDepthStencilAttachment`](get-depth-stencil-attachment.md) | 获取深度模板附件描述 | + +## 使用示例 + +```cpp +#include + +// 配置颜色附件 +AttachmentDesc colorAttachments[1]; +colorAttachments[0].format = Format::RGBA8_UNORM; +colorAttachments[0].loadOp = LoadAction::Clear; +colorAttachments[0].storeOp = StoreAction::Store; +colorAttachments[0].clearValue.color = { 0.0f, 0.0f, 0.0f, 1.0f }; + +// 配置深度附件（可选） +AttachmentDesc depthAttachment; +depthAttachment.format = Format::D24_UNORM_S8_UINT; +depthAttachment.loadOp = LoadAction::Clear; +depthAttachment.storeOp = StoreAction::Store; + +// 创建渲染通道 +RHIRenderPass* renderPass = device->CreateRenderPass(1, colorAttachments, &depthAttachment); +``` + +## 相关文档 + +- [RHIFramebuffer](../framebuffer/framebuffer.md) - 帧缓冲接口 diff --git a/docs/api/rhi/render-pass/shutdown.md b/docs/api/rhi/render-pass/shutdown.md new file mode 100644 index 00000000..1c71946c --- /dev/null +++ b/docs/api/rhi/render-pass/shutdown.md @@ -0,0 +1,21 @@ +# RHIRenderPass::Shutdown + +关闭渲染通道并释放相关资源。 + +```cpp +virtual void Shutdown() = 0; +``` + +销毁渲染通道对象，释放底层图形 API 资源。调用后，渲染通道不再有效。 + +**线程安全：** ❌ + +**注意：** +- 确保在没有任何帧缓冲正在使用此渲染通道时调用 +- 调用此方法后，已创建的关联帧缓冲可能变为无效 + +**示例：** + +```cpp +renderPass->Shutdown(); +``` diff --git a/docs/api/rhi/rhi.md b/docs/api/rhi/rhi.md index dd453e9d..534c7d28 100644 --- a/docs/api/rhi/rhi.md +++ b/docs/api/rhi/rhi.md @@ -40,7 +40,7 @@ RHI 模块将上层渲染逻辑与底层图形 API 解耦，通过抽象接口 | 类 | 文档 | 描述 | |----|------|------| | [RHIDevice](device/device.md) | `RHIDevice.h` | 渲染设备抽象，代表图形适配器实例 | -| [RHIFactory](rhifactory/rhifactory.md) | `RHIFactory.h` | 设备工厂，用于创建不同后端的设备实例 | +| [RHIFactory](factory/factory.md) | `RHIFactory.h` | 设备工厂，用于创建不同后端的设备实例 | ### 资源管理 @@ -49,6 +49,7 @@ RHI 模块将上层渲染逻辑与底层图形 API 解耦，通过抽象接口 | [RHIBuffer](buffer/buffer.md) | `RHIBuffer.h` | GPU 缓冲区资源，存储顶点、索引、常量等数据 | | [RHITexture](texture/texture.md) | `RHITexture.h` | GPU 纹理资源，存储 1D/2D/3D 图像数据 | | [RHIShader](shader/shader.md) | `RHIShader.h` | 着色器资源，管理顶点、像素等着色器程序 | +| [RHIFramebuffer](framebuffer/framebuffer.md) | `RHIFramebuffer.h` | 帧缓冲对象，管理渲染目标的颜色、深度和模板附件 | ### 命令执行 @@ -67,6 +68,7 @@ RHI 模块将上层渲染逻辑与底层图形 API 解耦，通过抽象接口 | [RHISampler](sampler/sampler.md) | `RHISampler.h` | 纹理采样器，配置纹理过滤和寻址模式 | | [RHIPipelineLayout](pipeline-layout/pipeline-layout.md) | `RHIPipelineLayout.h` | 管线布局，定义着色器资源绑定布局 | | [RHIDescriptorPool](descriptor-pool/descriptor-pool.md) | `RHIDescriptorPool.h` | 描述符池，管理 GPU 描述符分配 | +| [RHIRenderPass](render-pass/render-pass.md) | `RHIRenderPass.h` | 渲染通道，定义渲染操作的附件配置和加载/存储行为 | ### 类型与能力