// Copyright (c) 2014-2016 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

vkCmdCopyQueryPoolResults(3)
============================

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

C Specification
---------------

// refBegin vkCmdCopyQueryPoolResults Copy the results of queries in a query pool to a buffer object.

To copy query statuses and numerical results directly to buffer memory,
call:

include::../api/protos/vkCmdCopyQueryPoolResults.txt[]


Parameters
----------

  * pname:commandBuffer is the command buffer into which this command will
    be recorded.
  * pname:queryPool is the query pool managing the queries containing the
    desired results.
  * pname:firstQuery is the initial query index.
  * pname:queryCount is the number of queries. pname:firstQuery and
    pname:queryCount together define a range of queries.
  * pname:dstBuffer is a sname:VkBuffer object that will receive the results
    of the copy command.
  * pname:dstOffset is an offset into pname:dstBuffer.
  * pname:stride is the stride in bytes between results for individual
    queries within pname:dstBuffer. The required size of the backing memory
    for pname:dstBuffer is determined as described above for
    flink:vkGetQueryPoolResults.
  * pname:flags is a bitmask of elink:VkQueryResultFlagBits specifying how
    and when results are returned.


Description
-----------

fname:vkCmdCopyQueryPoolResults is guaranteed to see the effect of previous
uses of fname:vkCmdResetQueryPool in the same queue, without any additional
synchronization. Thus, the results will always reflect the most
recent use of the query.

pname:flags has the same possible values described above for the pname:flags
parameter of flink:vkGetQueryPoolResults, but the different style of
execution causes some subtle behavioral differences. Because
fname:vkCmdCopyQueryPoolResults executes in order with respect to other
query commands, there is less ambiguity about which use of a query is being
requested.

If no bits are set in pname:flags, results for all requested queries in the
available state are written as 32-bit unsigned integer values, and nothing
is written for queries in the unavailable state.

If ename:VK_QUERY_RESULT_64_BIT is set, the results are written as an array
of 64-bit unsigned integer values as described for
flink:vkGetQueryPoolResults.

If ename:VK_QUERY_RESULT_WAIT_BIT is set, the implementation will wait for
each query's status to be in the available state before retrieving the
numerical results for that query. This is guaranteed to reflect the most
recent use of the query on the same queue, assuming that the query is
not being simultaneously used by other queues. If the query does not become
available in a finite amount of time (e.g. due to not issuing a query
since the last reset), a ename:VK_ERROR_DEVICE_LOST error may: occur.

Similarly, if ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set and
ename:VK_QUERY_RESULT_WAIT_BIT is not set, the availability is guaranteed to
reflect the most recent use of the query on the same queue, assuming
that the query is not being simultaneously used by other queues. As with
fname:vkGetQueryPoolResults, implementations must: guarantee that if they
return a non-zero availability value, then the numerical results are valid.

If ename:VK_QUERY_RESULT_PARTIAL_BIT is set, ename:VK_QUERY_RESULT_WAIT_BIT
is not set, and the query's status is unavailable, an intermediate
result value between zero and the final result value is written for that
query.

ename:VK_QUERY_RESULT_PARTIAL_BIT mustnot: be used if the pool's
pname:queryType is ename:VK_QUERY_TYPE_TIMESTAMP.

fname:vkCmdCopyQueryPoolResults is considered to be a transfer operation,
and its writes to buffer memory must: be synchronized using
ename:VK_PIPELINE_STAGE_TRANSFER_BIT and
ename:VK_ACCESS_TRANSFER_WRITE_BIT before using the results.

include::../validity/protos/vkCmdCopyQueryPoolResults.txt[]


See Also
--------

slink:VkBuffer, slink:VkCommandBuffer, basetype:VkDeviceSize, slink:VkQueryPool, elink:VkQueryResultFlags


Document Notes
--------------

For more information, see the Vulkan Specification at URL

https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#vkCmdCopyQueryPoolResults

This page is extracted from the Vulkan Specification.
Fixes and changes should be made to the Specification,not directly.

include::footer.txt[]