vkDestroyAccelerationStructureKHR - Destroy an acceleration structure object

Valid Usage

• All submitted commands that refer to accelerationStructure must have completed execution

• If AllocationCallbacks were provided when accelerationStructure was created, a compatible set of callbacks must be provided here
• If no AllocationCallbacks were provided when accelerationStructure was created, pAllocator must be NULL

Valid Usage (Implicit)

• device must be a valid Device handle

• If accelerationStructure is not NULL_HANDLE, accelerationStructure must be a valid AccelerationStructureKHR handle
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• If accelerationStructure is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to accelerationStructure must be externally synchronized

See Also

AccelerationStructureKHR, AllocationCallbacks, Device

vkGetAccelerationStructureMemoryRequirementsKHR - Get acceleration structure memory requirements

Valid Usage (Implicit)

See Also

AccelerationStructureMemoryRequirementsInfoKHR, Device, MemoryRequirements2

vkBindAccelerationStructureMemoryKHR - Bind acceleration structure memory

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

BindAccelerationStructureMemoryInfoKHR, Device

vkCmdCopyAccelerationStructureKHR - Copy an acceleration structure

Valid Usage

• All AccelerationStructureKHR objects referenced by this command must be bound to device memory

• The DeferredOperationInfoKHR structure must not be included in the pNext chain of the CopyAccelerationStructureInfoKHR structure

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pInfo must be a valid pointer to a valid CopyAccelerationStructureInfoKHR 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, CopyAccelerationStructureInfoKHR

vkCopyAccelerationStructureKHR - Copy an acceleration structure on the host

Parameters

This command fulfills the same task as cmdCopyAccelerationStructureKHR but executed by the host.

Description

• device is the device which owns the acceleration structures.

• pInfo is a pointer to a CopyAccelerationStructureInfoKHR structure defining the copy operation.

If the DeferredOperationInfoKHR structure is included in the pNext chain of the CopyAccelerationStructureInfoKHR structure, the operation of this command is deferred, as defined in the Deferred Host Operations chapter.

Valid Usage

• All AccelerationStructureKHR objects referenced by this command must be bound to host-visible memory

• the ::rayTracingHostAccelerationStructureCommands feature must be enabled

Valid Usage (Implicit)

• device must be a valid Device handle

• pInfo must be a valid pointer to a valid CopyAccelerationStructureInfoKHR structure

Return Codes

Success

• SUCCESS
• OPERATION_DEFERRED_KHR
• OPERATION_NOT_DEFERRED_KHR

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

CopyAccelerationStructureInfoKHR, Device

vkCmdCopyAccelerationStructureToMemoryKHR - Copy an acceleration structure to device memory

Parameters

This command produces the same results as copyAccelerationStructureToMemoryKHR, but writes its result to a device address, and is executed on the device rather than the host. The output may not necessarily be bit-for-bit identical, but it can be equally used by either cmdCopyMemoryToAccelerationStructureKHR or copyMemoryToAccelerationStructureKHR.

Description

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

• pInfo is an a pointer to a CopyAccelerationStructureToMemoryInfoKHR structure defining the copy operation.

The defined header structure for the serialized data consists of:

• UUID_SIZE bytes of data matching PhysicalDeviceIDProperties::driverUUID
• UUID_SIZE bytes of data identifying the compatibility for comparison using getDeviceAccelerationStructureCompatibilityKHR
• A 64-bit integer of the total size matching the value queried using QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR
• A 64-bit integer of the deserialized size to be passed in to AccelerationStructureCreateInfoKHR::compactedSize
• A 64-bit integer of the count of the number of acceleration structure handles following. This will be zero for a bottom-level acceleration structure.

The corresponding handles matching the values returned by getAccelerationStructureDeviceAddressKHR or getAccelerationStructureHandleNV are tightly packed in the buffer following the count. The application is expected to store a mapping between those handles and the original application-generated bottom-level acceleration structures to provide when deserializing.

Valid Usage

• All DeviceOrHostAddressConstKHR referenced by this command must contain valid device addresses for a buffer bound to device memory. If the buffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

• All AccelerationStructureKHR objects referenced by this command must be bound to device memory
• The DeferredOperationInfoKHR structure must not be included in the pNext chain of the CopyAccelerationStructureToMemoryInfoKHR structure
• mode must be COPY_ACCELERATION_STRUCTURE_MODE_SERIALIZE_KHR

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pInfo must be a valid pointer to a valid CopyAccelerationStructureToMemoryInfoKHR 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, CopyAccelerationStructureToMemoryInfoKHR

vkCopyAccelerationStructureToMemoryKHR - Serialize an acceleration structure on the host

Parameters

This command fulfills the same task as cmdCopyAccelerationStructureToMemoryKHR but executed by the host.

Description

This command produces the same results as cmdCopyAccelerationStructureToMemoryKHR, but writes its result directly to a host pointer, and is executed on the host rather than the device. The output may not necessarily be bit-for-bit identical, but it can be equally used by either cmdCopyMemoryToAccelerationStructureKHR or copyMemoryToAccelerationStructureKHR.

