WaveEngine

WaveEngine 是一个面向 Windows x64 的 C++20 / DirectX 12 实时渲染引擎，附带轻量 ImGui 场景编辑器。仓库以可直接阅读和修改的渲染、场景、资产与编辑器代码为主。

主要能力

• DirectX 12 光栅管线：Mesh Shader、bindless 资源、G-Buffer、阴影、IBL、光照、曝光与 Tonemap。
• 可选 DXR 1.1 Path Tracing；硬件不支持时继续使用光栅路径。
• glTF、OBJ、FBX 静态模型导入，以及 WEMesh v3 缓存和 WEScene v7 场景文件；保留 v1–v6 场景读取兼容。
• Object + Component 世界物体管理：必带 Transform，可组合 Mesh、Camera、Directional Light，支持激活/启用状态及可撤销编辑；编辑器预览相机独立于游戏相机。详见 Object 与 Component。
• ImGui 编辑器：视口、层级、属性、资产浏览、渲染设置、撤销与重做。
• 异步 CPU 资产构建、按预算分帧上传与 fence 完成后 Mesh 发布、共享缓存和安全的 GPU 资源关闭。
• 持久有界 CPU 作业池，以及显式只读渲染帧快照和资源访问声明。
• 持久 EntityId、带 generation 的逻辑/渲染句柄、延迟复用的稳定 GPU 实例槽位，以及 double 世界位置和相机相对 float 渲染坐标。
• 共享 meshlet metadata、按实例分组的剔除 work，以及版本化 GPU table 的脏区上传与 RenderGraph Copy 访问声明。
• 版本化 .weproject 显式项目入口：声明内容根、启动世界和 Windows 能力 profile，按项目隔离保存数据。
• 独立 CPU 导入/CLOD 和 WaveCooker：显式资产索引、世界/Mesh/Shader 运行包；相机轨迹录制/回放和真实 CPU 帧统计导出。
• 独立 WavePlayer：只加载运行包，以包内 DXIL 渲染并直接呈现到 Swapchain；支持交互相机和上传就绪后的有限帧运行，无源树、DXC 或编辑器 UI 依赖。
• 原生资源分配计账与单次分配准入、D3D12MA/OS 内存查询及 Player 退出前的 JSON 报告；实际分配字节与 OS 用量分开记录，尚无驻留控制或淘汰。
• 专业密度的原生编辑器 UI：统一设计组件、Ctrl+K 命令搜索、World / Analyze 独立布局恢复、目录式 Content Browser 与场景/属性/视口协同编辑。详见 UI 框架与交互。
• 独立变换 Gizmo：轴/平面移动、完整旋转环、比例缩放、相对吸附与精细拖动，保持单次 Undo 和 double 世界坐标。详见 Gizmo 操作与结构。
• 启动期依赖解析、冻结扩展快照的静态插件宿主；应用服务、渲染帧扩展和编辑器面板均可作为插件组合。
• 内置 CPU/GPU Trace 录制、独立 WaveTraceViewer，以及默认关闭的 RenderDoc 单帧捕获。需要捕获时，在启动进程前显式设置 WAVE_ENABLE_RENDERDOC=1；WAVE_RENDERDOC_PATH 只指定安装路径，不启用捕获。

环境

• Windows 10/11 x64
• Visual Studio 2022、MSVC v143、Windows SDK
• CMake 4.0.1 或更新版本
• 支持 DirectX 12、Shader Model 6.6 和 Mesh Shader 的显卡
• Path Tracing 另需 DXR Tier 1.1

构建与运行

cmake --preset vs2022-x64
cmake --build --preset editor-debug
& .\Build\Debug\WaveEditor.exe

无参数保留仓库开发启动。显式打开仓库样例项目使用 & .\Build\Debug\WaveEditor.exe --project .\WaveEngine.weproject；项目模式只使用声明的内容根和 Worlds/default.wescn，不会读取旧开发场景。格式与路径规则见项目入口。

显式项目支持有界相机录制与回放：

& .\Build\Debug\WaveEditor.exe --project .\WaveEngine.weproject --record-replay Replay/camera.wereplay --frames 600 --seed 42 --replay-stats Replay/record
& .\Build\Debug\WaveEditor.exe --project .\WaveEngine.weproject --replay Saved/Project/Replay/camera.wereplay --replay-stats Replay/playback

