VK_KHR_ray_tracing(3)

# VK_KHR_ray_tracing(3) Manual Page

## Name

VK_KHR_ray_tracing - device extension

Loading… please wait.

## Registered Extension Number

151

## Revision

8

## Extension and Version Dependencies

- Requires Vulkan 1.0

- Requires `VK_KHR_get_physical_device_properties2`

- Requires `VK_KHR_get_memory_requirements2`

- Requires `VK_EXT_descriptor_indexing`

- Requires `VK_KHR_buffer_device_address`

- Requires `VK_KHR_deferred_host_operations`

- Requires `VK_KHR_pipeline_library`

- This is a provisional extension and must be used with caution. See the description of provisional header files for enablement and stability details.

### Other Extension Metadata

Last Modified Date

  2020-02-28

Interactions and External Dependencies

  - This extension requires the `SPV_KHR_ray_tracing` and `SPV_KHR_ray_query` SPIR-V extensions.

  - This extension requires the `GLSL_EXT_ray_tracing` and `GLSL_EXT_ray_query` extensions for GLSL source languages.

Contributors

  - Matthäus Chajdas, AMD

  - Greg Grebe, AMD

  - Nicolai Hähnle, AMD

  - Tobias Hector, AMD

  - Dave Oldcorn, AMD

  - Skyler Saleh, AMD

  - Mathieu Robart, Arm

  - Marius Bjorge, Arm

  - Tom Olson, Arm

  - Sebastian Tafuri, EA

  - Henrik Rydgard, Embark

  - Juan Cañada, Epic Games

  - Patrick Kelly, Epic Games

  - Yuriy O’Donnell, Epic Games

  - Michael Doggett, Facebook/Oculus

  - Don Scorgie, Imagination

  - Dae Kim, Imagination

  - Joshua Barczak, Intel

  - Slawek Grajewski, Intel

  - Jeff Bolz, NVIDIA

  - Pascal Gautron, NVIDIA

  - Daniel Koch, NVIDIA

  - Christoph Kubisch, NVIDIA

  - Ashwin Lele, NVIDIA

  - Robert Stepinski, NVIDIA

  - Martin Stich, NVIDIA

  - Nuno Subtil, NVIDIA

  - Eric Werness, NVIDIA

  - Jon Leech, Khronos

  - Jeroen van Schijndel, OTOY

  - Juul Joosten, OTOY

  - Alex Bourd, Qualcomm

  - Roman Larionov, Qualcomm

  - David McAllister, Qualcomm

  - Andrew Garrard, Samsung

  - Lewis Gordon, Samsung

  - Ralph Potter, Samsung

  - Jasper Bekkers, Traverse Research

  - Jesse Barker, Unity

  - Baldur Karlsson, Valve

### 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

Additionally, ray queries are available to other shader types outside of the dedicated ray tracing pipeline. Unlike `OpTraceRayKHR`, ray queries are not able to launch additional shaders, instead returning traversal results to the calling shader.

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

- `SPV_KHR_ray_tracing`

- `SPV_KHR_ray_query`

### New Object Types

- VkAccelerationStructureKHR

### New Commands

- vkBindAccelerationStructureMemoryKHR

- vkBuildAccelerationStructureKHR

- vkCmdBuildAccelerationStructureIndirectKHR

- vkCmdBuildAccelerationStructureKHR

- vkCmdCopyAccelerationStructureKHR

- vkCmdCopyAccelerationStructureToMemoryKHR

- vkCmdCopyMemoryToAccelerationStructureKHR

- vkCmdTraceRaysIndirectKHR

- vkCmdTraceRaysKHR

- vkCmdWriteAccelerationStructuresPropertiesKHR

- vkCopyAccelerationStructureKHR

- vkCopyAccelerationStructureToMemoryKHR

- vkCopyMemoryToAccelerationStructureKHR

- vkCreateAccelerationStructureKHR

- vkCreateRayTracingPipelinesKHR

- vkDestroyAccelerationStructureKHR

- vkGetAccelerationStructureDeviceAddressKHR

- vkGetAccelerationStructureMemoryRequirementsKHR

- vkGetDeviceAccelerationStructureCompatibilityKHR

- vkGetRayTracingCaptureReplayShaderGroupHandlesKHR