• device is the device which owns pInfo->src.
• pInfo is a pointer to a CopyAccelerationStructureToMemoryInfoKHR structure defining the copy operation.

If the DeferredOperationInfoKHR structure is included in the pNext chain of the CopyAccelerationStructureToMemoryInfoKHR structure, the operation of this command is deferred, as defined in the https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#deferred-host-operations chapter.

Valid Usage

• All AccelerationStructureKHR objects referenced by this command must be bound to host-visible memory

• All DeviceOrHostAddressKHR referenced by this command must contain valid host pointers
• the ::rayTracingHostAccelerationStructureCommands feature must be enabled

Valid Usage (Implicit)

• device must be a valid Device handle

• pInfo must be a valid pointer to a valid CopyAccelerationStructureToMemoryInfoKHR structure

Return Codes

Success

• SUCCESS
• OPERATION_DEFERRED_KHR
• OPERATION_NOT_DEFERRED_KHR

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

CopyAccelerationStructureToMemoryInfoKHR, Device

vkCmdCopyMemoryToAccelerationStructureKHR - Copy device memory to an acceleration structure

Parameters

This command can accept acceleration structures produced by either cmdCopyAccelerationStructureToMemoryKHR or copyAccelerationStructureToMemoryKHR.

Description

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

• pInfo is a pointer to a CopyMemoryToAccelerationStructureInfoKHR structure defining the copy operation.

The structure provided as input to deserialize is as described in cmdCopyAccelerationStructureToMemoryKHR, with any acceleration structure handles filled in with the newly-queried handles to bottom level acceleration structures created before deserialization. These do not need to be built at deserialize time, but must be created.

Valid Usage

• All DeviceOrHostAddressKHR referenced by this command must contain valid device addresses for a buffer bound to device memory. If the buffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

• All AccelerationStructureKHR objects referenced by this command must be bound to device memory
• The DeferredOperationInfoKHR structure must not be included in the pNext chain of the CopyMemoryToAccelerationStructureInfoKHR structure
• mode must be COPY_ACCELERATION_STRUCTURE_MODE_DESERIALIZE_KHR
• The data in pInfo->src must have a format compatible with the destination physical device as returned by getDeviceAccelerationStructureCompatibilityKHR

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pInfo must be a valid pointer to a valid CopyMemoryToAccelerationStructureInfoKHR 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, CopyMemoryToAccelerationStructureInfoKHR

vkCopyMemoryToAccelerationStructureKHR - Deserialize an acceleration structure on the host

Parameters

This command fulfills the same task as cmdCopyMemoryToAccelerationStructureKHR but is executed by the host.

Description

This command can accept acceleration structures produced by either cmdCopyAccelerationStructureToMemoryKHR or copyAccelerationStructureToMemoryKHR.

• device is the device which owns pInfo->dst.
• pInfo is a pointer to a CopyMemoryToAccelerationStructureInfoKHR structure defining the copy operation.

If the DeferredOperationInfoKHR structure is included in the pNext chain of the CopyMemoryToAccelerationStructureInfoKHR structure, the operation of this command is deferred, as defined in the Deferred Host Operations chapter.

Valid Usage

• All AccelerationStructureKHR objects referenced by this command must be bound to host-visible memory

• All DeviceOrHostAddressConstKHR referenced by this command must contain valid host pointers
• the ::rayTracingHostAccelerationStructureCommands feature must be enabled

Valid Usage (Implicit)

• device must be a valid Device handle

• pInfo must be a valid pointer to a valid CopyMemoryToAccelerationStructureInfoKHR structure

Return Codes

Success

• SUCCESS
• OPERATION_DEFERRED_KHR
• OPERATION_NOT_DEFERRED_KHR

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

CopyMemoryToAccelerationStructureInfoKHR, Device

vkCmdWriteAccelerationStructuresPropertiesKHR - Write acceleration structure result parameters to query results.

Valid Usage

• queryPool must have been created with a queryType matching queryType

• The queries identified by queryPool and firstQuery must be unavailable
• All acceleration structures in accelerationStructures must have been built with BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR if queryType is QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR
• queryType must be QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR or QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pAccelerationStructures must be a valid pointer to an array of accelerationStructureCount valid AccelerationStructureKHR handles
• queryType must be a valid QueryType value
• queryPool must be a valid QueryPool 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
• accelerationStructureCount must be greater than 0
• Each of commandBuffer, queryPool, and the elements of pAccelerationStructures must have been created, allocated, or retrieved from the same Device

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

AccelerationStructureKHR, CommandBuffer, QueryPool, QueryType

vkWriteAccelerationStructuresPropertiesKHR - Query acceleration structure meta-data on the host

Parameters

This command fulfills the same task as cmdWriteAccelerationStructuresPropertiesKHR but executed by the host.

Description

• device is the device which owns the acceleration structures in pAccelerationStructures.

