diff --git a/docs/zh/render-backend-dynamic-plan.md b/docs/zh/render-backend-dynamic-plan.md index 051e4efa4..5dd2a9fef 100644 --- a/docs/zh/render-backend-dynamic-plan.md +++ b/docs/zh/render-backend-dynamic-plan.md @@ -73,20 +73,21 @@ ## 阶段 3:Vulkan 后端(原型实现,运行时验证待完成) - 新增 Vulkan 后端库 `liboakvulkan.so`(当系统安装了 Vulkan 头文件/库时构建;无 Vulkan 环境时 CMake 自动跳过)。 -- 新增 `VulkanRenderer` 类,继承 `Renderer`,使用原生 Vulkan API 实现 offscreen 渲染管线;代码已合入,但尚未在真实 Vulkan 驱动上完整跑通。 +- 新增 `VulkanRenderer` 类,继承 `Renderer`,使用原生 Vulkan API 实现 offscreen 渲染管线;代码已合入,并在本机 NVIDIA Vulkan 驱动上通过了基础端到端渲染测试。 - CMake 集成:根目录查找 `Vulkan` 和 `shaderc`(可选);`oakvulkan` 目标链接 `Vulkan::Vulkan` 与 `shaderc_shared`;若 `Vulkan` 未找到则不构建该库,避免无 Vulkan 头文件时编译失败。 - 实现 Vulkan instance/device/queue/command pool 管理(代码层完成)。 - 实现 offscreen image/texture 管理(`CreateNativeTexture` / `DestroyNativeTexture`),支持 2D/3D、多种 pixel format(U8/U16/F16/F32 × 1/2/3/4 channel);3-channel 格式会探测 `COLOR_ATTACHMENT` 支持并自动回退到 4-channel 等价格式。 - 实现 staging buffer 上传/下载(`UploadToTexture` / `DownloadFromTexture`)。 - 实现 `ClearDestination`(`vkCmdClearColorImage`)。 - 实现 `Flush`(`vkDeviceWaitIdle`)。 -- 实现 GLSL → SPIR-V 运行时编译(通过 `shaderc`),支持自动 uniform binding。 -- 实现基础 graphics pipeline 用于 `Blit`(全屏 quad、顶点缓冲、按格式缓存的 render pass、combined image sampler descriptor set)。 +- 实现 GLSL → SPIR-V 运行时编译(通过 `shaderc`),支持顶点/片段共享 UBO、显式 sampler binding、顶点 uniform(如 `ove_mvpmat`)和常用 varyings。 +- 实现基础 graphics pipeline 用于 `Blit`(全屏 quad、顶点缓冲、按格式缓存的 render pass、combined image sampler descriptor set、persistent linear/nearest sampler、per-texture framebuffer cache)。 - 提供 `GetPixelFromTexture`(基于 `DownloadFromTexture` 的简化实现)。 - `oak_renderer_is_available` 现在会在首次检查时尝试 `Init()`,成功后报告 Vulkan 可用。 - 测试更新: - `LoadsExperimentalVulkanBackendWhenAvailable`:验证 Vulkan 后端可加载、初始化、报告能力位。 - `FallsBackWhenExperimentalVulkanUnavailable`:在 Vulkan 不可用的系统上验证回退 OpenGL;在 Vulkan 可用的系统上自动 SKIP。 + - `VulkanUploadBlitDownload`:创建 Vulkan backend,上传 U8 RGBA 纹理,经默认 pass-through shader Blit 到目标纹理,再下载并验证像素一致;该测试在当前开发环境的真实 Vulkan 驱动上通过。 - **已修复的明显问题(代码层)**: - 初始化幂等性:`Init()` / `PostInit()` 可安全重复调用。 - `Blit` 中的 descriptor/sampler 生命周期:sampler 与 descriptor set 在 `EndOneTimeCommands` 后统一释放。 @@ -94,11 +95,15 @@ - image layout 跟踪:输入纹理在绘制前被过渡到 `SHADER_READ_ONLY_OPTIMAL`。 - viewport/scissor:改为 dynamic state,避免 pipeline 缓存 key 遗漏视口尺寸。 - render pass clear:`clear_destination` 为 true 时 `loadOp` 设为 `CLEAR`。 - - 格式支持探测:通过 `vkGetPhysicalDeviceFormatProperties` 检查 `COLOR_ATTACHMENT` 能力,3-channel 不支持时回退到 4-channel。 + - 格式支持探测:通过 `vkGetPhysicalDeviceFormatProperties` 检查 `COLOR_ATTACHMENT` 能力,3-channel 不支持时回退到 4-channel(上传/下载的 CPU 侧通道对齐仍待完善)。 + - framebuffer / sampler 缓存:每张纹理延迟创建并复用 framebuffer;按插值模式复用 linear/nearest sampler。 + - 单通道纹理 swizzle:image view 组件映射为 R→RGB、A=1,匹配 OpenGL 灰度行为。 + - 纹理启用标志:为声明 `NAME_enabled` 的 shader 自动设置 0/1。 - **已知限制 / 待完善**: - 链接边界已最小化,`liboakvulkan.so` 现在只依赖 `libolive-rendercore`。 - - 尚未在真实 Vulkan 驱动/设备上验证渲染正确性。 - - 尚未在 proxy、thumbnail/cache、导出等完整渲染路径上验证 Vulkan 输出一致性。 + - 单通道/3-channel 格式的上传/下载 CPU 侧对齐、回退格式与请求格式不一致时的数据转换仍待完善。 + - `Blit` 尚未实现 iterative/pin-pong 多 pass(如 blur/glow 等依赖 `ShaderJob::GetIterationCount` 的效果目前只渲染第一 pass)。 + - 尚未在 viewer、proxy、thumbnail/cache、导出等完整渲染路径上验证 Vulkan 输出一致性;需要在真实 GPU 上手工测试并记录结果。 ## 阶段 4:Viewer 双后端(backend-neutral 路径已落地,Vulkan viewer 为原型) @@ -116,7 +121,7 @@ - `ViewerDisplayWidget::OnPaint` 在 backend-neutral 模式下改用 `QPainter` 填充背景,将颜色管理后的画面渲染到 U8 RGBA offscreen texture,再 `Download` 到 CPU buffer,最后用 `QImage::Format_RGBA8888_Premultiplied` + `setDevicePixelRatio` 绘制到 inner widget。 - OpenGL 路径保持原有 `BlitColorManaged` 直接到 widget 不变。 - Viewer 只消费后端 texture handle 或 readback frame,不直接假设 GL texture id。 -- **状态说明**:backend-neutral 代码已合并,但 Vulkan viewer 目前受限于 VulkanRenderer 原型状态,尚未在真实设备上验证端到端显示。 +- **状态说明**:backend-neutral 代码已合并;VulkanRenderer 现在可完成单 pass Blit,Viewer 的 backend-neutral readback 路径在代码层面可工作,但尚未在完整 UI 播放/导出流程中验证。 ## 阶段 5:OpenFX 处理边界(边界框架已完成,Vulkan 路径待验证) @@ -132,7 +137,7 @@ - 格式转换(`ConvertFrameIfNeeded`、`ConvertTextureForParams`)、readback(`ReadbackTextureToFrame`)、upload 等辅助函数保持后端无关,通过 `Renderer` 接口调用,无需移入后端库。 - `RenderProcessor::ProcessPluginJob` 不再要求 `render_ctx_` 实现 `OpenGLContextProvider`,任何 `Renderer` 都能驱动插件渲染。 - 更新相关 gtest:`PluginRenderer` 构造函数现在需要传入 renderer 指针,测试传入 `nullptr` 验证纯 CPU 路径。 -- **状态说明**:后端无关的边界框架和 OpenGL 动态路径已可编译并通过现有测试;Vulkan 下的 OFX CPU 回退路径代码已就位,但尚未在真实 Vulkan 后端上验证。 +- **状态说明**:后端无关的边界框架和 OpenGL 动态路径已可编译并通过现有测试;Vulkan 下的 OFX CPU 回退路径代码已就位,并在 Vulkan 可完成基础 Blit 的当前版本上具备验证条件。 ## 完成标准 @@ -142,6 +147,6 @@ - [x] 用户能在配置中选择 OpenGL/Vulkan。 - [x] Vulkan 不可用时自动回退到 OpenGL,不崩溃;`RenderManager::backend()` 会在 `DynamicRenderer` 内部回退后同步为实际运行后端。 - [x] 链接边界已最小化:`oakgl` / `oakvulkan` 现在只链接独立的 `libolive-rendercore`,不再拉入完整 editor 代码;库体积从约 21 MB 降至约 600 KB。 -- [x] Vulkan / backend-neutral viewer readback display 路径已搭建(offscreen texture → download → QImage → QPainter),但端到端显示尚未在真实 Vulkan 设备上验证。 +- [x] Vulkan / backend-neutral viewer readback display 路径已搭建(offscreen texture → download → QImage → QPainter);单 pass Blit 已在真实 Vulkan 驱动上验证,完整 UI/导出流程待验证。 - [x] OpenFX 插件渲染边界已处理:`PluginRenderer` 后端无关化,非 OpenGL 渲染器自动回退 CPU 路径,动态 OpenGL 后端通过 C ABI 支持 OFX OpenGL 输出绑定。 - [ ] 手工测试计划覆盖 viewer、proxy、scope、导出等完整路径。