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

// This section is included inside the Pipelines chapter (pipelines.txt)

[open,refpage='vkGetPipelineExecutablePropertiesKHR',desc='Get the executables associated with a pipeline',type='protos']
--
When a pipeline is created, its state and shaders are compiled into zero or
more device-specific executables, which are used when executing commands
against that pipeline.
To query the properties of these pipeline executables, call:

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

  * pname:device is the device that created the pipeline.
  * pname:pPipelineInfo describes the pipeline being queried.
  * pname:pExecutableCount is a pointer to an integer related to the number
    of pipeline executables available or queried, as described below.
  * pname:pProperties is either `NULL` or a pointer to an array of
    slink:VkPipelineExecutablePropertiesKHR structures.

If pname:pProperties is `NULL`, then the number of pipeline executables
associated with the pipeline is returned in pname:pExecutableCount.
Otherwise, pname:pExecutableCount must: point to a variable set by the user
to the number of elements in the pname:pProperties array, and on return the
variable is overwritten with the number of structures actually written to
pname:pProperties.
If pname:pExecutableCount is less than the number of pipeline executables
associated with the pipeline, at most pname:pExecutableCount structures will
be written, and ename:VK_INCOMPLETE will be returned instead of
ename:VK_SUCCESS, to indicate that not all the available properties were
returned.

.Valid Usage
****
  * [[VUID-vkGetPipelineExecutablePropertiesKHR-pipelineExecutableInfo-03270]]
    <<features-pipelineExecutableInfo, pname:pipelineExecutableInfo>> must:
    be enabled
  * [[VUID-vkGetPipelineExecutablePropertiesKHR-pipeline-03271]]
    pname:pipeline member of pname:pPipelineInfo must: have been created
    with pname:device
****

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

[open,refpage='VkPipelineInfoKHR',desc='Structure describing a pipeline',type='structs']
--
The sname:VkPipelineInfoKHR structure is defined as:

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

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:pipeline is a sname:VkPipeline handle.

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

[open,refpage='VkPipelineExecutablePropertiesKHR',desc='Structure describing a pipeline executable',type='structs']
--
The sname:VkPipelineExecutablePropertiesKHR structure is defined as:

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

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:stages is a bitmask of zero or more elink:VkShaderStageFlagBits
    indicating which shader stages (if any) were principally used as inputs
    to compile this pipeline executable.
  * pname:name is an array of ename:VK_MAX_DESCRIPTION_SIZE code:char
    containing a null-terminated UTF-8 string which is a short human
    readable name for this pipeline executable.
  * pname:description is an array of ename:VK_MAX_DESCRIPTION_SIZE code:char
    containing a null-terminated UTF-8 string which is a human readable
    description for this pipeline executable.
  * pname:subgroupSize is the subgroup size with which this pipeline
    executable is dispatched.

Not all implementations have a 1:1 mapping between shader stages and
pipeline executables and some implementations may: reduce a given shader
stage to fixed function hardware programming such that no pipeline
executable is available.
No guarantees are provided about the mapping between shader stages and
pipeline executables and pname:stages should: be considered a best effort
hint.
Because the application cannot: rely on the pname:stages field to provide an
exact description, pname:name and pname:description provide a human readable
name and description which more accurately describes the given pipeline
executable.

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

[open,refpage='vkGetPipelineExecutableStatisticsKHR',desc='Get compile time statistics associated with a pipeline executable',type='protos']
--
Each pipeline executable may: have a set of statistics associated with it
that are generated by the pipeline compilation process.
These statistics may: include things such as instruction counts, amount of
spilling (if any), maximum number of simultaneous threads, or anything else
which may: aid developers in evaluating the expected performance of a
shader.
To query the compile-time statistics associated with a pipeline executable,
call:

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

  * pname:device is the device that created the pipeline.
  * pname:pExecutableInfo describes the pipeline executable being queried.
  * pname:pStatisticCount is a pointer to an integer related to the number
    of statistics available or queried, as described below.
  * pname:pStatistics is either `NULL` or a pointer to an array of
    slink:VkPipelineExecutableStatisticKHR structures.

