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

• If a Sampler created with magFilter or minFilter equal to FILTER_LINEAR and compareEnable equal to FALSE is used to sample a ImageView as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT

• If a ImageView is accessed using atomic operations as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT
• If a ImageView is sampled with FILTER_CUBIC_EXT as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
• Any ImageView being sampled with FILTER_CUBIC_EXT as a result of this command must have a ImageViewType and format that supports cubic filtering, as specified by FilterCubicImageViewImageFormatPropertiesEXT::filterCubic returned by getPhysicalDeviceImageFormatProperties2
• Any ImageView being sampled with FILTER_CUBIC_EXT with a reduction mode of either SAMPLER_REDUCTION_MODE_MIN or SAMPLER_REDUCTION_MODE_MAX as a result of this command must have a ImageViewType and format that supports cubic filtering together with minmax filtering, as specified by FilterCubicImageViewImageFormatPropertiesEXT::filterCubicMinmax returned by getPhysicalDeviceImageFormatProperties2
• Any Image created with a ImageCreateInfo::flags containing IMAGE_CREATE_CORNER_SAMPLED_BIT_NV sampled as a result of this command must only be sampled using a SamplerAddressMode of SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE
• For each set n that is statically used by the Pipeline bound to the pipeline bind point used by this command, a descriptor set must have been bound to n at the same pipeline bind point, with a PipelineLayout that is compatible for set n, with the PipelineLayout used to create the current Pipeline, as described in ???
• For each push constant that is statically used by the Pipeline bound to the pipeline bind point used by this command, a push constant value must have been set for the same pipeline bind point, with a PipelineLayout that is compatible for push constants, with the PipelineLayout used to create the current Pipeline, as described in ???
• Descriptors in each bound descriptor set, specified via cmdBindDescriptorSets, must be valid if they are statically used by the Pipeline bound to the pipeline bind point used by this command
• A valid pipeline must be bound to the pipeline bind point used by this command
• If the Pipeline object bound to the pipeline bind point used by this command requires any dynamic state, that state must have been set for commandBuffer, and done so after any previously bound pipeline with the corresponding state not specified as dynamic
• There must not have been any calls to dynamic state setting commands for any state not specified as dynamic in the Pipeline object bound to the pipeline bind point used by this command, since that pipeline was bound
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used to sample from any Image with a ImageView of the type IMAGE_VIEW_TYPE_3D, IMAGE_VIEW_TYPE_CUBE, IMAGE_VIEW_TYPE_1D_ARRAY, IMAGE_VIEW_TYPE_2D_ARRAY or IMAGE_VIEW_TYPE_CUBE_ARRAY, in any shader stage
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions with ImplicitLod, Dref or Proj in their name, in any shader stage
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions that includes a LOD bias or any offset values, in any shader stage
• If the robust buffer access feature is not enabled, and if the Pipeline object bound to the pipeline bind point used by this command accesses a uniform buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point
• If the robust buffer access feature is not enabled, and if the Pipeline object bound to the pipeline bind point used by this command accesses a storage buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point
• If commandBuffer is an unprotected command buffer, any resource accessed by the Pipeline object bound to the pipeline bind point used by this command must not be a protected resource
• If a ImageView is accessed using OpImageWrite as a result of this command, then the Type of the Texel operand of that instruction must have at least as many components as the image view’s format.
• If a BufferView is accessed using OpImageWrite as a result of this command, then the Type of the Texel operand of that instruction must have at least as many components as the image view’s format.
• If a ImageView with a Format that has a 64-bit channel width is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 64.
• If a ImageView with a Format that has a channel width less than 64-bit is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 32.
• If a BufferView with a Format that has a 64-bit channel width is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 64.
• If a BufferView with a Format that has a channel width less than 64-bit is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 32.
• If the sparseImageInt64Atomics feature is not enabled, Image objects created with the IMAGE_CREATE_SPARSE_RESIDENCY_BIT flag must not be accessed by atomic instructions through an OpTypeImage with a SampledType with a Width of 64 by this command.
• If the sparseImageInt64Atomics feature is not enabled, Buffer objects created with the BUFFER_CREATE_SPARSE_RESIDENCY_BIT flag must not be accessed by atomic instructions through an OpTypeImage with a SampledType with a Width of 64 by this command.
• Any shader group handle referenced by this call must have been queried from the currently bound ray tracing shader pipeline
• This command must not cause a shader call instruction to be executed from a shader invocation with a recursion depth greater than the value of maxPipelineRayRecursionDepth used to create the bound ray tracing pipeline
• If the buffer from which pRayGenShaderBindingTable->deviceAddress was queried is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The buffer from which the pRayGenShaderBindingTable->deviceAddress is queried must have been created with the BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag
• pRayGenShaderBindingTable->deviceAddress must be a multiple of PhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupBaseAlignment
• The size member of pRayGenShaderBindingTable must be equal to its stride member
• If the buffer from which pMissShaderBindingTable->deviceAddress was queried is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The buffer from which the pMissShaderBindingTable->deviceAddress is queried must have been created with the BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag
• pMissShaderBindingTable->deviceAddress must be a multiple of PhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupBaseAlignment
• The stride member of pMissShaderBindingTable must be a multiple of PhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleAlignment
• The stride member of pMissShaderBindingTable must be less than or equal to PhysicalDeviceRayTracingPipelinePropertiesKHR::maxShaderGroupStride
• If the buffer from which pHitShaderBindingTable->deviceAddress was queried is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The buffer from which the pHitShaderBindingTable->deviceAddress is queried must have been created with the BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag
• pHitShaderBindingTable->deviceAddress must be a multiple of PhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupBaseAlignment
• The stride member of pHitShaderBindingTable must be a multiple of PhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleAlignment
• The stride member of pHitShaderBindingTable must be less than or equal to PhysicalDeviceRayTracingPipelinePropertiesKHR::maxShaderGroupStride
• If the buffer from which pCallableShaderBindingTable->deviceAddress was queried is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The buffer from which the pCallableShaderBindingTable->deviceAddress is queried must have been created with the BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag
• pCallableShaderBindingTable->deviceAddress must be a multiple of PhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupBaseAlignment
• The stride member of pCallableShaderBindingTable must be a multiple of PhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleAlignment
• The stride member of pCallableShaderBindingTable must be less than or equal to PhysicalDeviceRayTracingPipelinePropertiesKHR::maxShaderGroupStride
• If the currently bound ray tracing pipeline was created with flags that included PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR, the deviceAddress member of pHitShaderBindingTable must not be zero
• If the currently bound ray tracing pipeline was created with flags that included PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, the deviceAddress member of pHitShaderBindingTable must not be zero
• If the currently bound ray tracing pipeline was created with flags that included PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR, the deviceAddress member of pHitShaderBindingTable must not be zero
• If the currently bound ray tracing pipeline was created with flags that included PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR, the shader group handle identified by pMissShaderBindingTable must contain a valid miss shader
• If the currently bound ray tracing pipeline was created with flags that included PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR, entries in pHitShaderBindingTable accessed as a result of this command in order to execute an any-hit shader must not be set to zero
• If the currently bound ray tracing pipeline was created with flags that included PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, entries in pHitShaderBindingTable accessed as a result of this command in order to execute a closest hit shader must not be set to zero
• If the currently bound ray tracing pipeline was created with flags that included PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR, entries in pHitShaderBindingTable accessed as a result of this command in order to execute an intersection shader must not be set to zero
• Any hit group entries in pHitShaderBindingTable accessed by this call from a geometry with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR must have been created with RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR
• Any hit group entries in pHitShaderBindingTable accessed by this call from a geometry with a geometryType of GEOMETRY_TYPE_AABBS_KHR must have been created with RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR
• commandBuffer must not be a protected command buffer
• width must be less than or equal to PhysicalDeviceLimits::maxComputeWorkGroupCount[0] × PhysicalDeviceLimits::maxComputeWorkGroupSize[0]
• height must be less than or equal to PhysicalDeviceLimits::maxComputeWorkGroupCount[1] × PhysicalDeviceLimits::maxComputeWorkGroupSize[1]
• depth must be less than or equal to PhysicalDeviceLimits::maxComputeWorkGroupCount[2] × PhysicalDeviceLimits::maxComputeWorkGroupSize[2]
• width × height × depth must be less than or equal to PhysicalDeviceRayTracingPipelinePropertiesKHR::maxRayDispatchInvocationCount

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pRaygenShaderBindingTable must be a valid pointer to a valid StridedDeviceAddressRegionKHR structure
• pMissShaderBindingTable must be a valid pointer to a valid StridedDeviceAddressRegionKHR structure
• pHitShaderBindingTable must be a valid pointer to a valid StridedDeviceAddressRegionKHR structure
• pCallableShaderBindingTable must be a valid pointer to a valid StridedDeviceAddressRegionKHR structure
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support compute operations
• This command must only be called outside of a render pass instance

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

