# VK_NV_ray_tracing(3) Manual Page

## Name

VK_NV_ray_tracing - device extension

Loading… please wait.

## Registered Extension Number

166

## Revision

3

## Ratification Status

Not ratified

## Extension and Version Dependencies

VK_KHR_get_physical_device_properties2
and
VK_KHR_get_memory_requirements2
or
Vulkan Version 1.1

## API Interactions

- Interacts with VK_VERSION_1_1

- Interacts with VK_EXT_debug_report

- Interacts with VK_KHR_get_memory_requirements2

## SPIR-V Dependencies

- SPV_NV_ray_tracing

## Deprecation State

- Deprecated by VK_KHR_ray_tracing_pipeline extension

## Contact

- Eric Werness [GitHub]ewerness-nv

## Other Extension Metadata

Last Modified Date

  2018-11-20

Interactions and External Dependencies

  - This extension provides API support for `GL_NV_ray_tracing`

Contributors

  - Eric Werness, NVIDIA

  - Ashwin Lele, NVIDIA

  - Robert Stepinski, NVIDIA

  - Nuno Subtil, NVIDIA

  - Christoph Kubisch, NVIDIA

  - Martin Stich, NVIDIA

  - Daniel Koch, NVIDIA

  - Jeff Bolz, NVIDIA

  - Joshua Barczak, Intel

  - Tobias Hector, AMD

  - Henrik Rydgard, NVIDIA

  - Pascal Gautron, NVIDIA

## Description

Rasterization has been the dominant method to produce interactive graphics, but increasing performance of graphics hardware has made ray tracing a viable option for interactive rendering. Being able to integrate ray tracing with traditional rasterization makes it easier for applications to incrementally add ray traced effects to existing applications or to do hybrid approaches with rasterization for primary visibility and ray tracing for secondary queries.

To enable ray tracing, this extension adds a few different categories of new functionality:

- Acceleration structure objects and build commands

- A new pipeline type with new shader domains

- An indirection table to link shader groups with acceleration structure items

This extension adds support for the following SPIR-V extension in Vulkan:

- `SPV_NV_ray_tracing`

## New Object Types

- VkAccelerationStructureNV

## New Commands

- vkBindAccelerationStructureMemoryNV

- vkCmdBuildAccelerationStructureNV

- vkCmdCopyAccelerationStructureNV

- vkCmdTraceRaysNV

- vkCmdWriteAccelerationStructuresPropertiesNV

- vkCompileDeferredNV

- vkCreateAccelerationStructureNV

- vkCreateRayTracingPipelinesNV

- vkDestroyAccelerationStructureNV

- vkGetAccelerationStructureHandleNV

- vkGetAccelerationStructureMemoryRequirementsNV

- vkGetRayTracingShaderGroupHandlesNV

## New Structures

- VkAabbPositionsNV

- VkAccelerationStructureCreateInfoNV

- VkAccelerationStructureInfoNV

- VkAccelerationStructureInstanceNV

- VkAccelerationStructureMemoryRequirementsInfoNV

- VkBindAccelerationStructureMemoryInfoNV

- VkGeometryAABBNV

- VkGeometryDataNV

- VkGeometryNV

- VkGeometryTrianglesNV

- VkRayTracingPipelineCreateInfoNV

- VkRayTracingShaderGroupCreateInfoNV

- VkTransformMatrixNV

- Extending VkPhysicalDeviceProperties2:

  - VkPhysicalDeviceRayTracingPropertiesNV

- Extending VkWriteDescriptorSet:

  - VkWriteDescriptorSetAccelerationStructureNV

If VK_KHR_get_memory_requirements2 or Vulkan Version 1.1 is supported:

- VkMemoryRequirements2KHR

## New Enums

- VkAccelerationStructureMemoryRequirementsTypeNV

- VkAccelerationStructureTypeNV

- VkBuildAccelerationStructureFlagBitsNV

- VkCopyAccelerationStructureModeNV

- VkGeometryFlagBitsNV

- VkGeometryInstanceFlagBitsNV

- VkGeometryTypeNV

- VkRayTracingShaderGroupTypeNV

## New Bitmasks

- VkBuildAccelerationStructureFlagsNV

- VkGeometryFlagsNV

- VkGeometryInstanceFlagsNV

## New Enum Constants

- `VK_NV_RAY_TRACING_EXTENSION_NAME`

- `VK_NV_RAY_TRACING_SPEC_VERSION`

- `VK_SHADER_UNUSED_NV`

- Extending VkAccelerationStructureTypeKHR:

  - `VK_ACCELERATION_STRUCTURE_TYPE_BOTTOM_LEVEL_NV`

  - `VK_ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_NV`

- Extending VkAccessFlagBits:

  - `VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_NV`

  - `VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_NV`

- Extending VkBufferUsageFlagBits:

  - `VK_BUFFER_USAGE_RAY_TRACING_BIT_NV`

- Extending VkBuildAccelerationStructureFlagBitsKHR:

  - `VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_NV`

  - `VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_UPDATE_BIT_NV`

  - `VK_BUILD_ACCELERATION_STRUCTURE_LOW_MEMORY_BIT_NV`

  - `VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_BUILD_BIT_NV`

  - `VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_NV`

- Extending VkCopyAccelerationStructureModeKHR:

  - `VK_COPY_ACCELERATION_STRUCTURE_MODE_CLONE_NV`

  - `VK_COPY_ACCELERATION_STRUCTURE_MODE_COMPACT_NV`