• accelerationStructureCount is the count of acceleration structures for which to query the property.
• pAccelerationStructures points to an array of existing previously built acceleration structures.
• queryType is a QueryType value specifying the property to be queried.
• dataSize is the size in bytes of the buffer pointed to by pData.
• pData is a pointer to a user-allocated buffer where the results will be written.
• stride is the stride in bytes between results for individual queries within pData.

Valid Usage

• If queryType is QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then stride must be a multiple of the size of DeviceSize

• If queryType is QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then data must point to a DeviceSize
• If queryType is QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then stride must be a multiple of the size of DeviceSize
• If queryType is QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then data must point to a DeviceSize
• dataSize must be greater than or equal to accelerationStructureCount*stride
• The acceleration structures referenced by pAccelerationStructures must be bound to host-visible memory
• All acceleration structures in accelerationStructures must have been built with BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR if queryType is QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR
• queryType must be QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR or QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR
• the ::rayTracingHostAccelerationStructureCommands feature must be enabled

Valid Usage (Implicit)

• device must be a valid Device handle

• pAccelerationStructures must be a valid pointer to an array of accelerationStructureCount valid AccelerationStructureKHR handles
• queryType must be a valid QueryType value
• pData must be a valid pointer to an array of dataSize bytes
• accelerationStructureCount must be greater than 0
• dataSize must be greater than 0
• Each element of pAccelerationStructures 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

AccelerationStructureKHR, Device, QueryType

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 ImageView is sampled with FILTER_LINEAR 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.
• 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 maxRecursionDepth used to create the bound ray tracing pipeline
• If pRayGenShaderBindingTable->buffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The offset member of pRayGenShaderBindingTable must be less than the size of the pRayGenShaderBindingTable->buffer
• pRayGenShaderBindingTable->offset must be a multiple of PhysicalDeviceRayTracingPropertiesKHR::shaderGroupBaseAlignment
• pRayGenShaderBindingTable->offset + pRayGenShaderBindingTable->size must be less than or equal to the size of pRayGenShaderBindingTable->buffer
• The size member of pRayGenShaderBindingTable must be equal to its stride member
• If pMissShaderBindingTable->buffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The offset member of pMissShaderBindingTable must be less than the size of pMissShaderBindingTable->buffer
• The offset member of pMissShaderBindingTable must be a multiple of PhysicalDeviceRayTracingPropertiesKHR::shaderGroupBaseAlignment
• pMissShaderBindingTable->offset + pMissShaderBindingTable->size must be less than or equal to the size of pMissShaderBindingTable->buffer
• The stride member of pMissShaderBindingTable must be a multiple of PhysicalDeviceRayTracingPropertiesKHR::shaderGroupHandleSize
• The stride member of pMissShaderBindingTable must be less than or equal to PhysicalDeviceRayTracingPropertiesKHR::maxShaderGroupStride
• If pHitShaderBindingTable->buffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The offset member of pHitShaderBindingTable must be less than the size of pHitShaderBindingTable->buffer
• The offset member of pHitShaderBindingTable must be a multiple of PhysicalDeviceRayTracingPropertiesKHR::shaderGroupBaseAlignment
• pHitShaderBindingTable->offset + pHitShaderBindingTable->size must be less than or equal to the size of pHitShaderBindingTable->buffer
• The stride member of pHitShaderBindingTable must be a multiple of PhysicalDeviceRayTracingPropertiesKHR::shaderGroupHandleSize
• The stride member of pHitShaderBindingTable must be less than or equal to PhysicalDeviceRayTracingPropertiesKHR::maxShaderGroupStride
• If pCallableShaderBindingTable->buffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The offset member of pCallableShaderBindingTable must be less than the size of pCallableShaderBindingTable->buffer
• The offset member of pCallableShaderBindingTable must be a multiple of PhysicalDeviceRayTracingPropertiesKHR::shaderGroupBaseAlignment
• pCallableShaderBindingTable->offset + pCallableShaderBindingTable->size must be less than or equal to the size of pCallableShaderBindingTable->buffer
• The stride member of pCallableShaderBindingTable must be a multiple of PhysicalDeviceRayTracingPropertiesKHR::shaderGroupHandleSize
• The stride member of pCallableShaderBindingTable must be less than or equal to PhysicalDeviceRayTracingPropertiesKHR::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 buffer member of pHitShaderBindingTable must not be NULL_HANDLE
• 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 buffer member of pHitShaderBindingTable must not be NULL_HANDLE
• If the currently bound ray tracing pipeline was created with flags that included PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR, the buffer member of pHitShaderBindingTable must not be NULL_HANDLE
• 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
• If commandBuffer is a protected command buffer, any resource written to by the Pipeline object bound to the pipeline bind point used by this command must not be an unprotected resource
• If commandBuffer is a protected command buffer, pipeline stages other than the framebuffer-space and compute stages in the Pipeline object bound to the pipeline bind point must not write to any resource
• width must be less than or equal to PhysicalDeviceLimits::maxComputeWorkGroupCount[0]
• height must be less than or equal to PhysicalDeviceLimits::maxComputeWorkGroupCount[1]
• depth must be less than or equal to PhysicalDeviceLimits::maxComputeWorkGroupCount[2]

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pRaygenShaderBindingTable must be a valid pointer to a valid StridedBufferRegionKHR structure
• pMissShaderBindingTable must be a valid pointer to a valid StridedBufferRegionKHR structure
• pHitShaderBindingTable must be a valid pointer to a valid StridedBufferRegionKHR structure
• pCallableShaderBindingTable must be a valid pointer to a valid StridedBufferRegionKHR 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, StridedBufferRegionKHR

