XCEngine/docs/api/XCEngine/RHI/D3D12/D3D12CommandList/D3D12CommandList.md

D3D12CommandList

命名空间: XCEngine::RHI

类型: class

头文件: XCEngine/RHI/D3D12/D3D12CommandList.h

描述: D3D12 后端的图形/计算命令列表封装，负责记录 barrier、render pass、管线绑定、描述符绑定、绘制与 dispatch。

概览

D3D12CommandList 对应一条真实的 ID3D12GraphicsCommandList。它不是高层 render graph，也不是自动同步系统，而是更接近“backend recorder”的薄层实现。

这类类型在商业引擎里通常承担两件事：

• 把抽象 RHI 命令翻译成 D3D12 调用
• 在不引入太多调度系统复杂度的前提下，补一层最基本的状态缓存和参数装配

生命周期

• Initialize() 需要外部设备和 command allocator
• Reset() 重新开始录制，并清空软件侧状态缓存
• Close() 结束录制
• 提交由 D3D12CommandQueue 完成

当前实现的真实行为

资源状态与 barrier

• TransitionBarrier 会直接发出 ResourceBarrier
• 同时把 stateAfter 记入 m_resourceStateMap
• 这份状态表只是本命令列表内的软跟踪，不等同于跨队列、跨帧的全局真值

管线与描述符绑定

• SetPipelineState 会先调用 EnsureValid()
• Graphics 路径依赖 graphics PSO 和 graphics root signature
• Compute 路径会改走 SetComputeRootSignature() 和 compute pipeline state
• SetGraphicsDescriptorSets / SetComputeDescriptorSets 会根据 D3D12PipelineLayout 的映射，把 CBV 写到 root CBV，把 SRV/UAV/Sampler 绑定到 descriptor table

Render pass 与输出目标

• BeginRenderPass 当前更像“根据 D3D12RenderPass 描述执行清屏并调用 OMSetRenderTargets”
• EndRenderPass() 目前是空实现，不会生成额外 D3D12 结束命令
• SetRenderTargets 直接消费传入的 D3D12ResourceView CPU handle

绘制与计算

• Draw / DrawIndexed 直接转发到 DrawInstanced / DrawIndexedInstanced
• Dispatch 直接转发到 ID3D12GraphicsCommandList::Dispatch
• 间接绘制/间接 dispatch 相关内部接口当前调用 ExecuteIndirect(nullptr, ...)，说明这条能力还处在占位或未完工状态

值得注意的限制

• SetDepthBias() 目前为空实现
• EndRenderPass() 目前为空实现
• ClearDepthStencilView(ID3D12Resource* ...) 这一重载内部构造的是空 DSV handle，实用路径应优先走 view/handle 版本
• SetRenderTargetsInternal() 传入的是空 descriptor handle 数组，属于低层占位接口，不应视为成熟主路径

线程语义

命令列表对象没有显式并发保护。建议把它视为：

• 单线程录制对象
• 一次只由一个提交上下文持有和驱动

重点公共方法

• TransitionBarrier
• BeginRenderPass
• SetPipelineState
• SetGraphicsDescriptorSets
• SetComputeDescriptorSets
• SetRenderTargets
• SetVertexBuffers
• SetIndexBuffer
• Clear
• CopyResource
• Draw
• DrawIndexed
• Dispatch

相关文档

• D3D12
• D3D12Device
• D3D12CommandQueue
• D3D12DescriptorSet
• D3D12PipelineLayout