vkWriteAccelerationStructuresPropertiesKHR(3)

Name

vkWriteAccelerationStructuresPropertiesKHR - Query acceleration structure meta-data on the host

C Specification

To query acceleration structure size parameters on the host, call:

// Provided by VK_KHR_acceleration_structure
VkResult vkWriteAccelerationStructuresPropertiesKHR(
    VkDevice                                    device,
    uint32_t                                    accelerationStructureCount,
    const VkAccelerationStructureKHR*           pAccelerationStructures,
    VkQueryType                                 queryType,
    size_t                                      dataSize,
    void*                                       pData,
    size_t                                      stride);

Parameters

  • 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 is a pointer to an array of existing previously built acceleration structures.

  • queryType is a VkQueryType 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 an application-allocated buffer where the results will be written.

  • stride is the stride in bytes between results for individual queries within pData.

Description

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

Valid Usage

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-pAccelerationStructures-04964
    All acceleration structures in pAccelerationStructures must have been built prior to the execution of this command

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-accelerationStructures-03431
    All acceleration structures in pAccelerationStructures must have been built with VK_BUILD_ACCELERATION_STRUCTURE_ALLOW_COMPACTION_BIT_KHR if queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-06742
    queryType must be VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHR, VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR, VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, or VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03448
    If queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then stride must be a multiple of the size of VkDeviceSize

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03449
    If queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR, then pData must point to a VkDeviceSize

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03450
    If queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then stride must be a multiple of the size of VkDeviceSize

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-03451
    If queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR, then pData must point to a VkDeviceSize

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-06731
    If queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHR, then stride must be a multiple of the size of VkDeviceSize

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-06732
    If queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHR, then pData must point to a VkDeviceSize

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-06733
    If queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR, then stride must be a multiple of the size of VkDeviceSize

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-06734
    If queryType is VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR, then pData must point to a VkDeviceSize

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-dataSize-03452
    dataSize must be greater than or equal to accelerationStructureCount*stride

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-buffer-03733
    The buffer used to create each acceleration structure in pAccelerationStructures must be bound to host-visible device memory

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-buffer-03784
    The buffer used to create each acceleration structure in pAccelerationStructures must be bound to memory that was not allocated with multiple instances

Valid Usage (Implicit)

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

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-pAccelerationStructures-parameter
    pAccelerationStructures must be a valid pointer to an array of accelerationStructureCount valid VkAccelerationStructureKHR handles

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-queryType-parameter
    queryType must be a valid VkQueryType value

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

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-accelerationStructureCount-arraylength
    accelerationStructureCount must be greater than 0

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

  • VUID-vkWriteAccelerationStructuresPropertiesKHR-pAccelerationStructures-parent
    Each element of pAccelerationStructures must have been created, allocated, or retrieved from device

Return Codes
Success

  • VK_SUCCESS

Failure

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_UNKNOWN

  • VK_ERROR_VALIDATION_FAILED

See Also

VK_KHR_acceleration_structure, VkAccelerationStructureKHR, VkDevice, VkQueryType

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.