- vkGetRayTracingShaderGroupHandlesKHR

- vkWriteAccelerationStructuresPropertiesKHR

### New Structures

- VkAabbPositionsKHR

- VkAccelerationStructureBuildGeometryInfoKHR

- VkAccelerationStructureBuildOffsetInfoKHR

- VkAccelerationStructureCreateGeometryTypeInfoKHR

- VkAccelerationStructureCreateInfoKHR

- VkAccelerationStructureDeviceAddressInfoKHR

- VkAccelerationStructureGeometryAabbsDataKHR

- VkAccelerationStructureGeometryInstancesDataKHR

- VkAccelerationStructureGeometryKHR

- VkAccelerationStructureGeometryTrianglesDataKHR

- VkAccelerationStructureInstanceKHR

- VkAccelerationStructureMemoryRequirementsInfoKHR

- VkAccelerationStructureVersionKHR

- VkBindAccelerationStructureMemoryInfoKHR

- VkCopyAccelerationStructureInfoKHR

- VkCopyAccelerationStructureToMemoryInfoKHR

- VkCopyMemoryToAccelerationStructureInfoKHR

- VkRayTracingPipelineCreateInfoKHR

- VkRayTracingPipelineInterfaceCreateInfoKHR

- VkRayTracingShaderGroupCreateInfoKHR

- VkStridedBufferRegionKHR

- VkTraceRaysIndirectCommandKHR

- VkTransformMatrixKHR

- Extending VkPhysicalDeviceFeatures2, VkDeviceCreateInfo:

  - VkPhysicalDeviceRayTracingFeaturesKHR

- Extending VkPhysicalDeviceProperties2:

  - VkPhysicalDeviceRayTracingPropertiesKHR

- Extending VkWriteDescriptorSet:

  - VkWriteDescriptorSetAccelerationStructureKHR

### New Unions

- VkAccelerationStructureGeometryDataKHR

- VkDeviceOrHostAddressConstKHR

- VkDeviceOrHostAddressKHR

### New Enums

- VkAccelerationStructureBuildTypeKHR

- VkAccelerationStructureMemoryRequirementsTypeKHR

- VkAccelerationStructureTypeKHR

- VkBuildAccelerationStructureFlagBitsKHR

- VkCopyAccelerationStructureModeKHR

- VkGeometryFlagBitsKHR

- VkGeometryInstanceFlagBitsKHR

- VkGeometryTypeKHR

- VkRayTracingShaderGroupTypeKHR

### New Bitmasks

- VkBuildAccelerationStructureFlagsKHR

- VkGeometryFlagsKHR

- VkGeometryInstanceFlagsKHR

### New Enum Constants

- `VK_KHR_RAY_TRACING_EXTENSION_NAME`

- `VK_KHR_RAY_TRACING_SPEC_VERSION`

- `VK_SHADER_UNUSED_KHR`

- Extending VkAccessFlagBits:

  - `VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR`

  - `VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_KHR`

- Extending VkBufferUsageFlagBits:

  - `VK_BUFFER_USAGE_RAY_TRACING_BIT_KHR`

- Extending VkDebugReportObjectTypeEXT:

  - `VK_DEBUG_REPORT_OBJECT_TYPE_ACCELERATION_STRUCTURE_KHR_EXT`

- Extending VkDescriptorType:

  - `VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_KHR`

- Extending VkFormatFeatureFlagBits:

  - `VK_FORMAT_FEATURE_ACCELERATION_STRUCTURE_VERTEX_BUFFER_BIT_KHR`

- Extending VkGeometryTypeKHR:

  - `VK_GEOMETRY_TYPE_INSTANCES_KHR`

- Extending VkIndexType:

  - `VK_INDEX_TYPE_NONE_KHR`

- Extending VkObjectType:

  - `VK_OBJECT_TYPE_ACCELERATION_STRUCTURE_KHR`

- Extending VkPipelineBindPoint:

  - `VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR`

- Extending VkPipelineCreateFlagBits:

  - `VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR`

  - `VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR`

  - `VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR`

  - `VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR`

  - `VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR`

  - `VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR`

- Extending VkPipelineStageFlagBits:

  - `VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR`

  - `VK_PIPELINE_STAGE_RAY_TRACING_SHADER_BIT_KHR`