vkGetRayTracingShaderGroupHandlesKHR - Query ray tracing pipeline shader group handles

Valid Usage

• 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 PhysicalDeviceRayTracingPropertiesKHR::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

• 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 PhysicalDeviceRayTracingPropertiesKHR::shaderGroupHandleCaptureReplaySize × groupCount
• PhysicalDeviceRayTracingFeaturesKHR::rayTracingShaderGroupHandleCaptureReplay must be enabled to call this function

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 PhysicalDeviceRayTracingFeaturesKHR::rayTracingShaderGroupHandleCaptureReplay 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
• If pipelineCache was created with PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT, host access to pipelineCache must be externally synchronized
• The rayTracing feature must be enabled

Valid Usage (Implicit)

• device must be a valid Device 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 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, Device, Pipeline, PipelineCache, RayTracingPipelineCreateInfoKHR

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 buffer during execution. The parameters of trace ray are encoded in the TraceRaysIndirectCommandKHR structure located at offset bytes in buffer.

Valid Usage

• If a ImageView is sampled with FILTER_LINEAR 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.
• 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 maxRecursionDepth used to create the bound ray tracing pipeline
• If pRayGenShaderBindingTable->buffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The offset member of pRayGenShaderBindingTable must be less than the size of the pRayGenShaderBindingTable->buffer
• pRayGenShaderBindingTable->offset must be a multiple of PhysicalDeviceRayTracingPropertiesKHR::shaderGroupBaseAlignment
• pRayGenShaderBindingTable->offset + pRayGenShaderBindingTable->size must be less than or equal to the size of pRayGenShaderBindingTable->buffer
• The size member of pRayGenShaderBindingTable must be equal to its stride member
• If pMissShaderBindingTable->buffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The offset member of pMissShaderBindingTable must be less than the size of pMissShaderBindingTable->buffer
• The offset member of pMissShaderBindingTable must be a multiple of PhysicalDeviceRayTracingPropertiesKHR::shaderGroupBaseAlignment
• pMissShaderBindingTable->offset + pMissShaderBindingTable->size must be less than or equal to the size of pMissShaderBindingTable->buffer
• The stride member of pMissShaderBindingTable must be a multiple of PhysicalDeviceRayTracingPropertiesKHR::shaderGroupHandleSize
• The stride member of pMissShaderBindingTable must be less than or equal to PhysicalDeviceRayTracingPropertiesKHR::maxShaderGroupStride
• If pHitShaderBindingTable->buffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The offset member of pHitShaderBindingTable must be less than the size of pHitShaderBindingTable->buffer
• The offset member of pHitShaderBindingTable must be a multiple of PhysicalDeviceRayTracingPropertiesKHR::shaderGroupBaseAlignment
• pHitShaderBindingTable->offset + pHitShaderBindingTable->size must be less than or equal to the size of pHitShaderBindingTable->buffer
• The stride member of pHitShaderBindingTable must be a multiple of PhysicalDeviceRayTracingPropertiesKHR::shaderGroupHandleSize
• The stride member of pHitShaderBindingTable must be less than or equal to PhysicalDeviceRayTracingPropertiesKHR::maxShaderGroupStride
• If pCallableShaderBindingTable->buffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• The offset member of pCallableShaderBindingTable must be less than the size of pCallableShaderBindingTable->buffer
• The offset member of pCallableShaderBindingTable must be a multiple of PhysicalDeviceRayTracingPropertiesKHR::shaderGroupBaseAlignment
• pCallableShaderBindingTable->offset + pCallableShaderBindingTable->size must be less than or equal to the size of pCallableShaderBindingTable->buffer
• The stride member of pCallableShaderBindingTable must be a multiple of PhysicalDeviceRayTracingPropertiesKHR::shaderGroupHandleSize
• The stride member of pCallableShaderBindingTable must be less than or equal to PhysicalDeviceRayTracingPropertiesKHR::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 buffer member of pHitShaderBindingTable must not be NULL_HANDLE
• 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 buffer member of pHitShaderBindingTable must not be NULL_HANDLE
• If the currently bound ray tracing pipeline was created with flags that included PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR, the buffer member of pHitShaderBindingTable must not be NULL_HANDLE
• 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
• If buffer is non-sparse then it must be bound completely and contiguously to a single DeviceMemory object
• buffer must have been created with the BUFFER_USAGE_INDIRECT_BUFFER_BIT bit set
• offset must be a multiple of 4
• commandBuffer must not be a protected command buffer
• (offset + sizeof(TraceRaysIndirectCommandKHR)) must be less than or equal to the size of buffer
• the ::rayTracingIndirectTraceRays feature must be enabled

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pRaygenShaderBindingTable must be a valid pointer to a valid StridedBufferRegionKHR structure
• pMissShaderBindingTable must be a valid pointer to a valid StridedBufferRegionKHR structure
• pHitShaderBindingTable must be a valid pointer to a valid StridedBufferRegionKHR structure
• pCallableShaderBindingTable must be a valid pointer to a valid StridedBufferRegionKHR structure
• buffer must be a valid Buffer 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
• Both of buffer, and commandBuffer must have been created, allocated, or retrieved from the same Device

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

