// Copyright 2019-2021 The Khronos Group, Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

[open,refpage='vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR',desc='Reports properties of the performance query counters available on a queue family of a device',type='protos']
--
To enumerate the performance query counters available on a queue family of a
physical device, call:

include::{generated}/api/protos/vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR.txt[]

  * pname:physicalDevice is the handle to the physical device whose queue
    family performance query counter properties will be queried.
  * pname:queueFamilyIndex is the index into the queue family of the
    physical device we want to get properties for.
  * pname:pCounterCount is a pointer to an integer related to the number of
    counters available or queried, as described below.
  * pname:pCounters is either `NULL` or a pointer to an array of
    slink:VkPerformanceCounterKHR structures.
  * pname:pCounterDescriptions is either `NULL` or a pointer to an array of
    slink:VkPerformanceCounterDescriptionKHR structures.

If pname:pCounters is `NULL` and pname:pCounterDescriptions is `NULL`, then
the number of counters available is returned in pname:pCounterCount.
Otherwise, pname:pCounterCount must: point to a variable set by the user to
the number of elements in the pname:pCounters, pname:pCounterDescriptions,
or both arrays and on return the variable is overwritten with the number of
structures actually written out.
If pname:pCounterCount is less than the number of counters available, at
most pname:pCounterCount structures will be written, and ename:VK_INCOMPLETE
will be returned instead of ename:VK_SUCCESS, to indicate that not all the
available counters were returned.

include::{generated}/validity/protos/vkEnumeratePhysicalDeviceQueueFamilyPerformanceQueryCountersKHR.txt[]
--

[open,refpage='VkPerformanceCounterKHR',desc='Structure providing information about a counter',type='structs']
--
The sname:VkPerformanceCounterKHR structure is defined as:

include::{generated}/api/structs/VkPerformanceCounterKHR.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:unit is a elink:VkPerformanceCounterUnitKHR specifying the unit
    that the counter data will record.
  * pname:scope is a elink:VkPerformanceCounterScopeKHR specifying the scope
    that the counter belongs to.
  * pname:storage is a elink:VkPerformanceCounterStorageKHR specifying the
    storage type that the counter's data uses.
  * pname:uuid is an array of size ename:VK_UUID_SIZE, containing 8-bit
    values that represent a universally unique identifier for the counter of
    the physical device.

include::{generated}/validity/structs/VkPerformanceCounterKHR.txt[]
--

[open,refpage='VkPerformanceCounterUnitKHR',desc='Supported counter unit types',type='enums']
--
Performance counters have an associated unit.
This unit describes how to interpret the performance counter result.

The performance counter unit types which may: be returned in
slink:VkPerformanceCounterKHR::pname:unit are:

include::{generated}/api/enums/VkPerformanceCounterUnitKHR.txt[]

  * ename:VK_PERFORMANCE_COUNTER_UNIT_GENERIC_KHR - the performance counter
    unit is a generic data point.
  * ename:VK_PERFORMANCE_COUNTER_UNIT_PERCENTAGE_KHR - the performance
    counter unit is a percentage (%).
  * ename:VK_PERFORMANCE_COUNTER_UNIT_NANOSECONDS_KHR - the performance
    counter unit is a value of nanoseconds (ns).
  * ename:VK_PERFORMANCE_COUNTER_UNIT_BYTES_KHR - the performance counter
    unit is a value of bytes.
  * ename:VK_PERFORMANCE_COUNTER_UNIT_BYTES_PER_SECOND_KHR - the performance
    counter unit is a value of bytes/s.
  * ename:VK_PERFORMANCE_COUNTER_UNIT_KELVIN_KHR - the performance counter
    unit is a temperature reported in Kelvin.
  * ename:VK_PERFORMANCE_COUNTER_UNIT_WATTS_KHR - the performance counter
    unit is a value of watts (W).
  * ename:VK_PERFORMANCE_COUNTER_UNIT_VOLTS_KHR - the performance counter
    unit is a value of volts (V).
  * ename:VK_PERFORMANCE_COUNTER_UNIT_AMPS_KHR - the performance counter
    unit is a value of amps (A).
  * ename:VK_PERFORMANCE_COUNTER_UNIT_HERTZ_KHR - the performance counter
    unit is a value of hertz (Hz).
  * ename:VK_PERFORMANCE_COUNTER_UNIT_CYCLES_KHR - the performance counter
    unit is a value of cycles.
--