录制默认固定步长为 1/60 秒，可用 --fixed-step 指定；回放读取轨迹中的步长、seed 和帧数。初始资产上传期间固定相机并禁用输入，准备帧不计样本；等待超过 120 秒或 100000 次 Tick、或存在不可渲染资产时失败。完成指定帧数后正常关闭，轨迹与 CSV/JSON 原子写入 Saved/Project/，不会自动保存启动 world/config；中断导出已完成前缀并返回非零。GPU、上传与驻留等未采样指标保持空值。

离线 Cook 不创建窗口或 GPU：

cmake --build Build --config Release --target WaveCooker
& .\Build\Release\WaveCooker.exe --project .\WaveEngine.weproject --output Windows-x64

输出在项目的 Saved/Project/Cooked/Windows-x64/。启动世界可为 WESC v5–v7，引用网格的世界还需明确的 assetIndex；包只含启动世界、其引用的 Mesh、嵌入材质/纹理与运行时 Shader。Player 优先使用世界中的有效 Camera 组件。格式、预算及当前边界见 M3 离线 Cook。

独立 Player 加载该运行包：

cmake --build Build --config Release --target WavePlayer
& .\Build\Release\WavePlayer.exe --package .\Saved\Project\Cooked\Windows-x64\root.weapp
& .\Build\Release\WavePlayer.exe --package .\Saved\Project\Cooked\Windows-x64\root.weapp --frames 120
& .\Build\Release\WavePlayer.exe --package .\Saved\Project\Cooked\Windows-x64\root.weapp --frames 120 --trace
& .\Build\Release\WavePlayer.exe --package .\Saved\Project\Cooked\Windows-x64\root.weapp --frames 120 --trace --gpu-budget-mib 256

包目录随 WavePlayer.exe、D3D12Core.dll 部署；Debug 验证另需 d3d12SDKLayers.dll。Player 不加载 .weproject 或源资产，也不需要 DXC、HLSL、Editor 或 ImGui。--frames 1..1000000 在初始上传与 fence 发布完成后计数，完成指定数量的 Present 后自动正常退出；省略时保留右键/WASD 导航。--camera X Y Z / --look-at X Y Z 接受有限 double 世界坐标，默认取景包中第一个实体。当前照明与背景由宿主提供，项目相机、灯光和 Skybox 尚未打包。启动、隔离与验收细节见 M3 Player。

--trace 显式启用 CPU/GPU 文件录制，默认关闭。录制覆盖初始上传、渲染及 GPU idle 收尾，写入本次唯一的 UserSaved/Traces/player-<id>.wetrace，日志记录开始、停止与完整路径；启用失败会中止启动。可用 WaveTraceViewer 查看，或运行 Tools/Validation/InspectTrace.ps1 -TraceFile <file.wetrace> -RequireGpu 检查事件与文件完整性。

--gpu-budget-mib 64..65536 设置 Player 的原生资源分配总上限，单位 MiB；各 heap 的默认限制仍生效。这是应用分配策略，不是物理显存上限。默认 Default heap 取有效 OS Local budget 的 75%（最多 8 GiB），未知时取 4 GiB；Upload 为 256 MiB、Readback 为 64 MiB，总量最多 8 GiB。当前不随 OS 压力自动调节。预算不足时，Mesh 准备可以等待或局部拒绝；必需渲染资源被拒绝会在安全收尾后返回非零，不保证较低预算仍能启动。详细语义及实测值见 M4-B1 准入记录。

Player 在 GPU idle 成功后的关闭边界、销毁资源前，自动原子写入 UserSaved/Telemetry/memory.json，不要求启用 Trace。UserSaved 位于 %LOCALAPPDATA%/WaveEngine/Player/package-<canonical-package-path-hash>。报告按 heap/kind 记录仍存活的实际分配与峰值，另列准入限额、未消费预留、版本与估算偏差/拒绝计数，以及 D3D12MA 分配/块大小和 OS 用量/预算；未知数据为 null 并保留查询状态。它不是逐资源物理驻留测量，也不能凭单次退出快照证明无泄漏。口径与验证边界见当前引擎架构。