'

See Also

CommandBuffer, StridedDeviceAddressRegionKHR

vkGetRayTracingShaderGroupHandlesKHR - Query ray tracing pipeline shader group handles

Valid Usage

• pipeline must be a ray tracing pipeline

• firstGroup must be less than the number of shader groups in pipeline
• The sum of firstGroup and groupCount must be less than or equal to the number of shader groups in pipeline
• dataSize must be at least PhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleSize × groupCount
• pipeline must have not been created with PIPELINE_CREATE_LIBRARY_BIT_KHR

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

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

Device, Pipeline

vkGetRayTracingCaptureReplayShaderGroupHandlesKHR - Query ray tracing capture replay pipeline shader group handles

Valid Usage

• pipeline must be a ray tracing pipeline

• firstGroup must be less than the number of shader groups in pipeline
• The sum of firstGroup and groupCount must be less than or equal to the number of shader groups in pipeline
• dataSize must be at least PhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleCaptureReplaySize × groupCount
• PhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplay must be enabled to call this function
• pipeline must have been created with a flags that included PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR

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

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

Device, 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 re-use the shader group handles provided in RayTracingShaderGroupCreateInfoKHR::pShaderGroupCaptureReplayHandle when PhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplay is enabled.

Valid Usage

• If the flags member of any element of pCreateInfos contains the PIPELINE_CREATE_DERIVATIVE_BIT flag, and the basePipelineIndex member of that same element is not -1, basePipelineIndex must be less than the index into pCreateInfos that corresponds to that element