- Extending VkQueryType:

  - `VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR`

  - `VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR`

- Extending VkResult:

  - `VK_ERROR_INCOMPATIBLE_VERSION_KHR`

- Extending VkShaderStageFlagBits:

  - `VK_SHADER_STAGE_ANY_HIT_BIT_KHR`

  - `VK_SHADER_STAGE_CALLABLE_BIT_KHR`

  - `VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR`

  - `VK_SHADER_STAGE_INTERSECTION_BIT_KHR`

  - `VK_SHADER_STAGE_MISS_BIT_KHR`

  - `VK_SHADER_STAGE_RAYGEN_BIT_KHR`

- Extending VkStructureType:

  - `VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_BUILD_GEOMETRY_INFO_KHR`

  - `VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_GEOMETRY_TYPE_INFO_KHR`

  - `VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_INFO_KHR`

  - `VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_DEVICE_ADDRESS_INFO_KHR`

  - `VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_AABBS_DATA_KHR`

  - `VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_INSTANCES_DATA_KHR`

  - `VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_KHR`

  - `VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_GEOMETRY_TRIANGLES_DATA_KHR`

  - `VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_INFO_KHR`

  - `VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_VERSION_KHR`

  - `VK_STRUCTURE_TYPE_BIND_ACCELERATION_STRUCTURE_MEMORY_INFO_KHR`

  - `VK_STRUCTURE_TYPE_COPY_ACCELERATION_STRUCTURE_INFO_KHR`

  - `VK_STRUCTURE_TYPE_COPY_ACCELERATION_STRUCTURE_TO_MEMORY_INFO_KHR`

  - `VK_STRUCTURE_TYPE_COPY_MEMORY_TO_ACCELERATION_STRUCTURE_INFO_KHR`

  - `VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_FEATURES_KHR`

  - `VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_PROPERTIES_KHR`

  - `VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_CREATE_INFO_KHR`

  - `VK_STRUCTURE_TYPE_RAY_TRACING_PIPELINE_INTERFACE_CREATE_INFO_KHR`

  - `VK_STRUCTURE_TYPE_RAY_TRACING_SHADER_GROUP_CREATE_INFO_KHR`

  - `VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_ACCELERATION_STRUCTURE_KHR`

### New or Modified Built-In Variables

- `LaunchIDKHR`

- `LaunchSizeKHR`

- `WorldRayOriginKHR`

- `WorldRayDirectionKHR`

- `ObjectRayOriginKHR`

- `ObjectRayDirectionKHR`

- `RayTminKHR`

- `RayTmaxKHR`

- `InstanceCustomIndexKHR`

- `InstanceId`

- `ObjectToWorldKHR`

- `WorldToObjectKHR`

- `HitKindKHR`

- `IncomingRayFlagsKHR`

- `RayGeometryIndexKHR`

- (modified)`PrimitiveId`

### New SPIR-V Capabilities

- RayTracingProvisionalKHR

- RayQueryProvisionalKHR

- RayTraversalPrimitiveCullingProvisionalKHR

### Issues

(1) How does this extension differ from VK_NV_ray_tracing?

DISCUSSION:

The following is a summary of the main functional differences between VK_KHR_ray_tracing and VK_NV_ray_tracing:

- added support for indirect ray tracing (vkCmdTraceRaysIndirectKHR)

- uses SPV_KHR_ray_tracing instead of SPV_NV_ray_tracing

  - refer to KHR SPIR-V enums instead of NV SPIR-V enums (which are functionally equivalent and aliased to the same values).

  - added `RayGeometryIndexKHR` built-in

- added acceleration structure serialization / deserialization (`VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR`, `VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR`, vkCmdCopyAccelerationStructureToMemoryKHR, vkCmdCopyMemoryToAccelerationStructureKHR)

- removed vkCompileDeferredNV compilation functionality and replaced with deferred host operations interactions for ray tracing

- document inactive primitives and instances

- added VkPhysicalDeviceRayTracingFeaturesKHR structure

- extended VkPhysicalDeviceRayTracingPropertiesKHR

  - `maxRecursionDepth` has a minimum of 1 instead of 31

  - require `shaderGroupHandleSize` to be 32 bytes

