Ray Tracing Validation at the Driver Level

Summary

Ray tracing validation at the driver level is a critical tool for developers working on DirectX 12 and Vulkan applications. It helps identify potential problems that cannot be caught by existing debug solutions, improving performance and debugging capabilities. This article explains how to enable and use ray tracing validation, its requirements, and what it checks for.

Understanding Ray Tracing Validation

Ray tracing validation is a method of graphics rendering that simulates the physical behavior of light. It is used in real-time path tracing to provide true-to-life shadows, reflections, and global illumination. Unlike rasterization, which casts rays from a single point and stops at the first thing they hit, ray tracing casts rays from many points in any direction, and path tracing randomly samples all lights in a scene.

How Ray Tracing Validation Works

Ray tracing validation performs checks at the driver level, enabling it to identify potential problems that cannot be caught by tools such as the D3D12 Debug Layer and Vulkan Validation Layer. Warnings and errors are delivered straight from the driver to the application with a callback, where they can be processed through existing application-side debugging or logging systems.

Requirements

To use ray tracing validation with DirectX 12, you need an NVIDIA driver from version 551.61 or later, and a version of NVIDIA API (NvAPI) 545 or later. For Vulkan, you need an NVIDIA driver from version 560.70 for Windows or version 560.28.03 for Linux.

Enabling Ray Tracing Validation

To enable ray tracing validation, you need to set the NV_ALLOW_RAYTRACING_VALIDATION=1 environment variable on your development machine. This will require a restart of your IDE, and if the NVAPI_ACCESS_DENIED error persists, a machine restart may be required.

DirectX 12 Example

Here is an example of how to enable and use ray tracing validation in a DirectX 12 application:

1. Create a D3D12 device: Create a D3D12 device and initialize NVAPI.
2. Enable ray tracing validation: Enable ray tracing validation on this device with the NvAPI_D3D12_EnableRaytracingValidation function.
3. Register a callback: Register a callback with the NvAPI_D3D12_RegisterRaytracingValidationMessageCallback function to output to your debugger or logging system of choice.
4. Flush validation messages: Flush validation messages to the registered callback after fence signals or in your device-removal handler with the NvAPI_D3D12_FlushRaytracingValidationMessages function.

Vulkan Example

Here is an example of how to enable and use ray tracing validation in a Vulkan application:

1. Set the environment variable: Set the NV_ALLOW_RAYTRACING_VALIDATION=1 environment variable on your development machine.
2. Enable the extension: Enable the VK_NV_ray_tracing_validation extension and set its feature bit rayTracingValidation to true.
3. Register a callback: Register a callback with the VK_EXT_debug_utils extension message callbacks.
4. Check for support: Check for ray tracing validation support and enable the feature by passing the VkPhysicalDeviceRayTracingValidationFeaturesNV structure to the pNext chain of VkDeviceCreateInfo.

What is Being Validated?

Ray tracing validation reports on certain error conditions that can lead to hard-to-debug faults or corruptions with ray tracing and build acceleration structure calls. For DirectX 12, the validation occurs within DispatchRays and BuildRaytracingAccelerationStructure calls. For Vulkan, the validation occurs within vkCmdTraceRaysKHR and vkCmdBuildAccelerationStructuresKHR calls.

Validation Checks

Validation checks include:

• Unexpected SBT record shader type: Encountering a miss shader entry when expecting a hit group.
• SBT references a shader that is not part of the pipeline: SBT references a shader that is not part of the pipeline.
• Out-of-bounds SBT entry: Out-of-bounds SBT entry.
• Shader payload type mismatch: Shader payload type mismatch, when the invoked shader expects a type different than that passed to TraceRay.
• Maximum trace depth exceeded: Maximum trace depth exceeded.
• Stack overflow: Stack overflow.
• Performance warnings for inefficient acceleration structures: Performance warnings for inefficient acceleration structures.
• Excessive degenerated triangle use in re-fittable, bottom-level ASs: Excessive degenerated triangle use in re-fittable, bottom-level ASs.
• Bad vertex data: Bad vertex data, such as NaNs and large numbers.
• Ill-conditioned geometry or instance transforms: Ill-conditioned geometry or instance transforms.
• Incomplete source acceleration structures used for refitting, copying or TLAS builds: Incomplete source acceleration structures used for refitting, copying or TLAS builds.
• Vertex, OMM, or DMM input index out-of-bounds check: Vertex, OMM, or DMM input index out-of-bounds check.
• Altered flags between AS build and refit: Altered flags between AS build and refit.

Example Output

Here are a few examples of the driver’s validation output:

• UNKNOWN_ENTRY_FUNCTION error: An application might build a new ray tracing pipeline for the next frame and update the shader binding table (SBT) that is still in use for the current frame. This could lead to a potential fault on missing entries in the SBT in the current frame. Ray tracing validation reports an UNKNOWN_ENTRY_FUNCTION error along with error-specific details, guiding you to the root cause of the fault.

Table: Comparison of Ray Tracing Validation Requirements

Table: Ray Tracing Validation Checks

Conclusion

Ray tracing validation at the driver level is a powerful tool for developers working on DirectX 12 and Vulkan applications. It helps identify potential problems that cannot be caught by existing debug solutions, improving performance and debugging capabilities. By following the steps outlined in this article, you can enable and use ray tracing validation to improve your application’s performance and stability.