Buffer, CommandBuffer, DeviceSize, StridedBufferRegionKHR

vkGetDeviceAccelerationStructureCompatibilityKHR - Check if a serialized acceleration structure is compatible with the current device

Description

This possible return values for getDeviceAccelerationStructureCompatibilityKHR are:

• SUCCESS is returned if an acceleration structure serialized with version as the version information is compatible with device.
• ERROR_INCOMPATIBLE_VERSION_KHR is returned if an acceleration structure serialized with version as the version information is not compatible with device.

Valid Usage

• The rayTracing or rayQuery feature must be enabled

Valid Usage (Implicit)

• device must be a valid Device handle

• version must be a valid pointer to a valid AccelerationStructureVersionKHR structure

Return Codes

Success

• SUCCESS

Failure

• ERROR_INCOMPATIBLE_VERSION_KHR

See Also

AccelerationStructureVersionKHR, Device

vkCreateAccelerationStructureKHR - Create a new acceleration structure object

Description

Similar to other objects in Vulkan, the acceleration structure creation merely creates an object with a specific “shape”. The type and quantity of geometry that can be built into an acceleration structure is determined by the parameters of AccelerationStructureCreateInfoKHR.

Populating the data in the object after allocating and binding memory is done with commands such as cmdBuildAccelerationStructureKHR, buildAccelerationStructureKHR, cmdCopyAccelerationStructureKHR, and copyAccelerationStructureKHR.

The input buffers passed to acceleration structure build commands will be referenced by the implementation for the duration of the command. After the command completes, the acceleration structure may hold a reference to any acceleration structure specified by an active instance contained therein. Apart from this referencing, acceleration structures must be fully self-contained. The application may re-use or free any memory which was used by the command as an input or as scratch without affecting the results of ray traversal.

Valid Usage

• The rayTracing or rayQuery feature must be enabled

• If AccelerationStructureCreateInfoKHR::deviceAddress is not zero, the rayTracingAccelerationStructureCaptureReplay feature must be enabled
• If device was created with multiple physical devices, then the bufferDeviceAddressMultiDevice feature must be enabled

Valid Usage (Implicit)

• device must be a valid Device handle

• pCreateInfo must be a valid pointer to a valid AccelerationStructureCreateInfoKHR structure
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• pAccelerationStructure must be a valid pointer to a AccelerationStructureKHR handle

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

See Also

AccelerationStructureCreateInfoKHR, AccelerationStructureKHR, AllocationCallbacks, Device

A convenience wrapper to make a compatible pair of calls to createAccelerationStructureKHR and destroyAccelerationStructureKHR

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

vkCmdBuildAccelerationStructureKHR - Build an acceleration structure

Description

The cmdBuildAccelerationStructureKHR command provides the ability to initiate multiple acceleration structures builds, however there is no ordering or synchronization implied between any of the individual acceleration structure builds.

Note

This means that an application cannot build a top-level acceleration structure in the same cmdBuildAccelerationStructureKHR call as the associated bottom-level or instance acceleration structures are being built. There also cannot be any memory aliasing between any acceleration structure memories or scratch memories being used by any of the builds.

Valid Usage

• Each element of ppOffsetInfos[i] must be a valid pointer to an array of pInfos[i].geometryCount AccelerationStructureBuildOffsetInfoKHR structures

