# vkCmdWriteAccelerationStructuresPropertiesKHR(3) Manual Page

## Name

vkCmdWriteAccelerationStructuresPropertiesKHR - Write acceleration structure result parameters to query results.

Loading… please wait.

## C Specification

To query acceleration structure size parameters call:

    // Provided by VK_KHR_acceleration_structure
    void vkCmdWriteAccelerationStructuresPropertiesKHR(
        VkCommandBuffer                             commandBuffer,
        uint32_t                                    accelerationStructureCount,
        const VkAccelerationStructureKHR*           pAccelerationStructures,
        VkQueryType                                 queryType,
        VkQueryPool                                 queryPool,
        uint32_t                                    firstQuery);

## Parameters

- `commandBuffer` is the command buffer into which the command will be recorded.

- `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 type of queries managed by the pool.

- `queryPool` is the query pool that will manage the results of the query.

- `firstQuery` is the first query index within the query pool that will contain the `accelerationStructureCount` number of results.

## Description

Accesses to any of the acceleration structures listed in `pAccelerationStructures` must be synchronized with the `VK_PIPELINE_STAGE_2_ACCELERATION_STRUCTURE_COPY_BIT_KHR` pipeline stage or the `VK_PIPELINE_STAGE_ACCELERATION_STRUCTURE_BUILD_BIT_KHR` pipeline stage, and an access type of `VK_ACCESS_ACCELERATION_STRUCTURE_READ_BIT_KHR`.

- If `queryType` is `VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR`, then the value written out is the number of bytes required by a compacted acceleration structure.

- If `queryType` is `VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR`, then the value written out is the number of bytes required by a serialized acceleration structure.

Valid Usage

- VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-accelerationStructure-08924
  The `VkPhysicalDeviceAccelerationStructureFeaturesKHR`::`accelerationStructure` feature must be enabled

- VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-queryPool-02493
  `queryPool` must have been created with a `queryType` matching `queryType`

- VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-queryPool-02494
  The queries identified by `queryPool` and `firstQuery` must be unavailable

- VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-buffer-03736
  The `buffer` used to create each acceleration structure in `pAccelerationStructures` must be bound to device memory

- VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-query-04880
  The sum of `firstQuery` plus `accelerationStructureCount` must be less than or equal to the number of queries in `queryPool`

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

- VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-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-vkCmdWriteAccelerationStructuresPropertiesKHR-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`

Valid Usage (Implicit)

- VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-commandBuffer-parameter
  `commandBuffer` must be a valid VkCommandBuffer handle

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

- VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-queryType-parameter
  `queryType` must be a valid VkQueryType value

- VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-queryPool-parameter
  `queryPool` must be a valid VkQueryPool handle

- VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-commandBuffer-recording
  `commandBuffer` must be in the recording state

- VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-commandBuffer-cmdpool
  The `VkCommandPool` that `commandBuffer` was allocated from must support compute operations

- VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-renderpass
  This command must only be called outside of a render pass instance

- VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-videocoding
  This command must only be called outside of a video coding scope

- VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-accelerationStructureCount-arraylength
  `accelerationStructureCount` must be greater than `0`

- VUID-vkCmdWriteAccelerationStructuresPropertiesKHR-commonparent
  Each of `commandBuffer`, `queryPool`, and the elements of `pAccelerationStructures` must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

- Host access to `commandBuffer` must be externally synchronized

- Host access to the `VkCommandPool` that `commandBuffer` was allocated from must be externally synchronized

Command Properties

Command Buffer Levels | Render Pass Scope | Video Coding Scope | Supported Queue Types | Command Type
--- | --- | --- | --- | ---
Primary Secondary | Outside | Outside | Compute | Action

## See Also

VK_KHR_acceleration_structure, VkAccelerationStructureKHR, VkCommandBuffer, VkQueryPool, 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