• If the flags member of any element of pCreateInfos contains the PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline must have been created with the PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set
• flags must not contain the PIPELINE_CREATE_DISPATCH_BASE flag
• If pipelineCache was created with PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT, host access to pipelineCache must be externally synchronized
• If deferredOperation is not NULL_HANDLE, it must be a valid DeferredOperationKHR object
• Any previous deferred operation that was associated with deferredOperation must be complete
• The rayTracingPipeline feature must be enabled
• If deferredOperation is not NULL_HANDLE, the flags member of elements of pCreateInfos must not include PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT

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

• SUCCESS
• OPERATION_DEFERRED_KHR
• OPERATION_NOT_DEFERRED_KHR
• PIPELINE_COMPILE_REQUIRED_EXT

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS

See Also

AllocationCallbacks, DeferredOperationKHR, Device, Pipeline, PipelineCache, RayTracingPipelineCreateInfoKHR

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.

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

• If a Sampler created with magFilter or minFilter equal to FILTER_LINEAR and compareEnable equal to FALSE is used to sample a ImageView as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_LINEAR_BIT

• If a ImageView is accessed using atomic operations as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_STORAGE_IMAGE_ATOMIC_BIT
• If a ImageView is sampled with FILTER_CUBIC_EXT as a result of this command, then the image view’s format features must contain FORMAT_FEATURE_SAMPLED_IMAGE_FILTER_CUBIC_BIT_EXT
• Any ImageView being sampled with FILTER_CUBIC_EXT as a result of this command must have a ImageViewType and format that supports cubic filtering, as specified by FilterCubicImageViewImageFormatPropertiesEXT::filterCubic returned by getPhysicalDeviceImageFormatProperties2
• Any ImageView being sampled with FILTER_CUBIC_EXT with a reduction mode of either SAMPLER_REDUCTION_MODE_MIN or SAMPLER_REDUCTION_MODE_MAX as a result of this command must have a ImageViewType and format that supports cubic filtering together with minmax filtering, as specified by FilterCubicImageViewImageFormatPropertiesEXT::filterCubicMinmax returned by getPhysicalDeviceImageFormatProperties2
• Any Image created with a ImageCreateInfo::flags containing IMAGE_CREATE_CORNER_SAMPLED_BIT_NV sampled as a result of this command must only be sampled using a SamplerAddressMode of SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE
• For each set n that is statically used by the Pipeline bound to the pipeline bind point used by this command, a descriptor set must have been bound to n at the same pipeline bind point, with a PipelineLayout that is compatible for set n, with the PipelineLayout used to create the current Pipeline, as described in ???
• For each push constant that is statically used by the Pipeline bound to the pipeline bind point used by this command, a push constant value must have been set for the same pipeline bind point, with a PipelineLayout that is compatible for push constants, with the PipelineLayout used to create the current Pipeline, as described in ???
• Descriptors in each bound descriptor set, specified via cmdBindDescriptorSets, must be valid if they are statically used by the Pipeline bound to the pipeline bind point used by this command
• A valid pipeline must be bound to the pipeline bind point used by this command
• If the Pipeline object bound to the pipeline bind point used by this command requires any dynamic state, that state must have been set for commandBuffer, and done so after any previously bound pipeline with the corresponding state not specified as dynamic
• There must not have been any calls to dynamic state setting commands for any state not specified as dynamic in the Pipeline object bound to the pipeline bind point used by this command, since that pipeline was bound
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used to sample from any Image with a ImageView of the type IMAGE_VIEW_TYPE_3D, IMAGE_VIEW_TYPE_CUBE, IMAGE_VIEW_TYPE_1D_ARRAY, IMAGE_VIEW_TYPE_2D_ARRAY or IMAGE_VIEW_TYPE_CUBE_ARRAY, in any shader stage
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions with ImplicitLod, Dref or Proj in their name, in any shader stage
• If the Pipeline object bound to the pipeline bind point used by this command accesses a Sampler object that uses unnormalized coordinates, that sampler must not be used with any of the SPIR-V OpImageSample* or OpImageSparseSample* instructions that includes a LOD bias or any offset values, in any shader stage
• If the robust buffer access feature is not enabled, and if the Pipeline object bound to the pipeline bind point used by this command accesses a uniform buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point
• If the robust buffer access feature is not enabled, and if the Pipeline object bound to the pipeline bind point used by this command accesses a storage buffer, it must not access values outside of the range of the buffer as specified in the descriptor set bound to the same pipeline bind point
• If commandBuffer is an unprotected command buffer, any resource accessed by the Pipeline object bound to the pipeline bind point used by this command must not be a protected resource
• If a ImageView is accessed using OpImageWrite as a result of this command, then the Type of the Texel operand of that instruction must have at least as many components as the image view’s format.
• If a BufferView is accessed using OpImageWrite as a result of this command, then the Type of the Texel operand of that instruction must have at least as many components as the image view’s format.
• If a ImageView with a Format that has a 64-bit channel width is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 64.
• If a ImageView with a Format that has a channel width less than 64-bit is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 32.
• If a BufferView with a Format that has a 64-bit channel width is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 64.
• If a BufferView with a Format that has a channel width less than 64-bit is accessed as a result of this command, the SampledType of the OpTypeImage operand of that instruction must have a Width of 32.
• If the sparseImageInt64Atomics feature is not enabled, Image objects created with the IMAGE_CREATE_SPARSE_RESIDENCY_BIT flag must not be accessed by atomic instructions through an OpTypeImage with a SampledType with a Width of 64 by this command.
• If the sparseImageInt64Atomics feature is not enabled, Buffer objects created with the BUFFER_CREATE_SPARSE_RESIDENCY_BIT flag must not be accessed by atomic instructions through an OpTypeImage with a SampledType with a Width of 64 by this command.
• Any shader group handle referenced by this call must have been queried from the currently bound ray tracing shader pipeline
• This command must not cause a shader call instruction to be executed from a shader invocation with a recursion depth greater than the value of maxPipelineRayRecursionDepth used to create the bound ray tracing pipeline
• If the buffer from which pRayGenShaderBindingTable->deviceAddress was queried is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The buffer from which the pRayGenShaderBindingTable->deviceAddress is queried must have been created with the BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag
• pRayGenShaderBindingTable->deviceAddress must be a multiple of PhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupBaseAlignment
• The size member of pRayGenShaderBindingTable must be equal to its stride member
• If the buffer from which pMissShaderBindingTable->deviceAddress was queried is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The buffer from which the pMissShaderBindingTable->deviceAddress is queried must have been created with the BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag
• pMissShaderBindingTable->deviceAddress must be a multiple of PhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupBaseAlignment
• The stride member of pMissShaderBindingTable must be a multiple of PhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleAlignment
• The stride member of pMissShaderBindingTable must be less than or equal to PhysicalDeviceRayTracingPipelinePropertiesKHR::maxShaderGroupStride
• If the buffer from which pHitShaderBindingTable->deviceAddress was queried is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The buffer from which the pHitShaderBindingTable->deviceAddress is queried must have been created with the BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag
• pHitShaderBindingTable->deviceAddress must be a multiple of PhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupBaseAlignment
• The stride member of pHitShaderBindingTable must be a multiple of PhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleAlignment
• The stride member of pHitShaderBindingTable must be less than or equal to PhysicalDeviceRayTracingPipelinePropertiesKHR::maxShaderGroupStride
• If the buffer from which pCallableShaderBindingTable->deviceAddress was queried is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The buffer from which the pCallableShaderBindingTable->deviceAddress is queried must have been created with the BUFFER_USAGE_SHADER_BINDING_TABLE_BIT_KHR usage flag
• pCallableShaderBindingTable->deviceAddress must be a multiple of PhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupBaseAlignment
• The stride member of pCallableShaderBindingTable must be a multiple of PhysicalDeviceRayTracingPipelinePropertiesKHR::shaderGroupHandleAlignment
• The stride member of pCallableShaderBindingTable must be less than or equal to PhysicalDeviceRayTracingPipelinePropertiesKHR::maxShaderGroupStride
• If the currently bound ray tracing pipeline was created with flags that included PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR, the deviceAddress member of pHitShaderBindingTable must not be zero
• If the currently bound ray tracing pipeline was created with flags that included PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, the deviceAddress member of pHitShaderBindingTable must not be zero
• If the currently bound ray tracing pipeline was created with flags that included PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR, the deviceAddress member of pHitShaderBindingTable must not be zero
• If the currently bound ray tracing pipeline was created with flags that included PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR, the shader group handle identified by pMissShaderBindingTable must contain a valid miss shader
• If the currently bound ray tracing pipeline was created with flags that included PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR, entries in pHitShaderBindingTable accessed as a result of this command in order to execute an any-hit shader must not be set to zero
• If the currently bound ray tracing pipeline was created with flags that included PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, entries in pHitShaderBindingTable accessed as a result of this command in order to execute a closest hit shader must not be set to zero
• If the currently bound ray tracing pipeline was created with flags that included PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR, entries in pHitShaderBindingTable accessed as a result of this command in order to execute an intersection shader must not be set to zero
• Any hit group entries in pHitShaderBindingTable accessed by this call from a geometry with a geometryType of GEOMETRY_TYPE_TRIANGLES_KHR must have been created with RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR
• Any hit group entries in pHitShaderBindingTable accessed by this call from a geometry with a geometryType of GEOMETRY_TYPE_AABBS_KHR must have been created with RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR
• If the buffer from which indirectDeviceAddress was queried is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The buffer from which indirectDeviceAddress was queried must have been created with the BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set
• indirectDeviceAddress must be a multiple of 4
• commandBuffer must not be a protected command buffer
• All device addresses between indirectDeviceAddress and indirectDeviceAddress + sizeof(TraceRaysIndirectCommandKHR) - 1 must be in the buffer device address range of the same buffer
• the ::rayTracingPipelineTraceRaysIndirect feature must be enabled

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pRaygenShaderBindingTable must be a valid pointer to a valid StridedDeviceAddressRegionKHR structure
• pMissShaderBindingTable must be a valid pointer to a valid StridedDeviceAddressRegionKHR structure
• pHitShaderBindingTable must be a valid pointer to a valid StridedDeviceAddressRegionKHR structure
• pCallableShaderBindingTable must be a valid pointer to a valid StridedDeviceAddressRegionKHR structure
• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support compute operations
• This command must only be called outside of a render pass instance

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

