status-im/Vulkan-Docs
2
0
Fork 0
mirror of https://github.com/status-im/Vulkan-Docs.git synced 2025-02-25 20:45:12 +00:00
Code Issues Projects Releases Wiki Activity
Vulkan-Docs/chapters/VK_KHR_pipeline_executable_properties/pipelines.txt
Jon Leech 194a7f4d0d Change log for September 8, 2019 Vulkan 1.1.122 spec update: 
* Update release number to 122.

Internal Issues:

  * Add style guide language on not using standalone `+` signs (internal
    issue 736); not using leading whitespace for markup (internal issue
    747); and on keeping descriptions of a single API in a contiguous block
    of markup (internal issue 949), and apply them to the specification.
  * Add a glossary definition of "`constant integral expression`", pointing
    to the SPIR-V "`constant instruction`" definition (internal issue 1225).
  * Many minor edits to improve writing style consistency and capture
    additional style guidelines (internal issue 1553).
  * Clarify that <<fragops-depth-write, depth writes are not performed>> if
    there is no depth framebuffer attachment (internal issue 1771).
  * Allow implementations to use rectangular line style of interpolation for
    <<primsrast-lines-bresenham, wide Bresenham lines>>, though replicating
    attributes is still preferred. Clarify that code:FragCoord is not
    replicated (internal issue 1772).
  * Resolve a contradiction in valid usage statements for
    slink:VkImageCreateInfo and slink:VkImageStencilUsageCreateInfoEXT
    (internal issue 1773).
  * Add style guide discussion of markup for indented equations, and use
    markup workaround for asciidoctor 2 compatibility (internal issue 1793).
  * Deprecate the `<<VK_EXT_validation_flags>>` extension in `vk.xml` and
    the extension appendix (internal issue 1801).
  * Add a new checker script `scripts/xml_consistency.py`. This is not
    currently run as part of internal CI (internal merge request 3285).
  * Correct "`an`" -> "`a`" prepositions where needed (internal merge
    request 3334).
  * Clarify that the <<features-uniformBufferStandardLayout,
    pname:uniformBufferStandardLayout>> feature is only required when the
    extension defining it is supported (internal merge request 3341).
  * Bring scripts into closer sync with OpenXR, mainly through conversion of
    comments to docstrings where appropriate, and add gen-scripts-docs.sh
    (internal merge request 3324).
  * Correct pname:maxDrawMeshTasksCount to 2^16^-1 in the <<limits-required,
    Required Limits>> table (internal merge requests 3361).

New Extensions

  * `<<VK_IMG_format_pvrtc>>` (public issue 512).
2019-09-08 20:41:02 -07:00

330 lines
15 KiB
Plaintext
Raw Blame History

// 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 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 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 executables associated
with the pipeline, at most pname:pExecutableCount structures will be written
and fname:vkGetPipelineExecutablePropertiesKHR will return
ename:VK_INCOMPLETE.
.Valid Usage
****
* [[VUID-vkGetPipelineExecutablePropertiesKHR-pipelineExecutableProperties-03270]]
<<features-pipelineExecutableProperties,
pname:pipelineExecutableProperties>> 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 an extension-specific 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 an extension-specific structure.
* pname:stages is a bitmask of elink:VkShaderStageFlagBits indicating
which shader stages (if any) were principally used as inputs to compile
this pipeline executable.
* pname:name is a short human readable name for this executable.
* pname:description is a human readable description for this executable.
* pname:subgroupSize is the subgroup size with which this executable is
dispatched.
The pname:stages field may: be zero or it may: contain one or more bits
describing the stages principally used to compile this pipeline.
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 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 fname:vkGetPipelineExecutableStatisticsKHR will return
ename:VK_INCOMPLETE.
.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 set in the
pname:flags field of slink:VkGraphicsPipelineCreateInfo or
slink:VkComputePipelineCreateInfo.
****
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 an extension-specific structure.
* pname:pipeline is the pipeline to query.
* pname:executableIndex is the index of the 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 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 an extension-specific structure.
* pname:name is a short human readable name for this statistic.
* pname:description 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
fname:vkGetPipelineExecutableInternalRepresentationsKHR will return
ename:VK_INCOMPLETE.
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 compile pipeline with the final shader
assembly (if any) last.
.Valid Usage
****
* [[VUID-vkGetPipelineExecutableInternalRepresentationsKHR-pipelineExecutableProperties-03276]]
<<features-pipelineExecutableProperties,
pname:pipelineExecutableProperties>> 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
set in the pname:flags field of slink:VkGraphicsPipelineCreateInfo or
slink:VkComputePipelineCreateInfo.
****
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 an extension-specific structure.
* pname:name is a short human readable name for this internal
representation.
* pname:description 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 data, as described below.
* pname:pData is either `NULL` or a pointer to an block of data into which
the implementation will write the textual form of 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 data, at most pname:dataSize bytes of data will be written to
pname:pData and fname:vkGetPipelineExecutableInternalRepresentationsKHR will
return ename:VK_INCOMPLETE.
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[]
--
Reference in New Issue View Git Blame Copy Permalink