也可以直接使用 CMake：

cmake -S . -B Build -G "Visual Studio 17 2022" -A x64
cmake --build Build --config Debug --target WaveEditor

主要构建目标：

目标	内容
WaveThirdParty	非 ImGui 的 vendored 实现与第三方链接依赖
WaveImGui	ImGui 核心及 DX12/GLFW、DX11/Win32 backend object
WaveCore	基础设施、分配 ledger 与准入事务、Trace 公共能力、应用与插件宿主契约
WaveAssetData	仅依赖 WaveCore 的 CPU payload、WEMesh/WEScene、来源身份与索引、运行包 catalog 与单 Mesh 读取
WaveProject	项目描述、启动参数与显式资产索引 resolver
WaveAssetImportThirdParty / WaveAssetImport	独立 CPU 模型导入/CLOD，meshoptimizer 与 ufbx 实现归属
WaveShaderCook / WaveCookPipeline	CPU DXC 与离线世界/资产/Shader 打包
WaveCooker	无窗口、无 GPU 初始化的离线 Cook 程序
WaveShaderData	CPU Shader 注册元数据、运行 catalog 与包内 DXIL 结构验证，无 DXC/RHI
WavePlatform	Windows、窗口与输入平台层
WaveRenderCore	RHI、RenderGraph、包内 Shader 注入与渲染公共契约；不编译源 Shader
WaveRuntime	包内 Scene/Mesh、预算上传、Renderer 与运行时 Render Pass；源导入/保存归编辑器侧
WaveEditorShaders	编辑器 Shader 编译 provider 与 DXC，独立于 Player
WavePlayerCore	CPU CLI、PackageRuntime 路径、包预检、初始相机与有限帧控制
WavePlayerHost / WavePlayer	独立运行服务和可执行程序，复用 Runtime，直接呈现 Swapchain
WaveEditorCommon	Editor 与 TraceViewer 共用的 Style/Widgets 等 UI 基础
WaveEditorCore	编辑器宿主、Shell、专用 Render Pass 与 backend 接线
WaveBuiltinEditorPlugins	内置编辑器面板及其显式插件注册入口
WaveEditor	组合 Engine、Editor 与内置插件的编辑器可执行程序
WaveTraceViewer	DX11/Win32 独立 Trace 查看器

解决方案把代码导航与构建架构分开。Rider/Visual Studio 主树直接镜像仓库目录：Engine/Source、Engine/Shaders、Engine/ThirdParty、Tools、Tests 和 docs；所有 CMake 静态模块、程序及预定义目标统一收纳在折叠的 _BuildTargets。Modules、ThirdParty、Applications 等不再作为额外的 target 分类目录。这里的 Engine/ThirdParty 只是正常物理源码目录，不是独立架构分组。

模块仍是独立 build target，每个 .cpp/translation unit 只有一个编译归属；solution-level 文件只用于浏览，不参与第二次编译。静态链接器按引用抽取 object，因此 Editor 与 TraceViewer 不会互相带入对方的 ImGui backend。重新运行 CMake 后在 Rider Reload Solution 即可，不依赖任何 Explorer 显示开关。

插件是显式注册和组合边界，不等于 DLL。WaveEditorCore 不依赖任何具体插件；只有 WaveEditor 组合根链接 WaveBuiltinEditorPlugins 并把它注入宿主。插件依赖解析和启用选择只发生在启动期，冻结后帧内调度直接遍历连续指针表，不增加动态发现、字符串查找、锁或分配。

可选验证目标默认不参与常规构建：

cmake -S . -B Build -DWAVE_BUILD_TESTS=ON -DWAVE_BUILD_BENCHMARKS=ON
cmake --build Build --config Debug
ctest --test-dir Build -C Debug --output-on-failure
cmake --build Build --config Release --target WavePluginDispatchBenchmark
& .\Build\Release\WavePluginDispatchBenchmark.exe