'

See Also

CommandBuffer, DeviceAddress, StridedDeviceAddressRegionKHR

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

Device, Pipeline, ShaderGroupShaderKHR

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

Description

See Ray Tracing Pipeline Stack for more on computing pipelineStackSize.

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 a valid CommandBuffer handle

• commandBuffer must be in the recording state
• The CommandPool that commandBuffer was allocated from must support compute operations
• This command must only be called outside of a render pass instance

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

'

See Also

CommandBuffer

VkRayTracingShaderGroupCreateInfoKHR - Structure specifying shaders in a shader group

Valid Usage

• If type is RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR then generalShader must be a valid index into RayTracingPipelineCreateInfoKHR::pStages referring to a shader of SHADER_STAGE_RAYGEN_BIT_KHR, SHADER_STAGE_MISS_BIT_KHR, or SHADER_STAGE_CALLABLE_BIT_KHR

• If type is RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR then closestHitShader, anyHitShader, and intersectionShader must be SHADER_UNUSED_KHR
• If type is RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR then intersectionShader must be a valid index into RayTracingPipelineCreateInfoKHR::pStages referring to a shader of SHADER_STAGE_INTERSECTION_BIT_KHR
• If type is RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR then intersectionShader must be SHADER_UNUSED_KHR
• closestHitShader must be either SHADER_UNUSED_KHR or a valid index into RayTracingPipelineCreateInfoKHR::pStages referring to a shader of SHADER_STAGE_CLOSEST_HIT_BIT_KHR
• anyHitShader must be either SHADER_UNUSED_KHR or a valid index into RayTracingPipelineCreateInfoKHR::pStages referring to a shader of SHADER_STAGE_ANY_HIT_BIT_KHR
• If PhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplayMixed is FALSE then pShaderGroupCaptureReplayHandle must not be provided if it has not been provided on a previous call to ray tracing pipeline creation
• If PhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplayMixed is FALSE then the caller must guarantee that no ray tracing pipeline creation commands with pShaderGroupCaptureReplayHandle provided execute simultaneously with ray tracing pipeline creation commands without pShaderGroupCaptureReplayHandle provided

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_RAY_TRACING_SHADER_GROUP_CREATE_INFO_KHR

