HORIZON HASKELLDocslts/ghc-9.14.x45dd5372026-10-11Search names, modules, packages, or :: a typeCtrl K

GHC 9.14.1 · lts/ghc-9.14.x · 45dd537 · 2026-10-11

Modulevulkan-3.27GHC2021

Vulkan.Extensions.VK_KHR_ray_tracing_pipeline

Name

VK_KHR_ray_tracing_pipeline - device extension

VK_KHR_ray_tracing_pipeline

Name String

VK_KHR_ray_tracing_pipeline

Extension Type

Device extension

Registered Extension Number

348

Revision

1

Ratification Status

Ratified

Extension and Version Dependencies

VK_KHR_spirv_1_4      or

Vulkan Version 1.2 and VK_KHR_acceleration_structure

API Interactions

  • Interacts with VK_KHR_ray_query

SPIR-V Dependencies
Contact

Other Extension Metadata

Last Modified Date

2020-11-12

Interactions and External Dependencies
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

  • Andrew Garrard, Imagination

  • 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

  • Spencer Fricke, 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:

  • A new ray tracing pipeline type with new shader domains: ray generation, intersection, any-hit, closest hit, miss, and callable

  • A shader binding indirection table to link shader groups with acceleration structure items

  • Ray tracing commands which initiate the ray pipeline traversal and invocation of the various new shader domains depending on which traversal conditions are met

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

  • SPV_KHR_ray_tracing

New Commands

New Structures

New Enums

New Enum Constants

New or Modified Built-In Variables

New SPIR-V Capabilities

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_pipeline and VK_NV_ray_tracing:

  • added support for indirect ray tracing (cmdTraceRaysIndirectKHR)

  • 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

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

  • added PhysicalDeviceRayTracingPipelineFeaturesKHR structure

  • extended PhysicalDeviceRayTracingPipelinePropertiesKHR structure

    • renamed maxRecursionDepth to maxRayRecursionDepth and it has a minimum of 1 instead of 31

    • require shaderGroupHandleSize to be 32 bytes

    • added maxRayDispatchInvocationCount, shaderGroupHandleAlignment and maxRayHitAttributeSize

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

  • changed SBT parameters to a structure and added size (StridedDeviceAddressRegionKHR)

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

  • added pipeline library support for ray tracing

  • added watertightness guarantees

  • 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

  1. Can you give a more detailed comparison of differences and similarities between VK_NV_ray_tracing and VK_KHR_ray_tracing_pipeline?

DISCUSSION:

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

  1. What are the changes between the public provisional (VK_KHR_ray_tracing v8) release and the internal provisional (VK_KHR_ray_tracing v9) release?

  1. What are the changes between the internal provisional (VK_KHR_ray_tracing v9) release and the final (VK_KHR_acceleration_structure v11 / VK_KHR_ray_tracing_pipeline v1) release?

  • refactor VK_KHR_ray_tracing into 3 extensions, enabling implementation flexibility and decoupling ray query support from ray pipelines:

    • VK_KHR_acceleration_structure (for acceleration structure operations)

    • VK_KHR_ray_tracing_pipeline (for ray tracing pipeline and shader stages)

    • VK_KHR_ray_query (for ray queries in existing shader stages)

  • Require Volatile for the following builtins in the ray generation, closest hit, miss, intersection, and callable shader stages:

    • SubgroupSize, SubgroupLocalInvocationId, SubgroupEqMask, SubgroupGeMask, SubgroupGtMask, SubgroupLeMask, SubgroupLtMask

    • SMIDNV, WarpIDNV

  • clarify buffer usage flags for ray tracing

  • rename maxRecursionDepth to maxRayPipelineRecursionDepth (pipeline creation) and maxRayRecursionDepth (limit) to reduce confusion

  • Add queryable maxRayHitAttributeSize limit and rename members of RayTracingPipelineInterfaceCreateInfoKHR to maxPipelineRayPayloadSize and maxPipelineRayHitAttributeSize for clarity

  • Update SPIRV capabilities to use RayTracingKHR

  • extension is no longer provisional

  • define synchronization requirements for indirect trace rays and indirect buffer

  1. This extension adds gl_InstanceID for the intersection, any-hit, and closest hit shaders, but in KHR_vulkan_glsl, gl_InstanceID is replaced with gl_InstanceIndex. Which should be used for Vulkan in this extension?

