VKGETQUERYPOOLRESULT(3)

NAME
vkGetQueryPoolResults - Copy results of queries in a query pool to a host memory region.

C SPECIFICATION

    VkResult vkGetQueryPoolResults(
        VkDevice                                    device,
        VkQueryPool                                 queryPool,
        uint32_t                                    firstQuery,
        uint32_t                                    queryCount,
        size_t                                      dataSize,
        void*                                       pData,
        VkDeviceSize                                stride,
        VkQueryResultFlags                          flags);

PARAMETERS

device
    Logical device owning the query pool.

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.

dataSize
    The size of the data area pointed to by pData.

pData
    A pointer to a buffer that will be filled with query results.

stride
    The stride, in bytes between the start of each query object in memory.

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

DESCRIPTION

vkGetQueryPoolResults 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 host memory buffer specified by pData. dataSize contains the size of the output buffer. If pData is not NULL, then the output buffer size must be large enough to hold the query results. 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

    • device must be a valid VkDevice handle

    • queryPool must be a valid VkQueryPool handle

    • pData must be a pointer to an array of dataSize bytes

    • flags must be a valid combination of VkQueryResultFlagBits values

    • dataSize must be greater than 0

    • queryPool must have been created, allocated or retrieved from device

    • Each of device and queryPool must have been created, allocated or retrieved from the same VkPhysicalDevice

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

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

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

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

    • dataSize must be large enough to contain the result of each query, as described here

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

RETURN CODES

On success, this command returns

        • VK_SUCCESS

        • VK_NOT_READY

On failure, this command returns

        • VK_ERROR_OUT_OF_HOST_MEMORY

        • VK_ERROR_OUT_OF_DEVICE_MEMORY

        • VK_ERROR_DEVICE_LOST

RETURN VALUE

Upon success, vkGetQueryPoolResults returns VK_SUCCESS and query results are deposited in the buffer pointed to by pData. If only some of the results are available, vkGetQueryPoolResults returns VK_NOT_READY; in this case, if flags contains VK_QUERY_RESULT_PARTIAL_BIT, partial results are deposited in the buffer pointed to by pData. Upon failure, a descriptive error code is returned.

SEE ALSO

vkCmdCopyQueryPoolResults, VkQueryResultFlags, vkCmdBeginQuery, VkQueryControlFlags

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.