• Each pInfos[i].srcAccelerationStructure must not refer to the same acceleration structure as any pInfos[i].dstAccelerationStructure that is provided to the same build command unless it is identical for an update
• For each pInfos[i], dstAccelerationStructure must have been created with compatible AccelerationStructureCreateInfoKHR where AccelerationStructureCreateInfoKHR::type and AccelerationStructureCreateInfoKHR::flags are identical to AccelerationStructureBuildGeometryInfoKHR::type and AccelerationStructureBuildGeometryInfoKHR::flags respectively, AccelerationStructureBuildGeometryInfoKHR::geometryCount for dstAccelerationStructure are greater than or equal to the build size, and each geometry in AccelerationStructureBuildGeometryInfoKHR::ppGeometries for dstAccelerationStructure has greater than or equal to the number of vertices, indices, and AABBs, AccelerationStructureGeometryTrianglesDataKHR::transformData is both 0 or both non-zero, and all other parameters are the same
• For each pInfos[i], if update is TRUE, then objects that were previously active for that acceleration structure must not be made inactive as per ???
• For each pInfos[i], if update is TRUE, then objects that were previously inactive for that acceleration structure must not be made active as per ???
• Any acceleration structure instance in any top level build in this command must not reference any bottom level acceleration structure built by this command
• There must not be any memory aliasing between the scratch memories that are provided in all the pInfos[i].scratchData memories for the acceleration structure builds
• There must not be any memory aliasing between memory bound to any top level, bottom level, or instance acceleration structure accessed by this command
• If update is FALSE, all addresses between pInfos[i].scratchData and pInfos[i].scratchData + N
• 1 must be in the buffer device address range of the same buffer, where N is given by the size member of the MemoryRequirements structure returned from a call to getAccelerationStructureMemoryRequirementsKHR with AccelerationStructureMemoryRequirementsInfoKHR::accelerationStructure set to pInfos[i].dstAccelerationStructure and AccelerationStructureMemoryRequirementsInfoKHR::type set to ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_BUILD_SCRATCH_KHR
• If update is TRUE, all addresses between pInfos[i].scratchData and pInfos[i].scratchData + N
• 1 must be in the buffer device address range of the same buffer, where N is given by the size member of the MemoryRequirements structure returned from a call to getAccelerationStructureMemoryRequirementsKHR with AccelerationStructureMemoryRequirementsInfoKHR::accelerationStructure set to pInfos[i].dstAccelerationStructure and AccelerationStructureMemoryRequirementsInfoKHR::type set to ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_UPDATE_SCRATCH_KHR
• The buffer from which the buffer device address pInfos[i].scratchData is queried must have been created with BUFFER_USAGE_RAY_TRACING_BIT_KHR usage flag
• All DeviceOrHostAddressKHR or DeviceOrHostAddressConstKHR referenced by this command must contain valid device addresses for a buffer bound to device memory. If the buffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object
• All AccelerationStructureKHR objects referenced by this command must be bound to device memory
• The DeferredOperationInfoKHR structure must not be included in the pNext chain of any of the provided AccelerationStructureBuildGeometryInfoKHR structures

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pInfos must be a valid pointer to an array of infoCount valid AccelerationStructureBuildGeometryInfoKHR structures
• ppOffsetInfos must be a valid pointer to an array of infoCount AccelerationStructureBuildOffsetInfoKHR structures
• 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
• infoCount must be greater than 0

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

AccelerationStructureBuildGeometryInfoKHR, AccelerationStructureBuildOffsetInfoKHR, CommandBuffer

vkCmdBuildAccelerationStructureIndirectKHR - Build an acceleration structure with some parameters provided on the device

Valid Usage

• All DeviceOrHostAddressKHR or DeviceOrHostAddressConstKHR referenced by this command must contain valid device addresses for a buffer bound to device memory. If the buffer is non-sparse then it must be bound completely and contiguously to a single VkDeviceMemory object

• All AccelerationStructureKHR objects referenced by this command must be bound to device memory
• The ::rayTracingIndirectAccelerationStructureBuild feature must be enabled
• The DeferredOperationInfoKHR structure must not be included in the pNext chain of any of the provided AccelerationStructureBuildGeometryInfoKHR structures

Valid Usage (Implicit)

• commandBuffer must be a valid CommandBuffer handle

• pInfo must be a valid pointer to a valid AccelerationStructureBuildGeometryInfoKHR structure
• indirectBuffer must be a valid Buffer 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
• Both of commandBuffer, and indirectBuffer must have been created, allocated, or retrieved from the same Device

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

AccelerationStructureBuildGeometryInfoKHR, Buffer, CommandBuffer, DeviceSize

vkBuildAccelerationStructureKHR - Build an acceleration structure on the host

Parameters

This command fulfills the same task as cmdBuildAccelerationStructureKHR but executed by the host.

Description

• device is the Device for which the acceleration structures are being built.

• infoCount is the number of acceleration structures to build. It specifies the number of the pInfos structures and ppOffsetInfos pointers that must be provided.
• pInfos is a pointer to an array of infoCount AccelerationStructureBuildGeometryInfoKHR structures defining the geometry used to build each acceleration structure.
• ppOffsetInfos is an array of infoCount pointers to arrays of AccelerationStructureBuildOffsetInfoKHR structures. Each ppOffsetInfos[i] is an array of pInfos[i].geometryCount AccelerationStructureBuildOffsetInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored, as defined by pInfos[i].

The buildAccelerationStructureKHR command provides the ability to initiate multiple acceleration structures builds, however there is no ordering or synchronization implied between any of the individual acceleration structure builds.

Note

This means that an application cannot build a top-level acceleration structure in the same buildAccelerationStructureKHR call as the associated bottom-level or instance acceleration structures are being built. There also cannot be any memory aliasing between any acceleration structure memories or scratch memories being used by any of the builds.

If the DeferredOperationInfoKHR structure is included in the pNext chain of any AccelerationStructureBuildGeometryInfoKHR structure, the operation of this command is deferred, as defined in the Deferred Host Operations chapter.

Valid Usage

