# vkWriteAccelerationStructuresPropertiesKHR(3) Manual Page

## Name

vkWriteAccelerationStructuresPropertiesKHR - Query acceleration structure meta-data on the host

Loading… please wait.

## 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-accelerationStructureHostCommands-03585
  The `VkPhysicalDeviceAccelerationStructureFeaturesKHR`::`accelerationStructureHostCommands` feature must be enabled

- 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

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

## Copyright

Copyright 2014-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0