RESOLVED: This extension uses gl_InstanceID and maps it to InstanceId in SPIR-V. It is acknowledged that this is different than other shader stages in Vulkan. There are two main reasons for the difference here:

  • symmetry with gl_PrimitiveID which is also available in these shaders

  • there is no “baseInstance” relevant for these shaders, and so ID makes it more obvious that this is zero-based.

  1. Why is VK_KHR_pipeline_library an interaction instead of a required dependency, particularly when the “Device Extensions” section says it is required to be supported anyhow?

RESOLVED: If the VK_KHR_pipeline_library extension were a required dependency, then every application would need to enable the extension whether or not they actually want to use the pipeline library functionality. Developers found this to be annoying and unfriendly behavior. We do wish to require all implementations to support it though, and thus it is listed as a requirement in device extensions section.

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, 2020-11-12 (Mathieu Robart, Daniel Koch, Eric Werness, Tobias Hector)

    • Decomposition of the specification, from VK_KHR_ray_tracing to VK_KHR_ray_tracing_pipeline (#1918,!3912)

    • require certain subgroup and sm_shader_builtin shader builtins to be decorated as volatile in the ray generation, closest hit, miss, intersection, and callable stages (#1924,!3903,!3954)

    • clarify buffer usage flags for ray tracing (#2181,!3939)

    • rename maxRecursionDepth to maxRayPipelineRecursionDepth and maxRayRecursionDepth (#2203,!3937)

    • add queryable maxRayHitAttributeSize and rename members of VkRayTracingPipelineInterfaceCreateInfoKHR (#2102,!3966)

    • update to use RayTracingKHR SPIR-V capability

    • add VUs for matching hit group type against geometry type (#2245,!3994)

    • require RayTMaxKHR be volatile in intersection shaders (#2268,!4030)

    • add numerical limits for ray parameters (#2235,!3960)

    • fix SBT indexing rules for device addresses (#2308,!4079)

    • relax formula for ray intersection candidate determination (#2322,!4080)

    • add more details on ShaderRecordBufferKHR variables (#2230,!4083)

    • clarify valid bits for InstanceCustomIndexKHR (GLSL/GLSL#19,!4128)

    • allow at most one IncomingRayPayloadKHR, IncomingCallableDataKHR, and HitAttributeKHR (!4129)

    • add minimum for maxShaderGroupStride (#2353,!4131)

    • require VK_KHR_pipeline_library extension to be supported (#2348,!4135)

    • clarify meaning of 'geometry index' (#2272,!4137)

    • restrict traces to TLAS (#2239,!4141)

    • add note about maxPipelineRayPayloadSize (#2383,!4172)

    • do not require raygen shader in pipeline libraries (!4185)

    • define sync for indirect trace rays and indirect buffer (#2407,!4208)

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.

  • 14 types
  • 8 values
  • Packagevulkan-3.27
  • Exports33
  • LanguageGHC2021
  • LicenceBSD-3-Clause
  • SourceVK_KHR_ray_tracing_pipeline.hs
valuecmdTraceRaysKHR
  1. :: MonadIO io
  2. => CommandBuffer

    commandBuffer is the command buffer into which the command will be recorded.

  3. -> "raygenShaderBindingTable" ::: StridedDeviceAddressRegionKHR

    pRaygenShaderBindingTable is a StridedDeviceAddressRegionKHR that holds the shader binding table data for the ray generation shader stage.

  4. -> "missShaderBindingTable" ::: StridedDeviceAddressRegionKHR

    pMissShaderBindingTable is a StridedDeviceAddressRegionKHR that holds the shader binding table data for the miss shader stage.

  5. -> "hitShaderBindingTable" ::: StridedDeviceAddressRegionKHR

    pHitShaderBindingTable is a StridedDeviceAddressRegionKHR that holds the shader binding table data for the hit shader stage.

  6. -> "callableShaderBindingTable" ::: StridedDeviceAddressRegionKHR

    pCallableShaderBindingTable is a StridedDeviceAddressRegionKHR that holds the shader binding table data for the callable shader stage.

  7. -> "width" ::: Word32

    width is the width of the ray trace query dimensions.

  8. -> "height" ::: Word32

    height is height of the ray trace query dimensions.

  9. -> "depth" ::: Word32

    depth is depth of the ray trace query dimensions.

  10. -> io ()
#

vkCmdTraceRaysKHR - Initialize a ray tracing dispatch

Description

When the command is executed, a ray generation group of width × height × depth rays is assembled.

Valid Usage

Valid Usage (Implicit)

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

Command Buffer Levels

Render Pass Scope

Video Coding Scope

Supported Queue Types

Command Type

Primary Secondary

Outside

Outside

VK_QUEUE_COMPUTE_BIT

Action

Conditional Rendering

vkCmdTraceRaysKHR is not affected by conditional rendering

See Also

VK_KHR_ray_tracing_pipeline, CommandBuffer, StridedDeviceAddressRegionKHR

valuegetRayTracingShaderGroupHandlesKHR
  1. :: MonadIO io
  2. => Device

    device is the logical device containing the ray tracing pipeline.

  3. -> Pipeline

    pipeline is the ray tracing pipeline object containing the shaders.

  4. -> "firstGroup" ::: Word32

    firstGroup is the index of the first group to retrieve a handle for from the RayTracingPipelineCreateInfoKHR::pGroups or RayTracingPipelineCreateInfoNV::pGroups array.

  5. -> "groupCount" ::: Word32

    groupCount is the number of shader handles to retrieve.

  6. -> "dataSize" ::: Word64

    dataSize is the size in bytes of the buffer pointed to by pData.

  7. -> "data" ::: Ptr ()

    pData is a pointer to an application-allocated buffer where the results will be written.

  8. -> io ()
#

vkGetRayTracingShaderGroupHandlesKHR - Query ray tracing pipeline shader group handles

Description

On success, an array of groupCount shader handles will be written to pData, with each element being of size PhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleSize. The first handle written corresponds to the group identified by firstGroup, with subsequent handles corresponding to consecutive shader groups in the order they appear in the RayTracingPipelineCreateInfoKHR::pGroups or RayTracingPipelineCreateInfoNV::pGroups array.

If pipeline was created with PIPELINE_CREATE_LIBRARY_BIT_KHR and the pipelineLibraryGroupHandles feature is enabled applications can query group handles from that pipeline, even if the pipeline is a library and is never bound to a command buffer. These group handles remain bitwise identical for any pipeline which references the pipeline library. Group indices are assigned as-if the pipeline was created without PIPELINE_CREATE_LIBRARY_BIT_KHR.

Valid Usage

  • pipeline must be a ray tracing pipeline

Valid Usage (Implicit)

  • device must be a valid Device handle

  • pipeline must be a valid Pipeline handle

  • pData must be a valid pointer to an array of dataSize bytes

  • dataSize must be greater than 0

  • pipeline must have been created, allocated, or retrieved from device

Return Codes

Success
Failure

See Also

VK_KHR_ray_tracing_pipeline, VK_NV_ray_tracing, Device, Pipeline

valuegetRayTracingCaptureReplayShaderGroupHandlesKHR
  1. :: MonadIO io
  2. => Device

    device is the logical device containing the ray tracing pipeline.

  3. -> Pipeline

    pipeline is the ray tracing pipeline object containing the shaders.

  4. -> "firstGroup" ::: Word32

    firstGroup is the index of the first group to retrieve a handle for from the RayTracingPipelineCreateInfoKHR::pGroups array.

  5. -> "groupCount" ::: Word32

    groupCount is the number of shader handles to retrieve.

  6. -> "dataSize" ::: Word64

    dataSize is the size in bytes of the buffer pointed to by pData.

  7. -> "data" ::: Ptr ()

    pData is a pointer to an application-allocated buffer where the results will be written.

  8. -> io ()
#

vkGetRayTracingCaptureReplayShaderGroupHandlesKHR - Query opaque capture replay data for pipeline shader group handles

Description

On success, an array of groupCount shader handles will be written to pData, with each element being of size PhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleCaptureReplaySize. The first handle written corresponds to the group identified by firstGroup, with subsequent handles corresponding to consecutive shader groups in the order they appear in the RayTracingPipelineCreateInfoKHR::pGroups array.

Once queried, this opaque data can be provided at pipeline creation time (in a subsequent execution), using RayTracingShaderGroupCreateInfoKHR::pShaderGroupCaptureReplayHandle, as described in Ray Tracing Capture Replay.

If pipeline was created with PIPELINE_CREATE_LIBRARY_BIT_KHR and the pipelineLibraryGroupHandles feature is enabled applications can query capture replay group handles from that pipeline. The capture replay handle remains bitwise identical for any pipeline which references the pipeline library. Group indices are assigned as-if the pipeline was created without PIPELINE_CREATE_LIBRARY_BIT_KHR.

Valid Usage

  • pipeline must be a ray tracing pipeline

Valid Usage (Implicit)

  • device must be a valid Device handle

  • pipeline must be a valid Pipeline handle

  • pData must be a valid pointer to an array of dataSize bytes

  • dataSize must be greater than 0

  • pipeline must have been created, allocated, or retrieved from device

Return Codes

Success
Failure

See Also

VK_KHR_ray_tracing_pipeline, Device, Pipeline

valuecreateRayTracingPipelinesKHR
  1. :: MonadIO io
  2. => Device

    device is the logical device that creates the ray tracing pipelines.

  3. -> DeferredOperationKHR

    deferredOperation is NULL_HANDLE or the handle of a valid DeferredOperationKHR request deferral object for this command.

  4. -> PipelineCache

    pipelineCache is either NULL_HANDLE, indicating that pipeline caching is disabled, or to enable caching, the handle of a valid PipelineCache object. The implementation must not access this object outside of the duration of this command.

  5. -> "createInfos" ::: Vector (SomeStruct RayTracingPipelineCreateInfoKHR)

    pCreateInfos is a pointer to an array of RayTracingPipelineCreateInfoKHR structures.

  6. -> "allocator" ::: Maybe AllocationCallbacks

    pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  7. -> io (Result, "pipelines" ::: Vector Pipeline)
#

vkCreateRayTracingPipelinesKHR - Creates a new ray tracing pipeline object

Description

The ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS error is returned if the implementation is unable to reuse the shader group handles provided in RayTracingShaderGroupCreateInfoKHR::pShaderGroupCaptureReplayHandle when PhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplay is enabled.

Pipelines are created and returned as described for Multiple Pipeline Creation.

Valid Usage

Valid Usage (Implicit)

  • device must be a valid Device handle

  • If deferredOperation is not NULL_HANDLE, deferredOperation must be a valid DeferredOperationKHR handle

  • If pipelineCache is not NULL_HANDLE, pipelineCache must be a valid PipelineCache handle

  • pCreateInfos must be a valid pointer to an array of createInfoCount valid RayTracingPipelineCreateInfoKHR structures

  • If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure

  • pPipelines must be a valid pointer to an array of createInfoCount Pipeline handles

  • createInfoCount must be greater than 0

  • If deferredOperation is a valid handle, it must have been created, allocated, or retrieved from device

  • If pipelineCache is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes

Success
Failure

See Also

VK_KHR_ray_tracing_pipeline, AllocationCallbacks, DeferredOperationKHR, Device, Pipeline, PipelineCache, RayTracingPipelineCreateInfoKHR

valuewithRayTracingPipelinesKHR
  1. :: MonadIO io
  2. => Device
  3. -> DeferredOperationKHR
  4. -> PipelineCache
  5. -> Vector (SomeStruct RayTracingPipelineCreateInfoKHR)
  6. -> Maybe AllocationCallbacks
  7. -> io (Result, Vector Pipeline) -> ((Result, Vector Pipeline) -> io ()) -> r
  8. -> r
#

A convenience wrapper to make a compatible pair of calls to createRayTracingPipelinesKHR and destroyPipeline

To ensure that destroyPipeline is always called: pass bracket (or the allocate function from your favourite resource management library) as the last argument. To just extract the pair pass (,) as the last argument.

valuecmdTraceRaysIndirectKHR
  1. :: MonadIO io
  2. => CommandBuffer

    commandBuffer is the command buffer into which the command will be recorded.

  3. -> "raygenShaderBindingTable" ::: StridedDeviceAddressRegionKHR

    pRaygenShaderBindingTable is a StridedDeviceAddressRegionKHR that holds the shader binding table data for the ray generation shader stage.

  4. -> "missShaderBindingTable" ::: StridedDeviceAddressRegionKHR

    pMissShaderBindingTable is a StridedDeviceAddressRegionKHR that holds the shader binding table data for the miss shader stage.

  5. -> "hitShaderBindingTable" ::: StridedDeviceAddressRegionKHR

    pHitShaderBindingTable is a StridedDeviceAddressRegionKHR that holds the shader binding table data for the hit shader stage.

  6. -> "callableShaderBindingTable" ::: StridedDeviceAddressRegionKHR

    pCallableShaderBindingTable is a StridedDeviceAddressRegionKHR that holds the shader binding table data for the callable shader stage.

  7. -> "indirectDeviceAddress" ::: DeviceAddress

    indirectDeviceAddress is a buffer device address which is a pointer to a TraceRaysIndirectCommandKHR structure containing the trace ray parameters.

  8. -> io ()
#

vkCmdTraceRaysIndirectKHR - Initialize an indirect ray tracing dispatch

Description

cmdTraceRaysIndirectKHR behaves similarly to cmdTraceRaysKHR except that the ray trace query dimensions are read by the device from indirectDeviceAddress during execution.

Valid Usage

Valid Usage (Implicit)

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

Command Buffer Levels

Render Pass Scope

Video Coding Scope

Supported Queue Types

Command Type

Primary Secondary

Outside

Outside

VK_QUEUE_COMPUTE_BIT

Action

Conditional Rendering

vkCmdTraceRaysIndirectKHR is not affected by conditional rendering

See Also

VK_KHR_ray_tracing_pipeline, CommandBuffer, DeviceAddress, StridedDeviceAddressRegionKHR

valuegetRayTracingShaderGroupStackSizeKHR
  1. :: MonadIO io
  2. => Device

    device is the logical device containing the ray tracing pipeline.

  3. -> Pipeline

    pipeline is the ray tracing pipeline object containing the shaders groups.

  4. -> "group" ::: Word32

    group is the index of the shader group to query.

  5. -> ShaderGroupShaderKHR

    groupShader is the type of shader from the group to query.

  6. -> io DeviceSize
#

vkGetRayTracingShaderGroupStackSizeKHR - Query ray tracing pipeline shader group shader stack size

Description

The return value is the ray tracing pipeline stack size in bytes for the specified shader as called from the specified shader group.

Valid Usage

  • pipeline must be a ray tracing pipeline

  • The value of group must be less than the number of shader groups in pipeline

  • The shader identified by groupShader in group must not be SHADER_UNUSED_KHR

Valid Usage (Implicit)

  • device must be a valid Device handle

  • pipeline must be a valid Pipeline handle

  • groupShader must be a valid ShaderGroupShaderKHR value

  • pipeline must have been created, allocated, or retrieved from device

See Also

VK_KHR_ray_tracing_pipeline, Device, Pipeline, ShaderGroupShaderKHR

valuecmdSetRayTracingPipelineStackSizeKHR
  1. :: MonadIO io
  2. => CommandBuffer

    commandBuffer is the command buffer into which the command will be recorded.

  3. -> "pipelineStackSize" ::: Word32

    pipelineStackSize is the stack size to use for subsequent ray tracing trace commands.

  4. -> io ()
#

vkCmdSetRayTracingPipelineStackSizeKHR - Set the stack size dynamically for a ray tracing pipeline

Description

This command sets the stack size for subsequent ray tracing commands when the ray tracing pipeline is created with DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR set in PipelineDynamicStateCreateInfo::pDynamicStates. Otherwise, the stack size is computed as described in Ray Tracing Pipeline Stack.

Valid Usage

  • pipelineStackSize must be large enough for any dynamic execution through the shaders in the ray tracing pipeline used by a subsequent trace call

Valid Usage (Implicit)

  • commandBuffer must be in the recording state

  • The CommandPool that commandBuffer was allocated from must support QUEUE_COMPUTE_BIT operations

  • This command must only be called outside of a render pass instance

  • This command must only be called outside of a video coding scope

Host Synchronization

  • Host access to commandBuffer must be externally synchronized

  • Host access to the CommandPool that commandBuffer was allocated from must be externally synchronized

Command Properties

'

Command Buffer Levels

Render Pass Scope

Video Coding Scope

Supported Queue Types

Command Type

Primary Secondary

Outside

Outside

VK_QUEUE_COMPUTE_BIT

State

Conditional Rendering

vkCmdSetRayTracingPipelineStackSizeKHR is not affected by conditional rendering

See Also

VK_KHR_ray_tracing_pipeline, CommandBuffer

datadata RayTracingShaderGroupCreateInfoKHR
#

VkRayTracingShaderGroupCreateInfoKHR - Structure specifying shaders in a shader group

Description

If the pipeline is created with PIPELINE_CREATE_LIBRARY_BIT_KHR and the pipelineLibraryGroupHandles feature is enabled, pShaderGroupCaptureReplayHandle is inherited by all pipelines which link against this pipeline and remains bitwise identical for any pipeline which references this pipeline library.

Valid Usage

Valid Usage (Implicit)

See Also

VK_KHR_ray_tracing_pipeline, RayTracingPipelineCreateInfoKHR, RayTracingShaderGroupTypeKHR, StructureType

Constructors

Instances5Show, Storable, FromCStruct, ToCStruct, Zero
datadata RayTracingPipelineCreateInfoKHR (es :: [Type])
#

VkRayTracingPipelineCreateInfoKHR - Structure specifying parameters of a newly created ray tracing pipeline

Description

The parameters basePipelineHandle and basePipelineIndex are described in more detail in Pipeline Derivatives.

When PIPELINE_CREATE_LIBRARY_BIT_KHR is specified, this pipeline defines a pipeline library which cannot be bound as a ray tracing pipeline directly. Instead, pipeline libraries define common shaders and shader groups which can be included in future pipeline creation.

If pipeline libraries are included in pLibraryInfo, shaders defined in those libraries are treated as if they were defined as additional entries in pStages, appended in the order they appear in the pLibraries array and in the pStages array when those libraries were defined.

When referencing shader groups in order to obtain a shader group handle, groups defined in those libraries are treated as if they were defined as additional entries in pGroups, appended in the order they appear in the pLibraries array and in the pGroups array when those libraries were defined. The shaders these groups reference are set when the pipeline library is created, referencing those specified in the pipeline library, not in the pipeline that includes it.

The default stack size for a pipeline if DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR is not provided is computed as described in Ray Tracing Pipeline Stack.

If the pNext chain includes a PipelineCreateFlags2CreateInfo structure, PipelineCreateFlags2CreateInfo::flags from that structure is used instead of flags from this structure.

If the pNext chain includes a VkRayTracingPipelineClusterAccelerationStructureCreateInfoNV structure, then that structure controls whether cluster acceleration structures are allowed in this ray tracing pipeline.

Valid Usage

Valid Usage (Implicit)

See Also

VK_KHR_ray_tracing_pipeline, Pipeline, PipelineCreateFlags, PipelineDynamicStateCreateInfo, PipelineLayout, PipelineLibraryCreateInfoKHR, PipelineShaderStageCreateInfo, RayTracingPipelineInterfaceCreateInfoKHR, RayTracingShaderGroupCreateInfoKHR, StructureType, createRayTracingPipelinesKHR

Constructors

Instances5Extensible, Show, FromCStruct, ToCStruct, Zero
datadata PhysicalDeviceRayTracingPipelineFeaturesKHR
#

VkPhysicalDeviceRayTracingPipelineFeaturesKHR - Structure describing the ray tracing features that can be supported by an implementation

Members

This structure describes the following features:

Description

If the PhysicalDeviceRayTracingPipelineFeaturesKHR structure is included in the pNext chain of the PhysicalDeviceFeatures2 structure passed to getPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. If the application wishes to use a Device with any features described by PhysicalDeviceRayTracingPipelineFeaturesKHR, it must add an instance of the structure, with the desired feature members set to TRUE, to the pNext chain of DeviceCreateInfo when creating the Device.

Valid Usage

  • If rayTracingPipelineShaderGroupHandleCaptureReplayMixed is TRUE, rayTracingPipelineShaderGroupHandleCaptureReplay must also be TRUE

Valid Usage (Implicit)

Structure Chaining

Extends the structures

See Also

VK_KHR_ray_tracing_pipeline, Bool32, StructureType

Constructors

Instances6Eq, Show, Storable, FromCStruct, ToCStruct, Zero
datadata PhysicalDeviceRayTracingPipelinePropertiesKHR
#

VkPhysicalDeviceRayTracingPipelinePropertiesKHR - Properties of the physical device for ray tracing

Description

If the PhysicalDeviceRayTracingPipelinePropertiesKHR structure is included in the pNext chain of the PhysicalDeviceProperties2 structure passed to getPhysicalDeviceProperties2, it is filled in with each corresponding implementation-dependent property.

Limits specified by this structure must match those specified with the same name in PhysicalDeviceRayTracingPropertiesNV.

Structure Chaining

Extends the structure

See Also

VK_KHR_ray_tracing_pipeline, StructureType

Constructors

Instances6Eq, Show, Storable, FromCStruct, ToCStruct, Zero
datadata StridedDeviceAddressRegionKHR
#

VkStridedDeviceAddressRegionKHR - Structure specifying a region of device addresses with a stride

Valid Usage

  • If size is not zero, all addresses between deviceAddress and deviceAddress + size - 1 must be in the buffer device address range of the same buffer

  • If size is not zero, stride must be less than or equal to the size of the buffer from which deviceAddress was queried

Valid Usage (Implicit)

  • If deviceAddress is not 0, deviceAddress must be a valid DeviceAddress value

See Also

VK_KHR_ray_tracing_pipeline, VkClusterAccelerationStructureCommandsInfoNV, DeviceAddress, DeviceSize, cmdTraceRaysIndirectKHR, cmdTraceRaysKHR

Constructors

Instances6Eq, Show, Storable, FromCStruct, ToCStruct, Zero
datadata TraceRaysIndirectCommandKHR
#

VkTraceRaysIndirectCommandKHR - Structure specifying the parameters of an indirect ray tracing command

Description

The members of TraceRaysIndirectCommandKHR have the same meaning as the similarly named parameters of cmdTraceRaysKHR.

Valid Usage

See Also

VK_KHR_ray_tracing_pipeline

Constructors

Instances6Eq, Show, Storable, FromCStruct, ToCStruct, Zero
datadata RayTracingPipelineInterfaceCreateInfoKHR
#

VkRayTracingPipelineInterfaceCreateInfoKHR - Structure specifying additional interface information when using libraries

Description

maxPipelineRayPayloadSize is calculated as the maximum size of the block (in bytes) declared in the RayPayloadKHR or IncomingRayPayloadKHR storage classes. maxPipelineRayHitAttributeSize is calculated as the maximum size of any block (in bytes) declared in the HitAttributeKHR or HitObjectAttributeEXT storage class. As variables in these storage classes do not have explicit offsets, the size should be calculated as if each variable has a scalar alignment equal to the largest scalar alignment of any of the block’s members.

There is no explicit upper limit for maxPipelineRayPayloadSize, but in practice it should be kept as small as possible. Similar to invocation local memory, it must be allocated for each shader invocation and for devices which support many simultaneous invocations, this storage can rapidly be exhausted, resulting in failure.

Valid Usage (Implicit)

See Also

VK_KHR_ray_tracing_pipeline, RayTracingPipelineCreateInfoKHR, StructureType

Constructors

Instances6Eq, Show, Storable, FromCStruct, ToCStruct, Zero
newtypenewtype RayTracingShaderGroupTypeKHR
#

VkRayTracingShaderGroupTypeKHR - Shader group types

Description

For current group types, the hit group type could be inferred from the presence or absence of the intersection shader, but we provide the type explicitly for future hit groups that do not have that property.

See Also

VK_KHR_ray_tracing_pipeline, VK_NV_ray_tracing, RayTracingShaderGroupCreateInfoKHR, RayTracingShaderGroupCreateInfoNV

Constructors

Instances6Eq, Ord, Read, Show, Storable, Zero
newtypenewtype ShaderGroupShaderKHR
#

VkShaderGroupShaderKHR - Shader group shaders

Description

See Also

VK_KHR_ray_tracing_pipeline, getRayTracingShaderGroupStackSizeKHR

Constructors

Instances6Eq, Ord, Read, Show, Storable, Zero
newtypenewtype DeferredOperationKHR
#

VkDeferredOperationKHR - A deferred operation

Description

This handle refers to a tracking structure which manages the execution state for a deferred command.

See Also

VK_DEFINE_NON_DISPATCHABLE_HANDLE, VK_KHR_deferred_host_operations, buildAccelerationStructuresKHR, buildMicromapsEXT, copyAccelerationStructureKHR, copyAccelerationStructureToMemoryKHR, copyMemoryToAccelerationStructureKHR, copyMemoryToMicromapEXT, copyMicromapEXT, copyMicromapToMemoryEXT, createDataGraphPipelinesARM, createDeferredOperationKHR, createRayTracingPipelinesKHR, deferredOperationJoinKHR, destroyDeferredOperationKHR, getDeferredOperationMaxConcurrencyKHR, getDeferredOperationResultKHR

Constructors

Instances7Eq, Ord, Show, Storable, HasObjectType, IsHandle, …
datadata PipelineLibraryCreateInfoKHR
#

VkPipelineLibraryCreateInfoKHR - Structure specifying pipeline libraries to use when creating a pipeline

Valid Usage

Valid Usage (Implicit)

  • If libraryCount is not 0, pLibraries must be a valid pointer to an array of libraryCount valid Pipeline handles

Structure Chaining

Extends the structure

See Also

VK_KHR_pipeline_library, ExecutionGraphPipelineCreateInfoAMDX, Pipeline, RayTracingPipelineCreateInfoKHR, StructureType

Constructors

Instances4Show, FromCStruct, ToCStruct, Zero