• Each element of ppOffsetInfos[i] must be a valid pointer to an array of pInfos[i].geometryCount AccelerationStructureBuildOffsetInfoKHR structures

• Each pInfos[i].srcAccelerationStructure must not refer to the same acceleration structure as any pInfos[i].dstAccelerationStructure that is provided to the same build command unless it is identical for an update
• For each pInfos[i], dstAccelerationStructure must have been created with compatible AccelerationStructureCreateInfoKHR where AccelerationStructureCreateInfoKHR::type and AccelerationStructureCreateInfoKHR::flags are identical to AccelerationStructureBuildGeometryInfoKHR::type and AccelerationStructureBuildGeometryInfoKHR::flags respectively, AccelerationStructureBuildGeometryInfoKHR::geometryCount for dstAccelerationStructure are greater than or equal to the build size, and each geometry in AccelerationStructureBuildGeometryInfoKHR::ppGeometries for dstAccelerationStructure has greater than or equal to the number of vertices, indices, and AABBs, AccelerationStructureGeometryTrianglesDataKHR::transformData is both 0 or both non-zero, and all other parameters are the same
• For each pInfos[i], if update is TRUE, then objects that were previously active for that acceleration structure must not be made inactive as per ???
• For each pInfos[i], if update is TRUE, then objects that were previously inactive for that acceleration structure must not be made active as per ???
• Any acceleration structure instance in any top level build in this command must not reference any bottom level acceleration structure built by this command
• There must not be any memory aliasing between the scratch memories that are provided in all the pInfos[i].scratchData memories for the acceleration structure builds
• There must not be any memory aliasing between memory bound to any top level, bottom level, or instance acceleration structure accessed by this command
• All DeviceOrHostAddressKHR or DeviceOrHostAddressConstKHR referenced by this command must contain valid host addresses
• All AccelerationStructureKHR objects referenced by this command must be bound to host-visible memory
• The ::rayTracingHostAccelerationStructureCommands feature must be enabled

Valid Usage (Implicit)

• device must be a valid Device handle

• pInfos must be a valid pointer to an array of infoCount valid AccelerationStructureBuildGeometryInfoKHR structures
• ppOffsetInfos must be a valid pointer to an array of infoCount AccelerationStructureBuildOffsetInfoKHR structures
• infoCount must be greater than 0

Return Codes

Success

• SUCCESS
• OPERATION_DEFERRED_KHR
• OPERATION_NOT_DEFERRED_KHR

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY

See Also

AccelerationStructureBuildGeometryInfoKHR, AccelerationStructureBuildOffsetInfoKHR, Device

vkGetAccelerationStructureDeviceAddressKHR - Query an address of a acceleration structure

Description

The 64-bit return value is an address of the acceleration structure, which can be used for device and shader operations that involve acceleration structures, such as ray traversal and acceleration structure building.

If the acceleration structure was created with a non-zero value of AccelerationStructureCreateInfoKHR::deviceAddress the return value will be the same address.

Valid Usage

• If device was created with multiple physical devices, then the bufferDeviceAddressMultiDevice feature must be enabled

Valid Usage (Implicit)

• device must be a valid Device handle

• pInfo must be a valid pointer to a valid AccelerationStructureDeviceAddressInfoKHR structure

See Also

AccelerationStructureDeviceAddressInfoKHR, Device

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 PhysicalDeviceRayTracingFeaturesKHR::rayTracingShaderGroupHandleCaptureReplayMixed is FALSE then pShaderGroupCaptureReplayHandle must not be provided if it has not been provided on a previous call to ray tracing pipeline creation
• If PhysicalDeviceRayTracingFeaturesKHR::rayTracingShaderGroupHandleCaptureReplayMixed 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 libraries, 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.

If the DeferredOperationInfoKHR structure is included in the pNext chain of RayTracingPipelineCreateInfoKHR, the operation of this pipeline creation is deferred, as defined in the Deferred Host Operations chapter.

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 stage member of at least one element of pStages must be SHADER_STAGE_RAYGEN_BIT_KHR
• 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
• maxRecursionDepth must be less than or equal to PhysicalDeviceRayTracingPropertiesKHR::maxRecursionDepth
• If flags includes PIPELINE_CREATE_LIBRARY_BIT_KHR, pLibraryInterface must not be NULL
• If the libraryCount member of libraries is greater than 0, pLibraryInterface must not be NULL
• Each element of the pLibraries member of libraries must have been created with the value of maxRecursionDepth equal to that in this pipeline
• Each element of the pLibraries member of libraries must have been created with a layout that is compatible with the layout in this pipeline
• Each element of the pLibraries member of libraries must have been created with values of the maxPayloadSize, maxAttributeSize, and maxCallableSize members of pLibraryInterface equal to those in this pipeline
• 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 rayTracingPrimitiveCulling feature is not enabled, flags must not include PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR
• If the rayTracingPrimitiveCulling feature is not enabled, flags must not include PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR
• If libraries.libraryCount is zero, then stageCount must not be zero
• If libraries.libraryCount is zero, then groupCount must not be zero

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_RAY_TRACING_PIPELINE_CREATE_INFO_KHR

• Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of DeferredOperationInfoKHR or 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
• libraries must be a valid PipelineLibraryCreateInfoKHR structure
• If pLibraryInterface is not NULL, pLibraryInterface must be a valid pointer to a valid RayTracingPipelineInterfaceCreateInfoKHR 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, PipelineLayout, PipelineLibraryCreateInfoKHR, PipelineShaderStageCreateInfo, RayTracingPipelineInterfaceCreateInfoKHR, RayTracingShaderGroupCreateInfoKHR, StructureType, createRayTracingPipelinesKHR

VkBindAccelerationStructureMemoryInfoKHR - Structure specifying acceleration structure memory binding

Valid Usage

• accelerationStructure must not already be backed by a memory object

• memoryOffset must be less than the size of memory
• memory must have been allocated using one of the memory types allowed in the memoryTypeBits member of the MemoryRequirements structure returned from a call to getAccelerationStructureMemoryRequirementsKHR with accelerationStructure and type of ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_KHR
• memoryOffset must be an integer multiple of the alignment member of the MemoryRequirements structure returned from a call to getAccelerationStructureMemoryRequirementsKHR with accelerationStructure and type of ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_KHR
• The size member of the MemoryRequirements structure returned from a call to getAccelerationStructureMemoryRequirementsKHR with accelerationStructure and type of ACCELERATION_STRUCTURE_MEMORY_REQUIREMENTS_TYPE_OBJECT_KHR must be less than or equal to the size of memory minus memoryOffset

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_BIND_ACCELERATION_STRUCTURE_MEMORY_INFO_KHR

• pNext must be NULL
• accelerationStructure must be a valid AccelerationStructureKHR handle
• memory must be a valid DeviceMemory handle
• If deviceIndexCount is not 0, pDeviceIndices must be a valid pointer to an array of deviceIndexCount uint32_t values
• Both of accelerationStructure, and memory must have been created, allocated, or retrieved from the same Device

See Also

AccelerationStructureKHR, DeviceMemory, DeviceSize, StructureType, bindAccelerationStructureMemoryKHR, bindAccelerationStructureMemoryNV

VkWriteDescriptorSetAccelerationStructureKHR - Structure specifying acceleration structure descriptor info

Valid Usage

• accelerationStructureCount must be equal to descriptorCount in the extended structure

• Each acceleration structure in pAccelerationStructures must have been created with ACCELERATION_STRUCTURE_TYPE_TOP_LEVEL_KHR

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET_ACCELERATION_STRUCTURE_KHR

• pAccelerationStructures must be a valid pointer to an array of accelerationStructureCount valid AccelerationStructureKHR handles
• accelerationStructureCount must be greater than 0

See Also

AccelerationStructureKHR, StructureType

VkAccelerationStructureMemoryRequirementsInfoKHR - Structure specifying acceleration to query for memory requirements

Valid Usage (Implicit)

See Also

AccelerationStructureBuildTypeKHR, AccelerationStructureKHR, AccelerationStructureMemoryRequirementsTypeKHR, StructureType, getAccelerationStructureMemoryRequirementsKHR

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

Members

The members of the PhysicalDeviceRayTracingFeaturesKHR structure describe the following features:

Description

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

• rayTracingShaderGroupHandleCaptureReplay indicates whether the implementation supports saving and reusing shader group handles, e.g. for trace capture and replay.
• rayTracingShaderGroupHandleCaptureReplayMixed 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.
• rayTracingAccelerationStructureCaptureReplay indicates whether the implementation supports saving and reusing acceleration structure device addresses, e.g. for trace capture and replay.
• rayTracingIndirectTraceRays indicates whether the implementation supports indirect trace ray commands, e.g. cmdTraceRaysIndirectKHR.
• rayTracingIndirectAccelerationStructureBuild indicates whether the implementation supports indirect acceleration structure build commands, e.g. cmdBuildAccelerationStructureIndirectKHR.
• rayTracingHostAccelerationStructureCommands indicates whether the implementation supports host side acceleration structure commands, e.g. buildAccelerationStructureKHR, copyAccelerationStructureKHR, copyAccelerationStructureToMemoryKHR, copyMemoryToAccelerationStructureKHR, writeAccelerationStructuresPropertiesKHR.
• rayQuery indicates whether the implementation supports ray query (OpRayQueryProceedKHR) functionality.
• rayTracingPrimitiveCulling indicates whether the implementation supports primitive culling during ray traversal.

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

Valid Usage

• If rayTracingShaderGroupHandleCaptureReplayMixed is TRUE, rayTracingShaderGroupHandleCaptureReplay must also be TRUE

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_PHYSICAL_DEVICE_RAY_TRACING_FEATURES_KHR

See Also

Bool32, StructureType

VkPhysicalDeviceRayTracingPropertiesKHR - Properties of the physical device for ray tracing

Description

If the PhysicalDeviceRayTracingPropertiesKHR 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