• pNext must be NULL
• type must be a valid RayTracingShaderGroupTypeKHR value

See Also

RayTracingPipelineCreateInfoKHR, RayTracingShaderGroupTypeKHR, StructureType

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.

Valid Usage

• If flags contains the PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is -1, basePipelineHandle must be a valid handle to a ray tracing Pipeline

• If flags contains the PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineHandle is NULL_HANDLE, basePipelineIndex must be a valid index into the calling command’s pCreateInfos parameter
• If flags contains the PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is not -1, basePipelineHandle must be NULL_HANDLE
• If flags contains the PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineHandle is not NULL_HANDLE, basePipelineIndex must be -1
• The shader code for the entry points identified by pStages, and the rest of the state identified by this structure must adhere to the pipeline linking rules described in the Shader Interfaces chapter
• layout must be consistent with all shaders specified in pStages
• The number of resources in layout accessible to each shader stage that is used by the pipeline must be less than or equal to PhysicalDeviceLimits::maxPerStageResources
• flags must not include PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV
• If the pipelineCreationCacheControl feature is not enabled, flags must not include PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT or PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT
• If flags does not include PIPELINE_CREATE_LIBRARY_BIT_KHR, the stage member of at least one element of pStages, including those implicitly added by pLibraryInfo, must be SHADER_STAGE_RAYGEN_BIT_KHR
• maxPipelineRayRecursionDepth must be less than or equal to PhysicalDeviceRayTracingPipelinePropertiesKHR::maxRayRecursionDepth
• If flags includes PIPELINE_CREATE_LIBRARY_BIT_KHR, pLibraryInterface must not be NULL
• If pLibraryInfo is not NULL and its libraryCount member is greater than 0, its pLibraryInterface member must not be NULL
• Each element of the pLibraries member of pLibraryInfo must have been created with the value of maxPipelineRayRecursionDepth equal to that in this pipeline
• If pLibraryInfo is not NULL, each element of its pLibraries member must have been created with a layout that is compatible with the layout in this pipeline
• If pLibraryInfo is not NULL, each element of its pLibraries member must have been created with values of the maxPipelineRayPayloadSize and maxPipelineRayHitAttributeSize members of pLibraryInterface equal to those in this pipeline
• If flags includes PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR, each element of the pLibraries member of libraries must have been created with the PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR bit set
• If the VK_KHR_pipeline_library extension is not enabled, pLibraryInfo and pLibraryInterface must be NULL.
• If flags includes PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR, for any element of pGroups with a type of RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, the anyHitShader of that element must not be SHADER_UNUSED_KHR
• If flags includes PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, for any element of pGroups with a type of RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, the closestHitShader of that element must not be SHADER_UNUSED_KHR
• If the rayTraversalPrimitiveCulling feature is not enabled, flags must not include PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR
• If the rayTraversalPrimitiveCulling feature is not enabled, flags must not include PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR
• If flags includes PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR, rayTracingPipelineShaderGroupHandleCaptureReplay must be enabled
• If PhysicalDeviceRayTracingPipelineFeaturesKHR::rayTracingPipelineShaderGroupHandleCaptureReplay is TRUE and the pShaderGroupCaptureReplayHandle member of any element of pGroups is not NULL, flags must include PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR
• If pLibraryInfo is not NULL and its libraryCount is 0, stageCount must not be 0
• If pLibraryInfo is not NULL and its libraryCount is 0, groupCount must not be 0
• Any element of the pDynamicStates member of pDynamicState must be DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_RAY_TRACING_PIPELINE_CREATE_INFO_KHR