- added indirect and batched acceleration structure builds (vkCmdBuildAccelerationStructureIndirectKHR)

- added host acceleration structure commands

- reworked geometry structures so they could be better shared between device, host, and indirect builds

- added `geometryArrayOfPointers` and made instances more like triangles and AABBs.

- changed SBT parameters to a structure and added size (VkStridedBufferRegionKHR)

- explicitly made VkAccelerationStructureKHR use device addresses

- added ability to capture and replay shader group handles and acceleration structures

- added acceleration structure compatibility check function (vkGetDeviceAccelerationStructureCompatibilityKHR)

- add parameter for requesting memory requirements for host and/or device build

- added pipeline library support for ray tracing

- added watertightness guarantees

- added format feature for acceleration structure build vertex formats (`VK_FORMAT_FEATURE_ACCELERATION_STRUCTURE_VERTEX_BUFFER_BIT_KHR`)

- added no-null-shader pipeline flags (`VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_*_SHADERS_BIT_KHR`)

- added memory model interactions with ray tracing and define how subgroups work and can be repacked

- added ray query and SPV_KHR_ray_query support

(2) Can you give a more detailed comparision of differences and similarities between VK_NV_ray_tracing and VK_KHR_ray_tracing?

DISCUSSION:

The following is a more detailed comparision of which commands, structures, and enums are aliased, changed, or removed.

- Aliased functionality — enums, structures, and commands that are considered equivalent:

  - VkAccelerationStructureNV ↔ VkAccelerationStructureKHR

  - VkRayTracingShaderGroupTypeNV ↔ VkRayTracingShaderGroupTypeKHR

  - VkGeometryTypeNV ↔ VkGeometryTypeKHR

  - VkAccelerationStructureTypeNV ↔ VkAccelerationStructureTypeKHR

  - VkCopyAccelerationStructureModeNV ↔ VkCopyAccelerationStructureModeKHR

  - VkAccelerationStructureMemoryRequirementsTypeNV ↔ VkAccelerationStructureMemoryRequirementsTypeKHR

  - VkGeometryFlagsNV ↔ VkGeometryFlagsKHR

  - VkGeometryFlagBitsNV ↔ VkGeometryFlagBitsKHR

  - VkGeometryInstanceFlagsNV ↔ VkGeometryInstanceFlagsKHR

  - VkGeometryInstanceFlagBitsNV ↔ VkGeometryInstanceFlagBitsKHR

  - VkBuildAccelerationStructureFlagsNV ↔ VkBuildAccelerationStructureFlagsKHR

  - VkBuildAccelerationStructureFlagBitsNV ↔ VkBuildAccelerationStructureFlagBitsKHR

  - VkBindAccelerationStructureMemoryInfoNV ↔ VkBindAccelerationStructureMemoryInfoKHR

  - VkWriteDescriptorSetAccelerationStructureNV ↔ VkWriteDescriptorSetAccelerationStructureKHR

  - VkTransformMatrixNV ↔ VkTransformMatrixKHR (added to NV_ray_tracing for descriptive purposes)

  - VkAabbPositionsNV ↔ VkAabbPositionsKHR (added to NV_ray_tracing for descriptive purposes)

  - VkAccelerationStructureInstanceNV ↔ VkAccelerationStructureInstanceKHR (added to NV_ray_tracing for descriptive purposes)

  - vkDestroyAccelerationStructureNV ↔ vkDestroyAccelerationStructureKHR

  - vkBindAccelerationStructureMemoryNV ↔ vkBindAccelerationStructureMemoryKHR

  - vkGetRayTracingShaderGroupHandlesNV ↔ vkGetRayTracingShaderGroupHandlesKHR

  - vkCmdWriteAccelerationStructuresPropertiesNV ↔ vkCmdWriteAccelerationStructuresPropertiesKHR