[open,refpage='VkPerformanceCounterScopeKHR',desc='Supported counter scope types',type='enums']
--
Performance counters have an associated scope.
This scope describes the granularity of a performance counter.

The performance counter scope types which may: be returned in
slink:VkPerformanceCounterKHR::pname:scope are:

include::{generated}/api/enums/VkPerformanceCounterScopeKHR.txt[]

  * ename:VK_PERFORMANCE_COUNTER_SCOPE_COMMAND_BUFFER_KHR - the performance
    counter scope is a single complete command buffer.
  * ename:VK_PERFORMANCE_COUNTER_SCOPE_RENDER_PASS_KHR - the performance
    counter scope is zero or more complete render passes.
    The performance query containing the performance counter must: begin and
    end outside a render pass instance.
  * ename:VK_PERFORMANCE_COUNTER_SCOPE_COMMAND_KHR - the performance counter
    scope is zero or more commands.
--

[open,refpage='VkPerformanceCounterStorageKHR',desc='Supported counter storage types',type='enums']
--
Performance counters have an associated storage.
This storage describes the payload of a counter result.

The performance counter storage types which may: be returned in
slink:VkPerformanceCounterKHR::pname:storage are:

include::{generated}/api/enums/VkPerformanceCounterStorageKHR.txt[]

  * ename:VK_PERFORMANCE_COUNTER_STORAGE_INT32_KHR - the performance counter
    storage is a 32-bit signed integer.
  * ename:VK_PERFORMANCE_COUNTER_STORAGE_INT64_KHR - the performance counter
    storage is a 64-bit signed integer.
  * ename:VK_PERFORMANCE_COUNTER_STORAGE_UINT32_KHR - the performance
    counter storage is a 32-bit unsigned integer.
  * ename:VK_PERFORMANCE_COUNTER_STORAGE_UINT64_KHR - the performance
    counter storage is a 64-bit unsigned integer.
  * ename:VK_PERFORMANCE_COUNTER_STORAGE_FLOAT32_KHR - the performance
    counter storage is a 32-bit floating-point.
  * ename:VK_PERFORMANCE_COUNTER_STORAGE_FLOAT64_KHR - the performance
    counter storage is a 64-bit floating-point.
--

[open,refpage='VkPerformanceCounterDescriptionKHR',desc='Structure providing more detailed information about a counter',type='structs']
--
The sname:VkPerformanceCounterDescriptionKHR structure is defined as:

include::{generated}/api/structs/VkPerformanceCounterDescriptionKHR.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:flags is a bitmask of
    elink:VkPerformanceCounterDescriptionFlagBitsKHR indicating the usage
    behavior for the counter.
  * pname:name is an array of size ename:VK_MAX_DESCRIPTION_SIZE, containing
    a null-terminated UTF-8 string specifying the name of the counter.
  * pname:category is an array of size ename:VK_MAX_DESCRIPTION_SIZE,
    containing a null-terminated UTF-8 string specifying the category of the
    counter.
  * pname:description is an array of size ename:VK_MAX_DESCRIPTION_SIZE,
    containing a null-terminated UTF-8 string specifying the description of
    the counter.

include::{generated}/validity/structs/VkPerformanceCounterDescriptionKHR.txt[]
--

[open,refpage='VkPerformanceCounterDescriptionFlagBitsKHR',desc='Bitmask specifying usage behavior for a counter',type='enums']
--
Bits which can: be set in
slink:VkPerformanceCounterDescriptionKHR::pname:flags to specify usage
behavior for a performance counter are:

include::{generated}/api/enums/VkPerformanceCounterDescriptionFlagBitsKHR.txt[]

  * ename:VK_PERFORMANCE_COUNTER_DESCRIPTION_PERFORMANCE_IMPACTING_BIT_KHR
    specifies that recording the counter may: have a noticeable performance
    impact.
  * ename:VK_PERFORMANCE_COUNTER_DESCRIPTION_CONCURRENTLY_IMPACTED_BIT_KHR
    specifies that concurrently recording the counter while other submitted
    command buffers are running may: impact the accuracy of the recording.
--

[open,refpage='VkPerformanceCounterDescriptionFlagsKHR',desc='Bitmask of VkPerformanceCounterDescriptionFlagBitsKHR',type='flags']
--
include::{generated}/api/flags/VkPerformanceCounterDescriptionFlagsKHR.txt[]

tlink:VkPerformanceCounterDescriptionFlagsKHR is a bitmask type for setting
a mask of zero or more elink:VkPerformanceCounterDescriptionFlagBitsKHR.
--