CPU 调度基准目标为 WaveJobSystemBenchmark。真实 DX12 启动/退出检查可运行 Tools/Validation/SmokeEditor.ps1 -Scene Cube -Workspace World；独立包检查使用 Tools/Validation/SmokePlayer.ps1 -Configuration Debug -PackageFile <root.weapp> -FrameCount 120 -RequireMemoryReport -RecordTrace -GPUAllocationBudgetMiB 256。脚本要求内存对账、准入值符合限额，以及包含 CPU/GPU 事件、无丢事件且完整结束的 Trace；-Interactive -ResizeWindow -CaptureWindow 另覆盖窗口 resize、持续运行、截图与正常关闭。脚本在 .tmp/Validation/ 创建保留的隔离目录，仅操作自己启动的 PID，并检查日志与文件未变；PrintWindow 截图需肉眼确认。有限帧启动检查不能替代完整大世界基准、跨原点/拾取/Undo 的交互验收。最新范围见 M4-B1 准入记录，M3 历史范围见 Player 实施记录。

目录

• Engine/Source/：当前引擎、编辑器与内置插件源码；其编译所有权由上述静态模块严格划分。
• Engine/Shaders/：HLSL Shader。
• Engine/ThirdParty/：随仓库提供的第三方依赖。
• Assets/：示例资产。
• WaveEngine.weproject、Worlds/：显式项目样例与独立启动世界。
• Tools/TraceViewer/：Trace 查看器。
• docs/architecture/：当前实现说明。

当前边界

• 仅实现 DirectX 12 后端；Vulkan 只有预留宏入口。
• 重点是静态场景编辑与渲染；已有离线 Cook、运行包与独立 Player，尚无完整 Gameplay、物理、音频或应用发布链。
• RenderGraph 当前使用单 Direct Queue、整资源状态，不含异步 Compute/Copy、subresource barrier、aliasing 或 pass culling。
• GPU Scene 已按脏槽位更新实例表，复用共享 meshlet 目录及空闲 GPU table 版本；dirty 检测仍扫描全部实例，拓扑变化仍全量更新目录、work 和实例表，原点变化更新全部实例。
• 默认场景与编辑器导入已使用跨帧 Mesh 上传队列：每 Tick 最多 8 MiB、64 块、8 次资源创建，在途传输上限 32 MiB；2 ms 为软时间上限。待发布 CPU/GPU payload 各 2 GiB 是排队估算，不是实际 CPU 存储或显存驻留预算。D3D12MA 资源创建已统一受单次分配准入控制；同步 promotion、Skybox/IBL/AS 等仍不全部受 Mesh 队列的每帧配额限制。单视图候选 meshlet 上限为 4,194,240，超出拒绝，尚不自动拆分 dispatch。
• Mesh 准备及上传记录将暂时容量不足作为 Deferred、永久过大作为资产局部拒绝；后者保留实体与原因、不反复入队，内容替换通知后允许重试。Deferred 上传在 producer 预留 staging，payload 同持 reservation/permit，worker 唯一 Claim；已完成 fence 的命令资源可在无新 GPU 提交时回收。尚无整 Mesh 预留或 staging/render 最低容量隔离；原生创建失败、预算中途缩小导致 Commit 拒绝仍走提交失败路径。
• double 位置解决坐标表示与相对渲染精度，不提供世界分区、驻留淘汰或地形系统。CPU 运行包已有不可变 catalog 和按 AssetId 单独读取 Mesh 的接口；Player 仍一次读取整个启动包，再分帧上传。分区流送、异步按需读取、消费 lease、受管理 CPU 存储预算和驻留淘汰尚未接入，M4 未完成。
• glTF 的 AlphaMode、双面、UV1 和逐纹理 sampler 尚未完整实现。

更多细节见当前引擎架构和插件架构与开发约束。

面向大型开放世界技术探索的目标方案见开放世界重设计，分阶段结果见 M0、M1、M2 GPU Scene、上传/回放续作、M3 离线 Cook、M3 Player、M4-B1 准入及 M4-B2 staging。最新边界的 Debug/Release 各38目标构建、各35/35 CPU测试及8份实际运行报告通过：包含跨线程预留与无新提交回收、Editor三模式、Player两配置256MiB各120帧、Debug resize、64MiB预期拒绝后安全退出及默认Trace关闭。结果证明本片事务与收尾，不构成驻留或开放世界性能验收；M1/M2剩余组合验收及M4–M6总目标仍未完成。