VKCMDCOPYQUERYPOOLRE(3)

NAME
vkCmdCopyQueryPoolResults - Copy the results of queries in a query pool to a buffer object.

C SPECIFICATION

    void vkCmdCopyQueryPoolResults(
        VkCommandBuffer                             commandBuffer,
        VkQueryPool                                 queryPool,
        uint32_t                                    firstQuery,
        uint32_t                                    queryCount,
        VkBuffer                                    dstBuffer,
        VkDeviceSize                                dstOffset,
        VkDeviceSize                                stride,
        VkQueryResultFlags                          flags);

PARAMETERS

commandBuffer
    The command buffer into which the command is to be placed.

queryPool
    The query pool whose results should be copied to the buffer object.

startQuery
    The index of the first query in the query pool whose results should be copied to the buffer object.

queryCount
    The number of queries in the query pool whose results should be copied to the buffer object.

dstBuffer
    The buffer object the results should be written to.

dstOffset
    The offset within the buffer object the results should be written to.

stride
    The stride between subsequent query result writes.

flags
    The flags controlling the behavior of the query result copy command (see VkQueryResultFlags).

DESCRIPTION

vkCmdCopyQueryPoolResults copies the results of queryCount number of queries in the query pool specified by queryPool starting from index startQuery. The results are written to the buffer object specified by dstBuffer starting from dstOffset with each subsequent query’s result being written stride number of bytes after the previous one. The semantics of when and what values written to the destination buffer are defined by the type of the queries in the query pool, the query control flags passed to vkCmdBeginQuery, and the query result control flags specified by flags.

VALID USAGE

    • commandBuffer must be a valid VkCommandBuffer handle

    • queryPool must be a valid VkQueryPool handle

    • dstBuffer must be a valid VkBuffer handle

    • flags must be a valid combination of VkQueryResultFlagBits values

    • commandBuffer must be in the recording state

    • The VkCommandPool that commandBuffer was allocated from must support graphics or compute operations

    • This command must only be called outside of a render pass instance

    • Each of commandBuffer, queryPool and dstBuffer must have been created, allocated or retrieved from the same VkDevice

    • dstOffset must be less than the size of dstBuffer

    • firstQuery must be less than the number of queries in queryPool

    • The sum of firstQuery and queryCount must be less than or equal to the number of queries in queryPool

    • If VK_QUERY_RESULT_64_BIT is not set in flags then dstOffset and stride must be multiples of 4

    • If VK_QUERY_RESULT_64_BIT is set in flags then dstOffset and stride must be multiples of 8

    • dstBuffer must have enough storage, from dstOffset, to contain the result of each query, as described here

    • dstBuffer must have been created with VK_BUFFER_USAGE_TRANSFER_DST_BIT usage flag

    • If the queryType used to create queryPool was VK_QUERY_TYPE_TIMESTAMP, flags must not contain VK_QUERY_RESULT_PARTIAL_BIT

HOST SYNCHRONIZATION

    • Host access to commandBuffer must be externally synchronized

COMMAND PROPERTIES
Command Buffer Levels | Render Pass Scope | Supported Queue Types
Primary Secondary | Outside | GRAPHICS COMPUTE

NOTES

Although vkCmdCopyQueryPoolResults does not generate errors or return a value, enabled validation layers may detect possible error conditions or potentially undefined behavior and report this via some other means.

SEE ALSO

vkGetQueryPoolResults, vkCmdBeginQuery, vkCmdEndQuery, vkCmdResetQueryPool, vkDestroyQueryPool, vkCreateQueryPool

COPYRIGHT

Copyright © 2014-2016 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.

AUTHOR

Khronos Group
    Author.