DX12光线追踪程序启动崩溃求助（附核心代码）

命中签名与着色器绑定一致性检查 #

• 核对Hit.hlsl中命中着色器的输入参数与命中签名创建时的布局：
  • 确保命中签名声明的CBV/SRV数量、类型、注册槽位，与HLSL中[shader("closesthit")]函数的资源绑定完全匹配。比如HLSL里写了cbuffer LightCB : register(b0)，命中签名必须对应预留b0槽位的CBV条目。
  • 排查是否存在未声明的资源引用：如果Hit着色器中调用了光照相关的SRV，但命中签名未添加对应条目，会直接导致绑定失败触发崩溃。
• 验证D3D12_HIT_GROUP_DESC配置：
  • 确认HitGroupType与几何体类型匹配：场景中的四面体和平面属于三角形网格，必须设置为D3D12_HIT_GROUP_TYPE_TRIANGLES，错误设置为 procedural 类型会导致管线不兼容。
  • 检查着色器入口点名称：AnyHitShaderImport、ClosestHitShaderImport的字符串必须与HLSL编译后的入口点完全一致（DX12对大小写敏感，注意拼写）。

着色器资源堆（Descriptor Heap）问题排查 #

• 确认光照资源的堆类型与可见性：
  • 光照常量缓冲区必须使用D3D12_DESCRIPTOR_HEAP_TYPE_CBV_SRV_UAV类型的堆，且创建堆时必须指定D3D12_DESCRIPTOR_HEAP_FLAG_SHADER_VISIBLE，否则着色器无法访问资源。
  • 计算描述符偏移时必须调用device->GetDescriptorHandleIncrementSize()获取正确值，禁止手动硬编码，不同GPU的描述符增量大小可能不同，硬编码会导致偏移错误。
• 检查堆容量：添加光照模块后新增的CBV/SRV是否超出了堆的初始创建大小，若堆容量不足，会导致描述符写入越界崩溃。

着色器绑定表（SBT）验证 #

• 确认SBT条目大小与对齐要求：
  • 每个SBT条目的大小必须是D3D12_RAYTRACING_SHADER_TABLE_BYTE_ALIGNMENT（256字节）的整数倍，必须通过RaytracingPipeline->GetShaderTableSize()获取官方计算的大小，禁止自行估算。
  • 检查命中组条目与资源的绑定：如果光照CBV绑定在命中签名中，SBT条目必须正确包含指向该CBV的描述符指针；若通过根签名传递，需确认根参数的绑定逻辑无误。
• 检查SBT内存初始化：
  • SBT的GPU内存必须使用D3D12_HEAP_TYPE_UPLOAD或配合上传堆的D3D12_HEAP_TYPE_DEFAULT创建，写入条目时不能超出分配的内存范围，越界写入会直接触发崩溃。

HLSL核心代码问题排查 #

• Common.hlsl：
  • 确保CPU端与HLSL端的光照常量缓冲区结构体完全一致：成员顺序、数据类型、字节对齐必须严格匹配，比如CPU端用float3，HLSL里不能用float4，否则会导致数据解析错误。
  • 核对全局光照资源的注册槽位：比如cbuffer LightCB : register(b0)，根签名或命中签名中对应的参数必须绑定到b0槽，槽位不匹配会导致资源访问失败。
• Hit.hlsl：
  • 检查Closest Hit着色器中光照资源的访问逻辑：避免在未确认资源有效时直接读取，比如引用了未绑定的SRV/CBV。
  • 临时移除阴影相关代码：之前阴影未生效，可能遗留了错误的TraceRay调用参数，先注释掉阴影代码，确认程序能正常运行后再逐步恢复，排查是否是阴影与光照代码冲突。

新手友好的调试技巧 #

• 开启DX12调试层：创建设备时添加D3D12_CREATE_DEVICE_DEBUG标志，运行时会弹出调试输出窗口，里面会明确输出崩溃的具体原因（比如“根签名与着色器不匹配”“描述符堆访问越界”等），这是最高效的排查方式。
• 逐步注释排查：先完全注释掉光照模块的代码，确认程序能正常启动，然后逐行恢复光照相关代码，每次运行验证是否崩溃，快速定位到触发崩溃的具体代码行。

内容的提问来源于stack exchange，提问作者HeroOfSkies