- Extending VkDescriptorType:

  - `VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NV`

- Extending VkGeometryFlagBitsKHR:

  - `VK_GEOMETRY_NO_DUPLICATE_ANY_HIT_INVOCATION_BIT_NV`

  - `VK_GEOMETRY_OPAQUE_BIT_NV`

- Extending VkGeometryInstanceFlagBitsKHR:

  - `VK_GEOMETRY_INSTANCE_FORCE_NO_OPAQUE_BIT_NV`

  - `VK_GEOMETRY_INSTANCE_FORCE_OPAQUE_BIT_NV`

  - `VK_GEOMETRY_INSTANCE_TRIANGLE_CULL_DISABLE_BIT_NV`

  - `VK_GEOMETRY_INSTANCE_TRIANGLE_FRONT_COUNTERCLOCKWISE_BIT_NV`

- Extending VkGeometryTypeKHR:

  - `VK_GEOMETRY_TYPE_AABBS_NV`

  - `VK_GEOMETRY_TYPE_TRIANGLES_NV`

- Extending VkIndexType:

  - `VK_INDEX_TYPE_NONE_NV`

- Extending VkObjectType:

  - `VK_OBJECT_TYPE_ACCELERATION_STRUCTURE_NV`

- Extending VkPipelineBindPoint:

  - `VK_PIPELINE_BIND_POINT_RAY_TRACING_NV`

- Extending VkPipelineCreateFlagBits:

  - `VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV`

- Extending VkPipelineStageFlagBits:

  - `VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_NV`

  - `VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_NV`

- Extending VkQueryType:

  - `VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV`

- Extending VkRayTracingShaderGroupTypeKHR:

  - `VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV`

  - `VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV`

  - `VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV`

- Extending VkShaderStageFlagBits:

  - `VK_SHADER_STAGE_ANY_HIT_BIT_NV`

  - `VK_SHADER_STAGE_CALLABLE_BIT_NV`

  - `VK_SHADER_STAGE_CLOSEST_HIT_BIT_NV`

  - `VK_SHADER_STAGE_INTERSECTION_BIT_NV`

  - `VK_SHADER_STAGE_MISS_BIT_NV`

  - `VK_SHADER_STAGE_RAYGEN_BIT_NV`

- Extending VkStructureType:

  - `VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_INFO_NV`

  - `VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_INFO_NV`

  - `VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_INFO_NV`

  - `VK_STRUCTURE_TYPE_BIND_ACCELERATION_STRUCTURE_MEMORY_INFO_NV`

  - `VK_STRUCTURE_TYPE_GEOMETRY_AABB_NV`

  - `VK_STRUCTURE_TYPE_GEOMETRY_NV`

  - `VK_STRUCTURE_TYPE_GEOMETRY_TRIANGLES_NV`

  - `VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_PROPERTIES_NV`

  - `VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_CREATE_INFO_NV`

  - `VK_STRUCTURE_TYPE_RAY_TRACING_SHADER_GROUP_CREATE_INFO_NV`

  - `VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_ACCELERATION_STRUCTURE_NV`

If VK_EXT_debug_report is supported:

- Extending VkDebugReportObjectTypeEXT:

  - `VK_DEBUG_REPORT_OBJECT_TYPE_ACCELERATION_STRUCTURE_NV_EXT`

## New or Modified Built-In Variables

- `LaunchIdNV`

- `LaunchSizeNV`

- `WorldRayOriginNV`

- `WorldRayDirectionNV`

- `ObjectRayOriginNV`

- `ObjectRayDirectionNV`

- `RayTminNV`

- `RayTmaxNV`

- `InstanceCustomIndexNV`

- `InstanceId`

- `ObjectToWorldNV`

- `WorldToObjectNV`

- `HitTNV`

- `HitKindNV`

- `IncomingRayFlagsNV`

- (modified)`PrimitiveId`

## New SPIR-V Capabilities

- `RayTracingNV`

## Issues

1) Are there issues?

RESOLVED: Yes.

## Sample Code

Example ray generation GLSL shader

    #version 450 core
    #extension GL_NV_ray_tracing : require
    layout(set = 0, binding = 0, rgba8) uniform image2D image;
    layout(set = 0, binding = 1) uniform accelerationStructureNV as;
    layout(location = 0) rayPayloadNV float payload;

    void main()
    {
       vec4 col = vec4(0, 0, 0, 1);

       vec3 origin = vec3(float(gl_LaunchIDNV.x)/float(gl_LaunchSizeNV.x), float(gl_LaunchIDNV.y)/float(gl_LaunchSizeNV.y), 1.0);
       vec3 dir = vec3(0.0, 0.0, -1.0);

       traceNV(as, 0, 0xff, 0, 1, 0, origin, 0.0, dir, 1000.0, 0);

       col.y = payload;

       imageStore(image, ivec2(gl_LaunchIDNV.xy), col);
    }

## Version History

- Revision 1, 2018-09-11 (Robert Stepinski, Nuno Subtil, Eric Werness)

  - Internal revisions

- Revision 2, 2018-10-19 (Eric Werness)

  - rename to VK_NV_ray_tracing, add support for callables.

  - too many updates to list

- Revision 3, 2018-11-20 (Daniel Koch)

  - update to use InstanceId instead of InstanceIndex as implemented.

## See Also

No cross-references are available

## Document Notes

For more information, see the Vulkan Specification

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

## Copyright

Copyright 2014-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0