• pNext must be NULL or a pointer to a valid instance of PipelineCreationFeedbackCreateInfoEXT
• The sType value of each struct in the pNext chain must be unique
• flags must be a valid combination of PipelineCreateFlagBits values
• If stageCount is not 0, pStages must be a valid pointer to an array of stageCount valid PipelineShaderStageCreateInfo structures
• If groupCount is not 0, pGroups must be a valid pointer to an array of groupCount valid RayTracingShaderGroupCreateInfoKHR structures
• If pLibraryInfo is not NULL, pLibraryInfo must be a valid pointer to a valid PipelineLibraryCreateInfoKHR structure
• If pLibraryInterface is not NULL, pLibraryInterface must be a valid pointer to a valid RayTracingPipelineInterfaceCreateInfoKHR structure
• If pDynamicState is not NULL, pDynamicState must be a valid pointer to a valid PipelineDynamicStateCreateInfo structure
• layout must be a valid PipelineLayout handle
• Both of basePipelineHandle, and layout that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same Device

See Also

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

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

Members

The members of the PhysicalDeviceRayTracingPipelineFeaturesKHR structure describe the following features:

Description

• rayTracingPipeline indicates whether the implementation supports the ray tracing pipeline functionality. See Ray Tracing.

• rayTracingPipelineShaderGroupHandleCaptureReplay indicates whether the implementation supports saving and reusing shader group handles, e.g. for trace capture and replay.
• rayTracingPipelineShaderGroupHandleCaptureReplayMixed indicates whether the implementation supports reuse of shader group handles being arbitrarily mixed with creation of non-reused shader group handles. If this is FALSE, all reused shader group handles must be specified before any non-reused handles may be created.
• rayTracingPipelineTraceRaysIndirect indicates whether the implementation supports indirect trace ray commands, e.g. cmdTraceRaysIndirectKHR.
• rayTraversalPrimitiveCulling indicates whether the implementation supports primitive culling during ray traversal.

