366 lines
14 KiB
Plaintext
366 lines
14 KiB
Plaintext
ifdef::VK_INTEL_performance_query[]
|
|
|
|
[[queries-performance-intel]]
|
|
== Intel performance queries
|
|
|
|
Intel performance queries allow an application to capture performance data
|
|
for a set of commands.
|
|
Performance queries are used in a similar way than other types of queries.
|
|
A main difference with existing queries is that the resulting data should be
|
|
handed over to a library capabable to produce human readable results rather
|
|
than being read directly by an application.
|
|
|
|
[open,refpage='vkInitializePerformanceApiINTEL',desc='Initialize a device for performance queries',type='protos']
|
|
--
|
|
Prior to creating a performance query pool, initialize the device for
|
|
performance queries with the call:
|
|
|
|
include::{generated}/api/protos/vkInitializePerformanceApiINTEL.txt[]
|
|
|
|
* pname:device is the logical device used for the queries.
|
|
* pname:pInitializeInfo is a pointer to the initialization parameters.
|
|
|
|
include::{generated}/validity/protos/vkInitializePerformanceApiINTEL.txt[]
|
|
--
|
|
|
|
[open,refpage='VkInitializePerformanceApiInfoINTEL',desc='Structure specifying parameters of initialize of the device',type='structs']
|
|
--
|
|
The sname:VkInitializePerformanceApiInfoINTEL structure is defined as :
|
|
|
|
include::{generated}/api/structs/VkInitializePerformanceApiInfoINTEL.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:pUserData is a pointer for application data.
|
|
|
|
include::{generated}/validity/structs/VkInitializePerformanceApiInfoINTEL.txt[]
|
|
--
|
|
|
|
[open,refpage='vkUninitializePerformanceApiINTEL',desc='Uninitialize a device for performance queries',type='protos']
|
|
--
|
|
Once performance query operations have completed, uninitalize the device for
|
|
performance queries with the call:
|
|
|
|
include::{generated}/api/protos/vkUninitializePerformanceApiINTEL.txt[]
|
|
|
|
* pname:device is the logical device used for the queries.
|
|
|
|
include::{generated}/validity/protos/vkUninitializePerformanceApiINTEL.txt[]
|
|
--
|
|
|
|
[open,refpage='vkGetPerformanceParameterINTEL',desc='Query performance capabilities of the device',type='protos']
|
|
--
|
|
Some performance query features of a device can be discovered with the call:
|
|
|
|
include::{generated}/api/protos/vkGetPerformanceParameterINTEL.txt[]
|
|
|
|
* pname:device is the logical device to query.
|
|
* pname:parameter is the parameter to query.
|
|
* pname:pValue points to an instance of the slink:VkPerformanceValueINTEL
|
|
structure in which the type and value of the parameter are returned.
|
|
|
|
include::{generated}/validity/protos/vkGetPerformanceParameterINTEL.txt[]
|
|
--
|
|
|
|
[open,refpage='VkPerformanceParameterTypeINTEL',desc='Parameters that can be queried',type='enums']
|
|
--
|
|
Possible values of flink:vkGetPerformanceParameterINTEL::pname:parameter,
|
|
specifying a performance query feature, are:
|
|
|
|
include::{generated}/api/enums/VkPerformanceParameterTypeINTEL.txt[]
|
|
|
|
* ename:VK_PERFORMANCE_PARAMETER_TYPE_HW_COUNTERS_SUPPORTED_INTEL has a
|
|
boolean result which tells whether hardware counters can be captured.
|
|
* ename:VK_PERFORMANCE_PARAMETER_TYPE_STREAM_MARKER_VALID_BITS_INTEL has a
|
|
32 bits integer result which tells how many bits can be written into the
|
|
sname:VkStreamPerformanceMarkerInfoINTEL value.
|
|
--
|
|
|
|
[open,refpage='VkPerformanceValueINTEL',desc='Container for value and types of parameters that can be queried',type='structs']
|
|
--
|
|
The sname:VkPerformanceValueINTEL structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkPerformanceValueINTEL.txt[]
|
|
|
|
* pname:type is an elink:VkPerformanceValueTypeINTEL value specifying the
|
|
type of the returned data.
|
|
* pname:data is an slink:VkPerformanceValueDataINTEL union specifying the
|
|
value of the returned data.
|
|
|
|
include::{generated}/validity/structs/VkPerformanceValueINTEL.txt[]
|
|
--
|
|
|
|
[open,refpage='VkPerformanceValueTypeINTEL',desc='Type of the parameters that can be queried',type='enums']
|
|
--
|
|
Possible values of slink:VkPerformanceValueINTEL::pname:type, specifying the
|
|
type of the data returned in slink:VkPerformanceValueINTEL::pname:data, are:
|
|
|
|
* ename:VK_PERFORMANCE_VALUE_TYPE_UINT32_INTEL specifies that unsigned
|
|
32-bit integer data is returned in pname:data.value32.
|
|
* ename:VK_PERFORMANCE_VALUE_TYPE_UINT64_INTEL specifies that unsigned
|
|
64-bit integer data is returned in pname:data.value64.
|
|
* ename:VK_PERFORMANCE_VALUE_TYPE_FLOAT_INTEL specifies that
|
|
floating-point data is returned in pname:data.valueFloat.
|
|
* ename:VK_PERFORMANCE_VALUE_TYPE_BOOL_INTEL specifies that
|
|
basetype:Bool32 data is returned in pname:data.valueBool.
|
|
* ename:VK_PERFORMANCE_VALUE_TYPE_STRING_INTEL specifies that a pointer to
|
|
a NULL-terminated string is returned in pname:data.valueString.
|
|
The pointer is valid for the lifetime of the pname:device parameter
|
|
passed to flink:vkGetPerformanceParameterINTEL.
|
|
|
|
include::{generated}/api/enums/VkPerformanceValueTypeINTEL.txt[]
|
|
--
|
|
|
|
[open,refpage='VkPerformanceValueDataINTEL',desc='Values returned for the parameters',type='structs']
|
|
--
|
|
The sname:VkPerformanceValueDataINTEL union is defined as:
|
|
|
|
include::{generated}/api/structs/VkPerformanceValueDataINTEL.txt[]
|
|
|
|
* pname:data.value32 represents 32-bit integer data.
|
|
* pname:data.value64 represents 64-bit integer data.
|
|
* pname:data.valueFloat represents floating-point data.
|
|
* pname:data.valueBool represents basetype:Bool32 data.
|
|
* pname:data.valueString represents a pointer to a NULL-terminated string.
|
|
|
|
The correct member of the union is determined by the associated
|
|
elink:VkPerformanceValueTypeINTEL value.
|
|
|
|
include::{generated}/validity/structs/VkPerformanceValueDataINTEL.txt[]
|
|
--
|
|
|
|
[open,refpage='VkQueryPoolCreateInfoINTEL',desc='Structure specifying parameters to create a pool of performance queries',type='structs']
|
|
--
|
|
The sname:VkQueryPoolCreateInfoINTEL structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkQueryPoolCreateInfoINTEL.txt[]
|
|
|
|
To create a pool for Intel performance queries, set
|
|
slink:VkQueryPoolCreateInfo::pname:queryType to
|
|
ename:VK_QUERY_TYPE_PERFORMANCE_QUERY_INTEL and add a
|
|
sname:VkQueryPoolCreateInfoINTEL to the pname:pNext chain of the
|
|
slink:VkQueryPoolCreateInfo structure.
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:performanceCountersSampling describe how performance queries
|
|
should be captured.
|
|
|
|
include::{generated}/validity/structs/VkQueryPoolCreateInfoINTEL.txt[]
|
|
--
|
|
|
|
[open,refpage='VkQueryPoolSamplingModeINTEL',desc='Enum specifying how performance queries should be captured',type='enums']
|
|
--
|
|
Possible values of
|
|
slink:VkQueryPoolCreateInfoINTEL::pname:performanceCountersSampling are:
|
|
|
|
include::{generated}/api/enums/VkQueryPoolSamplingModeINTEL.txt[]
|
|
|
|
* ename:VK_QUERY_POOL_SAMPLING_MODE_MANUAL_INTEL is the default mode in
|
|
which the application calls flink:vkCmdBeginQuery and
|
|
flink:vkCmdEndQuery to record performance data.
|
|
--
|
|
|
|
[open,refpage='vkCmdSetPerformanceMarkerINTEL',desc='Markers',type='protos']
|
|
--
|
|
To help associate query results with a particular point at which an
|
|
application emitted commands, markers can be set into the command buffers
|
|
with the call:
|
|
|
|
include::{generated}/api/protos/vkCmdSetPerformanceMarkerINTEL.txt[]
|
|
|
|
The last marker set onto a command buffer before the end of a query will be
|
|
part of the query result.
|
|
|
|
include::{generated}/validity/protos/vkCmdSetPerformanceMarkerINTEL.txt[]
|
|
--
|
|
|
|
[open,refpage='VkPerformanceMarkerInfoINTEL',desc='Structure specifying performance markers',type='structs']
|
|
--
|
|
The sname:VkPerformanceMarkerInfoINTEL structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkPerformanceMarkerInfoINTEL.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:marker is the marker value that will be recorded into the opaque
|
|
query results.
|
|
|
|
include::{generated}/validity/structs/VkPerformanceMarkerInfoINTEL.txt[]
|
|
--
|
|
|
|
[open,refpage='vkCmdSetPerformanceStreamMarkerINTEL',desc='Markers',type='protos']
|
|
--
|
|
When monitoring the behavior of an application wihtin the dataset generated
|
|
by the entire set of applications running on the system, it is useful to
|
|
identify draw calls within a potentially huge amount of performance data.
|
|
To do so, application can generate stream markers that will be used to trace
|
|
back a particular draw call with a particular performance data item.
|
|
|
|
include::{generated}/api/protos/vkCmdSetPerformanceStreamMarkerINTEL.txt[]
|
|
|
|
include::{generated}/validity/protos/vkCmdSetPerformanceStreamMarkerINTEL.txt[]
|
|
--
|
|
|
|
[open,refpage='VkPerformanceStreamMarkerInfoINTEL',desc='Structure specifying stream performance markers',type='structs']
|
|
--
|
|
The sname:VkPerformanceStreamMarkerInfoINTEL structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkPerformanceStreamMarkerInfoINTEL.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:marker is the marker value that will be recorded into the reports
|
|
consumed by an external application.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkPerformanceStreamMarkerInfoINTEL-marker-02735]]
|
|
The value written by the application into pname:marker must: only used
|
|
the valid bits as reported by flink:vkGetPerformanceParameterINTEL with
|
|
the ename:VK_PERFORMANCE_PARAMETER_TYPE_STREAM_MARKER_VALID_BITS_INTEL.
|
|
****
|
|
|
|
include::{generated}/validity/structs/VkPerformanceStreamMarkerInfoINTEL.txt[]
|
|
--
|
|
|
|
[open,refpage='vkCmdSetPerformanceOverrideINTEL',desc='Performance override settings',type='protos']
|
|
--
|
|
Some applications might want measure the effect of a set of commands with a
|
|
different settings.
|
|
It is possible to override a particular settings using :
|
|
|
|
include::{generated}/api/protos/vkCmdSetPerformanceOverrideINTEL.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer where the override takes
|
|
place.
|
|
* pname:pOverrideInfo is a pointer to a
|
|
sname:VkPerformanceOverrideInfoINTEL selecting the parameter to
|
|
override.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkCmdSetPerformanceOverrideINTEL-pOverrideInfo-02736]]
|
|
pname:pOverrideInfo must: not be used with a
|
|
elink:VkPerformanceOverrideTypeINTEL that is not reported available by
|
|
fname:vkGetPerformanceParameterINTEL.
|
|
****
|
|
|
|
include::{generated}/validity/protos/vkCmdSetPerformanceOverrideINTEL.txt[]
|
|
--
|
|
|
|
[open,refpage='VkPerformanceOverrideInfoINTEL',desc='Performance override info',type='structs']
|
|
--
|
|
The sname:VkPerformanceOverrideInfoINTEL structure is defined as:
|
|
|
|
include::{generated}/api/structs/VkPerformanceOverrideInfoINTEL.txt[]
|
|
|
|
* pname:type is the particular elink:VkPerformanceOverrideTypeINTEL to
|
|
set.
|
|
* pname:enable defines whether the override is enabled.
|
|
* pname:parameter is a potential required parameter for the override.
|
|
|
|
include::{generated}/validity/structs/VkPerformanceOverrideInfoINTEL.txt[]
|
|
--
|
|
|
|
[open,refpage='VkPerformanceOverrideTypeINTEL',desc='Performance override type',type='enums']
|
|
--
|
|
Possible values of slink:VkPerformanceOverrideInfoINTEL::pname:type,
|
|
specifying performance override types, are:
|
|
|
|
include::{generated}/api/enums/VkPerformanceOverrideTypeINTEL.txt[]
|
|
|
|
* ename:VK_PERFORMANCE_OVERRIDE_TYPE_NULL_HARDWARE_INTEL turns all
|
|
rendering operations into noop.
|
|
* ename:VK_PERFORMANCE_OVERRIDE_TYPE_FLUSH_GPU_CACHES_INTEL stalls the
|
|
stream of commands until all previously emitted commands have completed
|
|
and all caches been flushed and invalidated.
|
|
--
|
|
|
|
[open,refpage='VkPerformanceConfigurationINTEL',desc='Device configuration for performance queries',type='handles']
|
|
--
|
|
Before submitting command buffers containing performance queries commands to
|
|
a device queue, the application must acquire and set a performance query
|
|
configuration.
|
|
The configuration can be released once all command buffers containing
|
|
performance query commands are not in a pending state.
|
|
|
|
include::{generated}/api/handles/VkPerformanceConfigurationINTEL.txt[]
|
|
--
|
|
|
|
[open,refpage='vkAcquirePerformanceConfigurationINTEL',desc='Acquire the performance query capability',type='protos']
|
|
--
|
|
To acquire a device performance configuration, call:
|
|
|
|
include::{generated}/api/protos/vkAcquirePerformanceConfigurationINTEL.txt[]
|
|
|
|
* pname:device is the logical device that the performance query commands
|
|
will be submitted to.
|
|
* pname:pAcquireInfo is a pointer to
|
|
slink:VkPerformanceConfigurationAcquireInfoINTEL.
|
|
* pname:pConfiguration is a pointer to a
|
|
sname:VkPerformanceConfigurationINTEL handle in which the resulting
|
|
configuration object is returned.
|
|
|
|
include::{generated}/validity/protos/vkAcquirePerformanceConfigurationINTEL.txt[]
|
|
--
|
|
|
|
[open,refpage='VkPerformanceConfigurationAcquireInfoINTEL',desc='Acquire a configuration to capture performance data',type='structs']
|
|
--
|
|
The sname:VkPerformanceConfigurationAcquireInfoINTEL structure is defined
|
|
as:
|
|
|
|
include::{generated}/api/structs/VkPerformanceConfigurationAcquireInfoINTEL.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:type is one of the elink:VkPerformanceConfigurationTypeINTEL type
|
|
of performance configuration that will be acquired.
|
|
|
|
include::{generated}/validity/structs/VkPerformanceConfigurationAcquireInfoINTEL.txt[]
|
|
--
|
|
|
|
[open,refpage='VkPerformanceConfigurationTypeINTEL',desc='Type of performance configuration',type='enums']
|
|
--
|
|
Possible values of
|
|
slink:VkPerformanceConfigurationAcquireInfoINTEL::pname:type, specifying
|
|
performance configuration types, are:
|
|
|
|
include::{generated}/api/enums/VkPerformanceConfigurationTypeINTEL.txt[]
|
|
--
|
|
|
|
[open,refpage='vkQueueSetPerformanceConfigurationINTEL',desc='Set a performance query',type='protos']
|
|
--
|
|
To set a performance configuration, call:
|
|
|
|
include::{generated}/api/protos/vkQueueSetPerformanceConfigurationINTEL.txt[]
|
|
|
|
* pname:queue is the queue on which the configuration will be used.
|
|
* pname:configuration is the configuration to use.
|
|
|
|
include::{generated}/validity/protos/vkQueueSetPerformanceConfigurationINTEL.txt[]
|
|
--
|
|
|
|
[open,refpage='vkReleasePerformanceConfigurationINTEL',desc='Release a configuration to capture performance data',type='protos']
|
|
--
|
|
To release a device performance configuration, call:
|
|
|
|
include::{generated}/api/protos/vkReleasePerformanceConfigurationINTEL.txt[]
|
|
|
|
* pname:device is the device associated to the configuration object to
|
|
release.
|
|
* pname:configuration is the configuration object to release.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkReleasePerformanceConfigurationINTEL-configuration-02737]]
|
|
pname:configuration must: not be released before all command buffers
|
|
submitted while the configuration was set are in
|
|
<<commandbuffers-lifecycle, pending state>>.
|
|
****
|
|
|
|
include::{generated}/validity/protos/vkReleasePerformanceConfigurationINTEL.txt[]
|
|
--
|
|
|
|
endif::VK_INTEL_performance_query[]
|