mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-12 15:04:10 +00:00
1ca0ea1ef0
* Bump API patch number and header version number to 22 for this update.
Github Issues:
* Translate the subpass self-dependency language into concrete
validity statements, and added a validity statement about the
restrictions on layout parameters (public issue 267).
* Add validity requirement that
slink:VkAttachmentDescription::pname:finalLayout and
slink:VkAttachmentReference::pname:layout must not be
ename:VK_IMAGE_LAYOUT_UNDEFINED or
ename:VK_IMAGE_LAYOUT_PREINITIALIZED (public issue 268).
* Clarify that slink:VkSubpassDescription::pname:pResolveAttachments
layouts are used. Make language consistent with other attachment
arrays (public issue 270).
* Changed 64-bit definition for
dname:VK_DEFINE_NON_DISPATCHABLE_HANDLE to work for x32 platform in
+vk.xml+ and the resulting +vulkan.h+ (public issue 282).
* Add missing error return code for
flink:vkEnumerateInstanceExtensionProperties and
flink:vkEnumerateDeviceExtensionProperties (public issue 285)
* Fix several cases of stext::VkStructName.memberName markup to
stext::VkStructName::pname:memberName, to match other usage in the
spec, and describe this markup in the style guide (public issue
286).
* Modified validity language generation script to avoid redundant
common ancestor language if covered by generic parent language, and
used `Both' instead of `Each' when appropriate (public issue 288).
Internal Issues:
* Add language about behavior of flink:vkAllocateDescriptorSets when
allocation fails due to fragmentation, a new error
ename:VK_ERROR_FRAGMENTED_POOL, and a Note explaining the situation
(internal issue 309).
* For the features of code:PointSize, code:ClipDistance, and
code:CullDistance, the SPIR-V capability is required to be declared
on use (read or write) rather than on decoration (internal issue
359).
* Have desktop versions of GLSL respect precision qualification
(code:mediump and code:lowp) when compiling for Vulkan. These will
get translated to SPIR-V's code:RelaxedPrecision decoration as they
do with OpenGL ES versions of GLSL (ESSL). The default precision of
all types is code:highp when using a desktop version (internal issue
360).
* Add validity statement for slink:VkImageCreateInfo specifying that
multisampled images must be two-dimensional, optimally tiled, and
with a single mipmap level (internal issue 369).
* Add validity statements to slink:VkImageViewCreateInfo disallowing
creation of images or image views with no supported features. Made
some slink:VkImageViewCreateInfo validity statements more precise
and consistent. Added a Note to the <<features,features>> chapter
about formats with no features (internal issue 371).
* Remove +manpages+ from default build targets. Nroff outputs
containing imbedded latexmath will not render properly. Fixing this
is a lot of work for limited use cases (internal issue 401).
Other Commits:
* Fix flink:vkRenderPassBeginInfo::pname:clearValueCount validity
statement to be based on attachment indices rather than the number
of cleared attachments
(Vulkan-LoaderAndValidationLayers/issues/601).
* Convert registry documentation from LaTeX to asciidoc source and
rename from +src/spec/readme.tex+ to +src/spec/registry.txt+.
* Fix lack of Oxford commas in validity language.
* Lots of cleanup of generator scripts and Makefiles to move extension
list for generator into the script arguments instead of the body of
genvk.py, and express better dependencies between XML, scripts, and
generated files.
159 lines
6.0 KiB
Plaintext
159 lines
6.0 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/
|
|
|
|
vkGetQueryPoolResults(3)
|
|
========================
|
|
|
|
Name
|
|
----
|
|
vkGetQueryPoolResults - Copy results of queries in a query pool to a host memory region.
|
|
|
|
C Specification
|
|
---------------
|
|
|
|
// refBegin vkGetQueryPoolResults Copy results of queries in a query pool to a host memory region.
|
|
|
|
To retrieve status and results for a set of queries, call:
|
|
|
|
include::../api/protos/vkGetQueryPoolResults.txt[]
|
|
|
|
|
|
Parameters
|
|
----------
|
|
|
|
* pname:device is the logical device that owns the query pool.
|
|
* 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:dataSize is the size in bytes of the buffer pointed to by
|
|
pname:pData.
|
|
* pname:pData is a pointer to a user-allocated buffer
|
|
where the results will be written
|
|
* pname:stride is the stride in bytes between results for individual
|
|
queries within pname:pData.
|
|
* pname:flags is a bitmask of elink:VkQueryResultFlagBits specifying how
|
|
and when results are returned. Bits which can: be set include:
|
|
+
|
|
--
|
|
// refBegin VkQueryResultFlagBits - Bitmask specifying how and when query results are returned
|
|
include::../api/enums/VkQueryResultFlagBits.txt[]
|
|
--
|
|
+
|
|
** ename:VK_QUERY_RESULT_64_BIT indicates the results will be written as an
|
|
array of 64-bit unsigned integer values. If this bit is not set, the
|
|
results will be written as an array of 32-bit unsigned integer values.
|
|
** ename:VK_QUERY_RESULT_WAIT_BIT indicates that Vulkan will wait for
|
|
each query's status to become available before retrieving its results.
|
|
** ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT indicates that the
|
|
availability status accompanies the results.
|
|
** ename:VK_QUERY_RESULT_PARTIAL_BIT indicates that returning partial
|
|
results is acceptable.
|
|
|
|
|
|
Description
|
|
-----------
|
|
|
|
If no bits are set in pname:flags, and all requested queries are
|
|
in the available state, results are written as an array of
|
|
32-bit unsigned integer values. The behavior when not all queries
|
|
are available, is described <<queries-wait-bit-not-set, below>>.
|
|
|
|
If ename:VK_QUERY_RESULT_64_BIT is not set and the result overflows a
|
|
32-bit value, the value may: either wrap or saturate. Similarly, if
|
|
ename:VK_QUERY_RESULT_64_BIT is set and the result overflows a 64-bit
|
|
value, the value may: either wrap or saturate.
|
|
|
|
If ename:VK_QUERY_RESULT_WAIT_BIT is set, Vulkan will wait for each
|
|
query to be in the available state before retrieving the numerical
|
|
results for that query. In this case, fname:vkGetQueryPoolResults is
|
|
guaranteed to succeed and return ename:VK_SUCCESS if the queries
|
|
become available in a finite time (i.e. if they have been issued and not
|
|
reset). If queries will never finish (e.g. due to being reset but not
|
|
issued), then fname:vkGetQueryPoolResults may: not return in finite time.
|
|
|
|
[[queries-wait-bit-not-set]]
|
|
If ename:VK_QUERY_RESULT_WAIT_BIT and ename:VK_QUERY_RESULT_PARTIAL_BIT
|
|
are both not set then no result values are written to pname:pData for
|
|
queries that are in the unavailable state at the time of the call,
|
|
and fname:vkGetQueryPoolResults returns ename:VK_NOT_READY.
|
|
However, availability state is still written to pname:pData for those
|
|
queries if ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Applications must: take care to ensure that use of the
|
|
ename:VK_QUERY_RESULT_WAIT_BIT bit has the desired effect.
|
|
|
|
For example, if a query has been used previously and a command buffer
|
|
records the commands fname:vkCmdResetQueryPool, fname:vkCmdBeginQuery, and
|
|
fname:vkCmdEndQuery for that query, then the query will remain
|
|
in the available state until the fname:vkCmdResetQueryPool command
|
|
executes on a queue. Applications can: use fences or events to ensure that
|
|
an query has already been reset before checking for its results or
|
|
availability status. Otherwise, a stale value could be returned from a
|
|
previous use of the query.
|
|
|
|
The above also applies when ename:VK_QUERY_RESULT_WAIT_BIT is used in
|
|
combination with ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT. In this
|
|
case, the returned availability status may: reflect the result of a
|
|
previous use of the query unless the fname:vkCmdResetQueryPool command
|
|
has been executed since the last use of the query.
|
|
====
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Applications can: double-buffer query pool usage, with a pool per
|
|
frame, and reset queries at the end of the frame in which they
|
|
are read.
|
|
====
|
|
|
|
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 to
|
|
pname:pData for that query.
|
|
|
|
ename:VK_QUERY_RESULT_PARTIAL_BIT mustnot: be used if the pool's
|
|
pname:queryType is ename:VK_QUERY_TYPE_TIMESTAMP.
|
|
|
|
If ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set, the final integer
|
|
value written for each query is non-zero if the query's status was
|
|
available or zero if the status was unavailable. When
|
|
ename:VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is used, implementations must:
|
|
guarantee that if they return a non-zero availability value then the
|
|
numerical results must: be valid, assuming the results are not reset by a
|
|
subsequent command.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Satisfying this guarantee may: require careful ordering by the application,
|
|
e.g. to read the availability status before reading the results.
|
|
====
|
|
|
|
include::../validity/protos/vkGetQueryPoolResults.txt[]
|
|
|
|
|
|
See Also
|
|
--------
|
|
|
|
slink:VkDevice, 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#vkGetQueryPoolResults
|
|
|
|
This page is extracted from the Vulkan Specification.
|
|
Fixes and changes should be made to the Specification,not directly.
|
|
|
|
include::footer.txt[]
|
|
|