If the PhysicalDeviceRayTracingPipelineFeaturesKHR structure is included in the pNext chain of PhysicalDeviceFeatures2, it is filled with values indicating whether the feature is supported. PhysicalDeviceRayTracingPipelineFeaturesKHR can also be used in the pNext chain of DeviceCreateInfo to enable the features.

Valid Usage

• If rayTracingPipelineShaderGroupHandleCaptureReplayMixed is TRUE, rayTracingPipelineShaderGroupHandleCaptureReplay must also be TRUE

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_PIPELINE_FEATURES_KHR

See Also

Bool32, StructureType

VkPhysicalDeviceRayTracingPipelinePropertiesKHR - Properties of the physical device for ray tracing

Description

If the PhysicalDeviceRayTracingPipelinePropertiesKHR structure is included in the pNext chain of PhysicalDeviceProperties2, it is filled with the implementation-dependent limits.

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

Valid Usage (Implicit)

See Also

StructureType

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

Valid Usage

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

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

See Also

DeviceAddress, DeviceSize, cmdTraceRaysIndirectKHR, cmdTraceRaysKHR

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

Description

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

Valid Usage

See Also

No cross-references are available

VkRayTracingPipelineInterfaceCreateInfoKHR - Structure specifying additional interface information when using libraries

Description