- Changed enums, structures, and commands:

  - renamed `VK_GEOMETRY_INSTANCE_TRIANGLE_CULL_DISABLE_BIT_NV` → `VK_GEOMETRY_INSTANCE_TRIANGLE_FACING_CULL_DISABLE_BIT_KHR` in VkGeometryInstanceFlagBitsKHR

  - VkRayTracingShaderGroupCreateInfoNV → VkRayTracingShaderGroupCreateInfoKHR (added `pShaderGroupCaptureReplayHandle`)

  - VkRayTracingPipelineCreateInfoNV → VkRayTracingPipelineCreateInfoKHR (changed type of `pGroups`, added `libraries` and `pLibraryInterface`)

  - VkGeometryTrianglesNV → VkAccelerationStructureGeometryTrianglesDataKHR (device or host address instead of buffer+offset)

  - VkGeometryAABBNV → VkAccelerationStructureGeometryAabbsDataKHR (device or host address instead of buffer+offset)

  - VkGeometryDataNV → VkAccelerationStructureGeometryDataKHR (union of triangle/aabbs/instances)

  - VkGeometryNV → VkAccelerationStructureGeometryKHR (changed type of geometry)

  - VkAccelerationStructureInfoNV → VkAccelerationStructureCreateGeometryTypeInfoKHR (reshuffle geometry layout/info, instances moved to VkAccelerationStructureGeometryDataKHR)

  - VkAccelerationStructureCreateInfoNV → VkAccelerationStructureCreateInfoKHR (reshuffle geometry layout/info)

  - VkPhysicalDeviceRayTracingPropertiesNV → VkPhysicalDeviceRayTracingPropertiesKHR (renamed `maxTriangleCount` to `maxPrimitiveCount`, added `shaderGroupHandleCaptureReplaySize`)

  - VkAccelerationStructureMemoryRequirementsInfoNV → VkAccelerationStructureMemoryRequirementsInfoKHR (added `buildType`)

  - vkCreateAccelerationStructureNV → vkCreateAccelerationStructureKHR (device address, different geometry layout/info)

  - vkGetAccelerationStructureMemoryRequirementsNV → vkGetAccelerationStructureMemoryRequirementsKHR (different structs)

  - vkCmdBuildAccelerationStructureNV → vkCmdBuildAccelerationStructureKHR (params moved to structs, layout differences)

  - vkCmdCopyAccelerationStructureNV → vkCmdCopyAccelerationStructureKHR (params to struct, extendable)

  - vkCmdTraceRaysNV → vkCmdTraceRaysKHR (params to struct)

  - vkCreateRayTracingPipelinesNV → vkCreateRayTracingPipelinesKHR (different struct, changed functionality)

  - vkGetAccelerationStructureHandleNV → vkGetAccelerationStructureDeviceAddressKHR (device address instead of handle)

- Added enums, structures and commands:

  - `VK_GEOMETRY_TYPE_INSTANCES_KHR` to VkGeometryTypeKHR enum

  - `VK_COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR`, `VK_COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR` to VkCopyAccelerationStructureModeKHR enum

  - `VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR` `VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR`, `VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR`, `VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR`, `VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR`, `VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR` to VkPipelineCreateFlagBits

  - VkPhysicalDeviceRayTracingFeaturesKHR structure

  - VkAccelerationStructureBuildTypeKHR enum

  - VkDeviceOrHostAddressKHR and VkDeviceOrHostAddressConstKHR unions

  - VkPipelineLibraryCreateInfoKHR struct

  - VkRayTracingPipelineInterfaceCreateInfoKHR struct

  - VkAccelerationStructureBuildOffsetInfoKHR struct

  - VkAccelerationStructureGeometryInstancesDataKHR struct

  - VkAccelerationStructureDeviceAddressInfoKHR struct

  - VkAccelerationStructureVersionKHR struct

  - VkStridedBufferRegionKHR struct

  - VkTraceRaysIndirectCommandKHR struct

  - VkCopyAccelerationStructureToMemoryInfoKHR struct

  - VkCopyMemoryToAccelerationStructureInfoKHR struct

  - VkCopyAccelerationStructureInfoKHR struct

  - vkBuildAccelerationStructureKHR command (host build)

  - vkCopyAccelerationStructureKHR command (host copy)

  - vkCopyAccelerationStructureToMemoryKHR (host serialize)

  - vkCopyMemoryToAccelerationStructureKHR (host deserialize)

  - vkWriteAccelerationStructuresPropertiesKHR (host properties)

  - vkCmdCopyAccelerationStructureToMemoryKHR (device serialize)

  - vkCmdCopyMemoryToAccelerationStructureKHR (device deserialize)

  - vkGetRayTracingCaptureReplayShaderGroupHandlesKHR (shader group capture/replay)

  - vkGetDeviceAccelerationStructureCompatibilityKHR (serialization)