If pname:pStatistics is `NULL`, then the number of statistics associated
with the pipeline executable is returned in pname:pStatisticCount.
Otherwise, pname:pStatisticCount must: point to a variable set by the user
to the number of elements in the pname:pStatistics array, and on return the
variable is overwritten with the number of structures actually written to
pname:pStatistics.
If pname:pStatisticCount is less than the number of statistics associated
with the pipeline executable, at most pname:pStatisticCount structures will
be written, and ename:VK_INCOMPLETE will be returned instead of
ename:VK_SUCCESS, to indicate that not all the available statistics were
returned.

.Valid Usage
****
  * [[VUID-vkGetPipelineExecutableStatisticsKHR-pipelineExecutableInfo-03272]]
    <<features-pipelineExecutableInfo, pname:pipelineExecutableInfo>> must:
    be enabled
  * [[VUID-vkGetPipelineExecutableStatisticsKHR-pipeline-03273]]
    pname:pipeline member of pname:pExecutableInfo must: have been created
    with pname:device
  * [[VUID-vkGetPipelineExecutableStatisticsKHR-pipeline-03274]]
    pname:pipeline member of pname:pExecutableInfo must: have been created
    with ename:VK_PIPELINE_CREATE_CAPTURE_STATISTICS_BIT_KHR
****

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

[open,refpage='VkPipelineExecutableInfoKHR',desc='Structure describing a pipeline executable to query for associated statistics or internal representations',type='structs']
--
The sname:VkPipelineExecutableInfoKHR structure is defined as:

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

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:pipeline is the pipeline to query.
  * pname:executableIndex is the index of the pipeline executable to query
    in the array of executable properties returned by
    flink:vkGetPipelineExecutablePropertiesKHR.

.Valid Usage
****
  * [[VUID-VkPipelineExecutableInfoKHR-executableIndex-03275]]
    pname:executableIndex must: be less than the number of pipeline
    executables associated with pname:pipeline as returned in the
    pname:pExecutableCount parameter of
    fname:vkGetPipelineExecutablePropertiesKHR
****

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

[open,refpage='VkPipelineExecutableStatisticKHR',desc='Structure describing a compile-time pipeline executable statistic',type='structs']
--
The sname:VkPipelineExecutableStatisticKHR structure is defined as:

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

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:name is an array of ename:VK_MAX_DESCRIPTION_SIZE code:char
    containing a null-terminated UTF-8 string which is a short human
    readable name for this statistic.
  * pname:description is an array of ename:VK_MAX_DESCRIPTION_SIZE code:char
    containing a null-terminated UTF-8 string which is a human readable
    description for this statistic.
  * pname:format is a elink:VkPipelineExecutableStatisticFormatKHR value
    specifying the format of the data found in pname:value.
  * pname:value is the value of this statistic.

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