maxPipelineRayPayloadSize is calculated as the maximum number of bytes used by any block declared in the RayPayloadKHR or IncomingRayPayloadKHR storage classes. maxPipelineRayHitAttributeSize is calculated as the maximum number of bytes used by any block declared in the HitAttributeKHR 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.

Note

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

RayTracingPipelineCreateInfoKHR, StructureType

VkRayTracingShaderGroupTypeKHR - Shader group types

Description

Note

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

RayTracingShaderGroupCreateInfoKHR, RayTracingShaderGroupCreateInfoNV

VkShaderGroupShaderKHR - Shader group shaders

See Also

getRayTracingShaderGroupStackSizeKHR

VkDeferredOperationKHR - A deferred operation

Description

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

See Also

buildAccelerationStructuresKHR, copyAccelerationStructureKHR, copyAccelerationStructureToMemoryKHR, copyMemoryToAccelerationStructureKHR, createDeferredOperationKHR, createRayTracingPipelinesKHR, deferredOperationJoinKHR, destroyDeferredOperationKHR, getDeferredOperationMaxConcurrencyKHR, getDeferredOperationResultKHR

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

Valid Usage

• Each element of pLibraries must have been created with PIPELINE_CREATE_LIBRARY_BIT_KHR

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_PIPELINE_LIBRARY_CREATE_INFO_KHR

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

See Also

Pipeline, RayTracingPipelineCreateInfoKHR, StructureType