116 lines
4.4 KiB
Plaintext
116 lines
4.4 KiB
Plaintext
// 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::../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, basetypes: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[]
|
|
|