[open,refpage='VkPipelineExecutableStatisticFormatKHR',desc='Enum describing a pipeline executable statistic's data format',type='enums']
--
The ename:VkPipelineExecutableStatisticFormatKHR enum is defined as:

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

  * ename:VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_BOOL32_KHR specifies that
    the statistic is returned as a 32-bit boolean value which must: be
    either ename:VK_TRUE or ename:VK_FALSE and should: be read from the
    fname:b32 field of sname:VkPipelineExecutableStatisticValueKHR.
  * ename:VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHR specifies that
    the statistic is returned as a signed 64-bit integer and should: be read
    from the fname:i64 field of sname:VkPipelineExecutableStatisticValueKHR.
  * ename:VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHR specifies that
    the statistic is returned as an unsigned 64-bit integer and should: be
    read from the fname:u64 field of
    sname:VkPipelineExecutableStatisticValueKHR.
  * ename:VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_FLOAT64_KHR specifies that
    the statistic is returned as a 64-bit floating-point value and should:
    be read from the fname:f64 field of
    sname:VkPipelineExecutableStatisticValueKHR.
--

[open,refpage='VkPipelineExecutableStatisticValueKHR',desc='A union describing a pipeline executable statistic's value',type='structs']
--
The sname:VkPipelineExecutableStatisticValueKHR union is defined as:

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

  * pname:b32 is the 32-bit boolean value if the
    ename:VkPipelineExecutableStatisticFormatKHR is
    ename:VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_BOOL32_KHR.
  * pname:i64 is the signed 64-bit integer value if the
    ename:VkPipelineExecutableStatisticFormatKHR is
    ename:VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_INT64_KHR.
  * pname:u64 is the unsigned 64-bit integer value if the
    ename:VkPipelineExecutableStatisticFormatKHR is
    ename:VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_UINT64_KHR.
  * pname:f64 is the 64-bit floating-point value if the
    ename:VkPipelineExecutableStatisticFormatKHR is
    ename:VK_PIPELINE_EXECUTABLE_STATISTIC_FORMAT_FLOAT64_KHR.

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

[open,refpage='vkGetPipelineExecutableInternalRepresentationsKHR',desc='Get internal representations of the pipeline executable',type='protos']
--
Each pipeline executable may: have one or more text or binary internal
representations associated with it which are generated as part of the
compile process.
These may: include the final shader assembly, a binary form of the compiled
shader, or the shader compiler's internal representation at any number of
intermediate compile steps.
To query the internal representations associated with a pipeline executable,
call:

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

  * pname:device is the device that created the pipeline.
  * pname:pExecutableInfo describes the pipeline executable being queried.
  * pname:pInternalRepresentationCount is a pointer to an integer related to
    the number of internal representations available or queried, as
    described below.
  * pname:pInternalRepresentations is either `NULL` or a pointer to an array
    of slink:VkPipelineExecutableInternalRepresentationKHR structures.

If pname:pInternalRepresentations is `NULL`, then the number of internal
representations associated with the pipeline executable is returned in
pname:pInternalRepresentationCount.
Otherwise, pname:pInternalRepresentationCount must: point to a variable set
by the user to the number of elements in the pname:pInternalRepresentations
array, and on return the variable is overwritten with the number of
structures actually written to pname:pInternalRepresentations.
If pname:pInternalRepresentationCount is less than the number of internal
representations associated with the pipeline executable, at most
pname:pInternalRepresentationCount structures will be written, and
ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to
indicate that not all the available representations were returned.

While the details of the internal representations remain
implementation-dependent, the implementation should: order the internal
representations in the order in which they occur in the compiled pipeline
with the final shader assembly (if any) last.

.Valid Usage
****
  * [[VUID-vkGetPipelineExecutableInternalRepresentationsKHR-pipelineExecutableInfo-03276]]
    <<features-pipelineExecutableInfo, pname:pipelineExecutableInfo>> must:
    be enabled
  * [[VUID-vkGetPipelineExecutableInternalRepresentationsKHR-pipeline-03277]]
    pname:pipeline member of pname:pExecutableInfo must: have been created
    with pname:device
  * [[VUID-vkGetPipelineExecutableInternalRepresentationsKHR-pipeline-03278]]
    pname:pipeline member of pname:pExecutableInfo must: have been created
    with ename:VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR
****

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

[open,refpage='VkPipelineExecutableInternalRepresentationKHR',desc='Structure describing the textual form of a pipeline executable internal representation',type='structs']
--
The sname:VkPipelineExecutableInternalRepresentationKHR structure is defined
as:

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

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:name is an array of ename:VK_MAX_DESCRIPTION_SIZE code:char
    containing a null-terminated UTF-8 string which is a short human
    readable name for this internal representation.
  * pname:description is an array of ename:VK_MAX_DESCRIPTION_SIZE code:char
    containing a null-terminated UTF-8 string which is a human readable
    description for this internal representation.
  * pname:isText specifies whether the returned data is text or opaque data.
    If pname:isText is ename:VK_TRUE then the data returned in pname:pData
    is text and is guaranteed to be a null-terminated UTF-8 string.
  * pname:dataSize is an integer related to the size, in bytes, of the
    internal representation's data, as described below.
  * pname:pData is either `NULL` or a pointer to a block of data into which
    the implementation will write the internal representation.

If pname:pData is `NULL`, then the size, in bytes, of the internal
representation data is returned in pname:dataSize.
Otherwise, pname:dataSize must be the size of the buffer, in bytes, pointed
to by pname:pData and on return pname:dataSize is overwritten with the
number of bytes of data actually written to pname:pData including any
trailing null character.
If pname:dataSize is less than the size, in bytes, of the internal
representation's data, at most pname:dataSize bytes of data will be written
to pname:pData, and ename:VK_INCOMPLETE will be returned instead of
ename:VK_SUCCESS, to indicate that not all the available representation was
returned.

If pname:isText is ename:VK_TRUE and pname:pData is not `NULL` and
pname:dataSize is not zero, the last byte written to pname:pData will be a
null character.

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