C Specification

To allow constructing geometry instances with device code if desired, we need to be able to query a opaque handle for an acceleration structure. This handle is a value of 8 bytes. To get this handle, call:

// Provided by VK_NV_ray_tracing
VkResult vkGetAccelerationStructureHandleNV(
    VkDevice                                    device,
    VkAccelerationStructureNV                   accelerationStructure,
    size_t                                      dataSize,
    void*                                       pData);

Parameters

  • device is the logical device that owns the acceleration structures.

  • accelerationStructure is the acceleration structure.

  • 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.

Description

Valid Usage

  • VUID-vkGetAccelerationStructureHandleNV-dataSize-02240
    dataSize must be large enough to contain the result of the query, as described above

  • VUID-vkGetAccelerationStructureHandleNV-accelerationStructure-02787
    accelerationStructure must be bound completely and contiguously to a single VkDeviceMemory object via vkBindAccelerationStructureMemoryNV

Valid Usage (Implicit)

  • VUID-vkGetAccelerationStructureHandleNV-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkGetAccelerationStructureHandleNV-accelerationStructure-parameter
    accelerationStructure must be a valid VkAccelerationStructureNV handle

  • VUID-vkGetAccelerationStructureHandleNV-pData-parameter
    pData must be a valid pointer to an array of dataSize bytes

  • VUID-vkGetAccelerationStructureHandleNV-dataSize-arraylength
    dataSize must be greater than 0

  • VUID-vkGetAccelerationStructureHandleNV-accelerationStructure-parent
    accelerationStructure must have been created, allocated, or retrieved from device

Return Codes
On success, this command returns

  • VK_SUCCESS

On failure, this command returns

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

See Also

VK_NV_ray_tracing, VkAccelerationStructureNV, VkDevice

Document Notes

For more information, see the Vulkan Specification

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0