Vulkan-Docs/appendices/VK_NVX_raytracing.txt

include::meta/VK_NVX_raytracing.txt[]

*Last Modified Date*::
    2018-09-11

*Interactions and External Dependencies*::
  - This extension requires the
    https://htmlpreview.github.io/?https://github.com/KhronosGroup/SPIRV-Registry/blob/master/extensions/NV/SPV_NVX_raytracing.html[+SPV_NVX_raytracing+]
    SPIR-V extension.
  - This extension requires the
    https://github.com/KhronosGroup/GLSL/blob/master/extensions/nvx/GLSL_NVX_raytracing.txt[+GL_NVX_raytracing+]
    extension for GLSL source languages.

*Contributors*::
  - Eric Werness, NVIDIA
  - Ashwin Lele, NVIDIA
  - Robert Stepinski, NVIDIA
  - Nuno Subtil, NVIDIA
  - Christoph Kubisch, NVIDIA
  - Martin Stich, NVIDIA
  - Daniel Koch, NVIDIA

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

To enable raytracing, 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_NVX_raytracing+

=== New Object Types

  * slink:VkAccelerationStructureNVX

=== New Enum Constants

  * Extending elink:VkStructureType:
  ** ename:VK_STRUCTURE_TYPE_RAYTRACING_PIPELINE_CREATE_INFO_NVX
  ** ename:VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_CREATE_INFO_NVX
  ** ename:VK_STRUCTURE_TYPE_GEOMETRY_INSTANCE_NVX
  ** ename:VK_STRUCTURE_TYPE_GEOMETRY_NVX
  ** ename:VK_STRUCTURE_TYPE_GEOMETRY_TRIANGLES_NVX
  ** ename:VK_STRUCTURE_TYPE_GEOMETRY_AABB_NVX
  ** ename:VK_STRUCTURE_TYPE_BIND_ACCELERATION_STRUCTURE_MEMORY_INFO_NVX
  ** ename:VK_STRUCTURE_TYPE_DESCRIPTOR_ACCELERATION_STRUCTURE_INFO_NVX
  ** ename:VK_STRUCTURE_TYPE_ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_INFO_NVX
  ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_RAYTRACING_PROPERTIES_NVX
  * Extending elink:VkShaderStageFlagBits:
  ** ename:VK_SHADER_STAGE_RAYGEN_BIT_NVX
  ** ename:VK_SHADER_STAGE_ANY_HIT_BIT_NVX
  ** ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_NVX
  ** ename:VK_SHADER_STAGE_MISS_BIT_NVX
  ** ename:VK_SHADER_STAGE_INTERSECTION_BIT_NVX
  ** ename:VK_SHADER_STAGE_CALLABLE_BIT_NVX
  * Extending elink:VkPipelineStageFlagBits:
  ** ename:VK_PIPELINE_STAGE_RAYTRACING_BIT_NVX
  * Extending elink:VkBufferUsageFlagBits:
  ** ename:VK_BUFFER_USAGE_RAYTRACING_BIT_NVX
  * Extending elink:VkPipelineBindPoint:
  ** ename:VK_PIPELINE_BIND_POINT_RAYTRACING_NVX
  * Extending elink:VkDescriptorType
  ** ename:VK_DESCRIPTOR_TYPE_ACCELERATION_STRUCTURE_NVX
  * Extending elink:VkAccessFlagBits
  ** ename:VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_NVX
  ** ename:VK_ACCESS_ACCELERATION_STRUCTURE_WRITE_BIT_NVX
  * Extending elink:VkQueryType
  ** ename:VK_QUERY_TYPE_COMPACTED_SIZE_NVX
  * Extending elink:VkPipelineCreateFlagBits
  ** ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NVX


=== New Enums

 ** elink:VkGeometryFlagBitsNVX
 ** elink:VkGeometryInstanceFlagBitsNVX (TBD)
 ** elink:VkBuildAccelerationStructureFlagBitsNVX
 ** elink:VkCopyAccelerationStructureModeNVX
 ** elink:VkGeometryTypeNVX

=== New Structures

 ** slink:VkRaytracingPipelineCreateInfoNVX
 ** slink:VkGeometryTrianglesNVX
 ** slink:VkGeometryAABBNVX
 ** slink:VkGeometryDataNVX
 ** slink:VkGeometryNVX
 ** slink:VkAccelerationStructureCreateInfoNVX
 ** slink:VkBindAccelerationStructureMemoryInfoNVX
 ** slink:VkDescriptorAccelerationStructureInfoNVX
 ** slink:VkAccelerationStructureMemoryRequirementsInfoNVX
 ** slink:VkPhysicalDeviceRaytracingPropertiesNVX

=== New Functions

  * flink:vkCreateAccelerationStructureNVX
  * flink:vkDestroyAccelerationStructureNVX
  * flink:vkGetAccelerationStructureMemoryRequirementsNVX
  * flink:vkGetAccelerationStructureScratchMemoryRequirementsNVX
  * flink:vkBindAccelerationStructureMemoryNVX
  * flink:vkCmdBuildAccelerationStructureNVX
  * flink:vkCmdCopyAccelerationStructureNVX
  * flink:vkCmdTraceRaysNVX
  * flink:vkCreateRaytracingPipelinesNVX
  * flink:vkGetRaytracingShaderHandlesNVX
  * flink:vkGetAccelerationStructureHandleNVX
  * flink:vkCmdWriteAccelerationStructurePropertiesNVX
  * flink:vkCompileDeferredNVX

=== New or Modified Built-In Variables

  * <<interfaces-builtin-variables-launchid,code:LaunchIDNVX>>
  * <<interfaces-builtin-variables-launchsize,code:LaunchSizeNVX>>
  * <<interfaces-builtin-variables-worldrayorigin,code:WorldRayOriginNVX>>
  * <<interfaces-builtin-variables-worldraydirection,code:WorldRayDirectionNVX>>
  * <<interfaces-builtin-variables-objectrayorigin,code:ObjectRayOriginNVX>>
  * <<interfaces-builtin-variables-objectraydirection,code:ObjectRayDirectionNVX>>
  * <<interfaces-builtin-variables-raytmin,code:RayTminNVX>>
  * <<interfaces-builtin-variables-raytmax,code:RayTmaxNVX>>
  * <<interfaces-builtin-variables-instancecustomindex,code:InstanceCustomIndexNVX>>
  * <<interfaces-builtin-variables-objecttoworld,code:ObjectToWorldNVX>>
  * <<interfaces-builtin-variables-worldtoobject,code:WorldToObjectNVX>>
  * <<interfaces-builtin-variables-hitt,code:HitTNVX>>
  * <<interfaces-builtin-variables-hitkind,code:HitKindNVX>>
  * (modified)code:InstanceIndex
  * (modified)code:PrimitiveId

=== New SPIR-V Capabilities

  * <<spirvenv-capabilities-table-raytracing,RaytracingNVX>>

=== Issues

1) Are there issues?

*RESOLVED*: Yes.

=== Sample Code

Example ray generation GLSL shader

[source,c]
---------------------------------------------------
#version 450 core
#extension GL_NVX_raytracing : require
layout(set = 0, binding = 0, rgba8) uniform image2D image;
layout(set = 0, binding = 1) uniform accelerationStructureNVX as;
layout(location = 0) rayPayloadNVX float payload;

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

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

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

   col.y = payload;

   imageStore(image, ivec2(gl_LaunchIDNVX.xy), col);
}
---------------------------------------------------

=== Version History

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