- Functionality removed:

  - `VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV`

  - vkCompileDeferredNV command

### Sample Code

Example ray generation GLSL shader

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

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

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

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

       col.y = payload;

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

### Version History

- Revision 1, 2019-12-05 (Members of the Vulkan Ray Tracing TSG)

  - Internal revisions (forked from NV_ray_tracing)

- Revision 2, 2019-12-20 (Daniel Koch, Eric Werness)

  - Add const version of DeviceOrHostAddress (!3515)

  - Add VU to clarify that only handles in the current pipeline are valid (!3518)

  - Restore some missing VUs and add in-place update language (#1902, !3522)

  - rename VkAccelerationStructureInstanceKHR member from accelerationStructure to accelerationStructureReference to better match its type (!3523)

  - Allow VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS for pipeline creation if shader group handles cannot be re-used. (!3523)

  - update documentation for the VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS error code and add missing documentation for new return codes from VK_KHR_deferred_host_operations (!3523)

  - list new query types for VK_KHR_ray_tracing (!3523)

  - Fix VU statements for VkAccelerationStructureGeometryKHR referring to correct union members and update to use more current wording (!3523)

- Revision 3, 2020-01-10 (Daniel Koch, Jon Leech, Christoph Kubisch)

  - Fix 'instance of' and 'that/which contains/defines' markup issues (!3528)

  - factor out VK_KHR_pipeline_library as stand-alone extension (!3540)

  - Resolve Vulkan-hpp issues (!3543)

  - add missing require for VkGeometryInstanceFlagsKHR

  - de-alias VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_INFO_NV since the KHR structure is no longer equivalent

  - add len to pDataSize attribute for vkWriteAccelerationStructuresPropertiesKHR

- Revision 4, 2020-01-23 (Daniel Koch, Eric Werness)

  - Improve vkWriteAccelerationStructuresPropertiesKHR, add return value and VUs (#1947)

  - Clarify language to allow multiple raygen shaders (#1959)

  - Various editorial feedback (!3556)

  - Add language to help deal with looped self-intersecting fans (#1901)

  - Change vkCmdTraceRays{Indirect}KHR args to pointers (!3559)

  - Add scratch address validation language (#1941, !3551)

  - Fix definition and add hierarchy information for shader call scope (#1977, !3571)

- Revision 5, 2020-02-04 (Eric Werness, Jeff Bolz, Daniel Koch)

  - remove vestigial accelerationStructureUUID (!3582)

  - update definition of repack instructions and improve memory model interactions (#1910, #1913, !3584)

  - Fix wrong sType for VkPhysicalDeviceRayTracingFeaturesKHR (#1988)

  - Use provisional SPIR-V capabilities (#1987)

  - require rayTracingPrimitiveCulling if rayQuery is supported (#1927)

  - Miss shaders do not have object parameters (!3592)

  - Fix missing required types in XML (!3592)

  - clarify matching conditions for update (!3592)

  - add goal that host and device builds be similar (!3592)

  - clarify that `maxPrimitiveCount` limit should apply to triangles and AABBs (!3592)

  - Require alignment for instance arrayOfPointers (!3592)

  - Zero is a valid value for instance flags (!3592)

  - Add some alignment VUs that got lost in refactoring (!3592)

  - Recommend TMin epsilon rather than culling (!3592)

  - Get angle from dot product not cross product (!3592)

  - Clarify that AH can access the payload and attributes (!3592)

  - Match DXR behavior for inactive primitive definition (!3592)

  - Use a more generic term than degenerate for inactive to avoid confusion (!3592)

- Revision 6, 2020-02-20 (Daniel Koch)

  - fix some dangling NV references (#1996)

  - rename VkCmdTraceRaysIndirectCommandKHR to VkTraceRaysIndirectCommandKHR (!3607)

  - update contributor list (!3611)

  - use uint64_t instead of VkAccelerationStructureReferenceKHR in VkAccelerationStructureInstanceKHR (#2004)

- Revision 7, 2020-02-28 (Tobias Hector)

  - remove HitTKHR SPIR-V builtin (spirv/spirv-extensions#7)

- Revision 8, 2020-03-06 (Tobias Hector, Dae Kim, Daniel Koch, Jeff Bolz, Eric Werness)

  - explicitly state that Tmax is updated when new closest intersection is accepted (#2020,!3536)

  - Made references to min and max t values consistent (!3644)

  - finish enumerating differences relative to NV_ray_tracing in issues (1) and (2) (#1974,!3642)

  - fix formatting in some math equations (!3642)

  - Restrict the Hit Kind operand of `OpReportIntersectionKHR` to 7-bits (spirv/spirv-extensions#8,!3646)

  - Say raytracing 'should' be watertight (#2008,!3631)

  - Clarify memory requirements for ray tracing buffers (#2005,!3649)

  - Add callable size limits (#1997,!3652)

## See Also

VK_SHADER_UNUSED_KHR, VkAabbPositionsKHR, VkAccelerationStructureBuildGeometryInfoKHR, VkAccelerationStructureBuildOffsetInfoKHR, VkAccelerationStructureBuildTypeKHR, VkAccelerationStructureCreateGeometryTypeInfoKHR, VkAccelerationStructureCreateInfoKHR, VkAccelerationStructureDeviceAddressInfoKHR, VkAccelerationStructureGeometryAabbsDataKHR, VkAccelerationStructureGeometryDataKHR, VkAccelerationStructureGeometryInstancesDataKHR, VkAccelerationStructureGeometryKHR, VkAccelerationStructureGeometryTrianglesDataKHR, VkAccelerationStructureInstanceKHR, VkAccelerationStructureKHR, VkAccelerationStructureMemoryRequirementsInfoKHR, VkAccelerationStructureMemoryRequirementsTypeKHR, VkAccelerationStructureTypeKHR, VkAccelerationStructureVersionKHR, VkBindAccelerationStructureMemoryInfoKHR, VkBuildAccelerationStructureFlagBitsKHR, VkBuildAccelerationStructureFlagsKHR, VkCopyAccelerationStructureInfoKHR, VkCopyAccelerationStructureModeKHR, VkCopyAccelerationStructureToMemoryInfoKHR, VkCopyMemoryToAccelerationStructureInfoKHR, VkDeviceOrHostAddressConstKHR, VkDeviceOrHostAddressKHR, VkGeometryFlagBitsKHR, VkGeometryFlagsKHR, VkGeometryInstanceFlagBitsKHR, VkGeometryInstanceFlagsKHR, VkGeometryTypeKHR, VkPhysicalDeviceRayTracingFeaturesKHR, VkPhysicalDeviceRayTracingPropertiesKHR, VkRayTracingPipelineCreateInfoKHR, VkRayTracingPipelineInterfaceCreateInfoKHR, VkRayTracingShaderGroupCreateInfoKHR, VkRayTracingShaderGroupTypeKHR, VkStridedBufferRegionKHR, VkTraceRaysIndirectCommandKHR, VkTransformMatrixKHR, VkWriteDescriptorSetAccelerationStructureKHR, vkBindAccelerationStructureMemoryKHR, vkBuildAccelerationStructureKHR, vkCmdBuildAccelerationStructureIndirectKHR, vkCmdBuildAccelerationStructureKHR, vkCmdCopyAccelerationStructureKHR, vkCmdCopyAccelerationStructureToMemoryKHR, vkCmdCopyMemoryToAccelerationStructureKHR, vkCmdTraceRaysIndirectKHR, vkCmdTraceRaysKHR, vkCmdWriteAccelerationStructuresPropertiesKHR, vkCopyAccelerationStructureKHR, vkCopyAccelerationStructureToMemoryKHR, vkCopyMemoryToAccelerationStructureKHR, vkCreateAccelerationStructureKHR, vkCreateRayTracingPipelinesKHR, vkDestroyAccelerationStructureKHR, vkGetAccelerationStructureDeviceAddressKHR, vkGetAccelerationStructureMemoryRequirementsKHR, vkGetDeviceAccelerationStructureCompatibilityKHR, vkGetRayTracingCaptureReplayShaderGroupHandlesKHR, vkGetRayTracingShaderGroupHandlesKHR, vkWriteAccelerationStructuresPropertiesKHR

## 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 (c) 2014-2020 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0