mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-12 15:04:10 +00:00
64fa8ef4df
* Bump API patch number and header version number to 66 for this update.
Github Issues:
* Clarified how and when ename:VK_ERROR_TOO_MANY_OBJECTS is generated in
flink:vkAllocate Memory, and remove incorrect valid usage statement
about exceeding the API limit (public issue 356).
* Minor clarification of the description of
flink:vkUpdateDescriptorSetWithTemplateKHR::pname:descriptorUpdateTemplate
(public issue 564).
* Minor fixes for flink:vkCmdSetViewportWScalingNV (public pull request
588).
* Fix random name markup issues (public pull request 603).
* Fix code:BuiltIn decoration typo in the <<fxvertex-attrib, Vertex
Attributes>> section (public pull request 606).
* Fix synchronization language following the definition of
flink:vkAcquireNextImageKHR (public issue 607).
* Restore descriptions of several commands and structures missing from the
generated spec due to a mistyped asciidoctor conditional (public issue
612).
* Fix 1.0.41 changelog to refer to public issues 403/404 (public issue
618).
Internal Issues:
* Refactor valid usage statements with internal conditionals in
`copies.txt`, `pipelines.txt`, `renderpass.txt`, and `resources.txt` so
each branch of the conditional appears as a standalone statement which
can contain a separate VUID. This should have no impact on the generated
specs, but is necessary given the present state of the VU extractor and
the validation layer code that consumes them (internal issue 1043).
* Fix VkQueueGlobalPriorityEXT enum values missing _EXT suffix (internal
issue 1045).
* Clarified initial ownership of resources bound to shared memory objects,
(internal issue 1068).
* Fix duplicated valid usage ID tag for flink:vkCmdCopyImage, and make the
required layouts include ename:VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIONAL in
both cases (internal issue 1084).
Other Issues:
* Remove the noise functions from GLSL for SPIR-V for Vulkan in the
`GL_KHR_vulkan_glsl.txt` extension.
New Extensions:
* `VK_EXT_external_memory_host`
* `VK_EXT_external_memory_dma_buf`
* `VK_EXT_queue_family_foreign`
1681 lines
78 KiB
Plaintext
1681 lines
78 KiB
Plaintext
// Copyright (c) 2015-2017 Khronos Group. This work is licensed under a
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
// http://creativecommons.org/licenses/by/4.0/
|
|
|
|
[[pipelines]]
|
|
= Pipelines
|
|
|
|
The following <<pipelines-block-diagram,figure>> shows a block diagram of
|
|
the Vulkan pipelines.
|
|
Some Vulkan commands specify geometric objects to be drawn or computational
|
|
work to be performed, while others specify state controlling how objects are
|
|
handled by the various pipeline stages, or control data transfer between
|
|
memory organized as images and buffers.
|
|
Commands are effectively sent through a processing pipeline, either a
|
|
_graphics pipeline_ or a _compute pipeline_.
|
|
|
|
The first stage of the <<pipelines-graphics,graphics pipeline>>
|
|
(<<drawing,Input Assembler>>) assembles vertices to form geometric
|
|
primitives such as points, lines, and triangles, based on a requested
|
|
primitive topology.
|
|
In the next stage (<<shaders-vertex,Vertex Shader>>) vertices can: be
|
|
transformed, computing positions and attributes for each vertex.
|
|
If <<tessellation,tessellation>> and/or <<geometry,geometry>> shaders are
|
|
supported, they can: then generate multiple primitives from a single input
|
|
primitive, possibly changing the primitive topology or generating additional
|
|
attribute data in the process.
|
|
|
|
The final resulting primitives are <<vertexpostproc-clipping,clipped>> to a
|
|
clip volume in preparation for the next stage, <<primsrast,Rasterization>>.
|
|
The rasterizer produces a series of framebuffer addresses and values using a
|
|
two-dimensional description of a point, line segment, or triangle.
|
|
Each _fragment_ so produced is fed to the next stage
|
|
(<<shaders-fragment,Fragment Shader>>) that performs operations on
|
|
individual fragments before they finally alter the framebuffer.
|
|
These operations include conditional updates into the framebuffer based on
|
|
incoming and previously stored depth values (to effect <<fragops-depth,depth
|
|
buffering>>), <<framebuffer-blending,blending>> of incoming fragment colors
|
|
with stored colors, as well as <<framebuffer-blendoperations,masking>>,
|
|
<<fragops-stencil,stenciling>>, and other <<framebuffer-logicop,logical
|
|
operations>> on fragment values.
|
|
|
|
Framebuffer operations read and write the color and depth/stencil
|
|
attachments of the framebuffer for a given subpass of a <<renderpass,render
|
|
pass instance>>.
|
|
The attachments can: be used as input attachments in the fragment shader in
|
|
a later subpass of the same render pass.
|
|
|
|
The <<pipelines-compute,compute pipeline>> is a separate pipeline from the
|
|
graphics pipeline, which operates on one-, two-, or three-dimensional
|
|
workgroups which can: read from and write to buffer and image memory.
|
|
|
|
This ordering is meant only as a tool for describing Vulkan, not as a strict
|
|
rule of how Vulkan is implemented, and we present it only as a means to
|
|
organize the various operations of the pipelines.
|
|
Actual ordering guarantees between pipeline stages are explained in detail
|
|
in the <<synchronization-pipeline-stages-order, synchronization chapter>>.
|
|
|
|
[[pipelines-block-diagram]]
|
|
image::images/pipeline.svg[title="Block diagram of the Vulkan pipeline",{fullimagewidth},align="center"]
|
|
|
|
Each pipeline is controlled by a monolithic object created from a
|
|
description of all of the shader stages and any relevant fixed-function
|
|
stages.
|
|
<<interfaces,Linking>> the whole pipeline together allows the optimization
|
|
of shaders based on their input/outputs and eliminates expensive draw time
|
|
state validation.
|
|
|
|
A pipeline object is bound to the device state in command buffers.
|
|
Any pipeline object state that is marked as dynamic is not applied to the
|
|
device state when the pipeline is bound.
|
|
Dynamic state not set by binding the pipeline object can: be modified at any
|
|
time and persists for the lifetime of the command buffer, or until modified
|
|
by another dynamic state command or another pipeline bind.
|
|
No state, including dynamic state, is inherited from one command buffer to
|
|
another.
|
|
Only dynamic state that is required: for the operations performed in the
|
|
command buffer needs to be set.
|
|
For example, if blending is disabled by the pipeline state then the dynamic
|
|
color blend constants do not need to be specified in the command buffer,
|
|
even if this state is marked as dynamic in the pipeline state object.
|
|
If a new pipeline object is bound with state not marked as dynamic after a
|
|
previous pipeline object with that same state as dynamic, the new pipeline
|
|
object state will override the dynamic state.
|
|
Modifying dynamic state that is not set as dynamic by the pipeline state
|
|
object will lead to undefined results.
|
|
|
|
[open,refpage='VkPipeline',desc='Opaque handle to a pipeline object',type='handles']
|
|
--
|
|
|
|
Compute and graphics pipelines are each represented by sname:VkPipeline
|
|
handles:
|
|
|
|
include::../api/handles/VkPipeline.txt[]
|
|
|
|
--
|
|
|
|
|
|
[[pipelines-compute]]
|
|
== Compute Pipelines
|
|
|
|
Compute pipelines consist of a single static compute shader stage and the
|
|
pipeline layout.
|
|
|
|
The compute pipeline represents a compute shader and is created by calling
|
|
fname:vkCreateComputePipelines with pname:module and pname:pName selecting
|
|
an entry point from a shader module, where that entry point defines a valid
|
|
compute shader, in the sname:VkPipelineShaderStageCreateInfo structure
|
|
contained within the sname:VkComputePipelineCreateInfo structure.
|
|
|
|
[open,refpage='vkCreateComputePipelines',desc='Creates a new compute pipeline object',type='protos']
|
|
--
|
|
|
|
To create compute pipelines, call:
|
|
|
|
include::../api/protos/vkCreateComputePipelines.txt[]
|
|
|
|
* pname:device is the logical device that creates the compute pipelines.
|
|
* pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that
|
|
pipeline caching is disabled; or the handle of a valid
|
|
<<pipelines-cache,pipeline cache>> object, in which case use of that
|
|
cache is enabled for the duration of the command.
|
|
* pname:createInfoCount is the length of the pname:pCreateInfos and
|
|
pname:pPipelines arrays.
|
|
* pname:pCreateInfos is an array of sname:VkComputePipelineCreateInfo
|
|
structures.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
* pname:pPipelines is a pointer to an array in which the resulting compute
|
|
pipeline objects are returned.
|
|
ifdef::editing-notes[]
|
|
+
|
|
[NOTE]
|
|
.editing-note
|
|
====
|
|
TODO (Jon) - Should we say something like "`the i'th element of the
|
|
pname:pPipelines array is created based on the corresponding element of the
|
|
pname:pCreateInfos array`"? Also for flink:vkCreateGraphicsPipelines below.
|
|
====
|
|
endif::editing-notes[]
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkCreateComputePipelines-flags-00695]]
|
|
If the pname:flags member of any element of pname:pCreateInfos contains
|
|
the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the
|
|
pname:basePipelineIndex member of that same element is not `-1`,
|
|
pname:basePipelineIndex must: be less than the index into
|
|
pname:pCreateInfos that corresponds to that element
|
|
* [[VUID-vkCreateComputePipelines-flags-00696]]
|
|
If the pname:flags member of any element of pname:pCreateInfos contains
|
|
the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline
|
|
must: have been created with the
|
|
ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set
|
|
****
|
|
|
|
include::../validity/protos/vkCreateComputePipelines.txt[]
|
|
--
|
|
|
|
[open,refpage='VkComputePipelineCreateInfo',desc='Structure specifying parameters of a newly created compute pipeline',type='structs']
|
|
--
|
|
|
|
The sname:VkComputePipelineCreateInfo structure is defined as:
|
|
|
|
include::../api/structs/VkComputePipelineCreateInfo.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:flags is a bitmask of elink:VkPipelineCreateFlagBits specifying
|
|
how the pipeline will be generated.
|
|
* pname:stage is a slink:VkPipelineShaderStageCreateInfo describing the
|
|
compute shader.
|
|
* pname:layout is the description of binding locations used by both the
|
|
pipeline and descriptor sets used with the pipeline.
|
|
* pname:basePipelineHandle is a pipeline to derive from
|
|
* pname:basePipelineIndex is an index into the pname:pCreateInfos
|
|
parameter to use as a pipeline to derive from
|
|
|
|
The parameters pname:basePipelineHandle and pname:basePipelineIndex are
|
|
described in more detail in <<pipelines-pipeline-derivatives,Pipeline
|
|
Derivatives>>.
|
|
|
|
pname:stage points to a structure of type
|
|
sname:VkPipelineShaderStageCreateInfo.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkComputePipelineCreateInfo-flags-00697]]
|
|
If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT
|
|
flag, and pname:basePipelineIndex is -1, pname:basePipelineHandle must:
|
|
be a valid handle to a compute sname:VkPipeline
|
|
* [[VUID-VkComputePipelineCreateInfo-flags-00698]]
|
|
If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT
|
|
flag, and pname:basePipelineHandle is dlink:VK_NULL_HANDLE,
|
|
pname:basePipelineIndex must: be a valid index into the calling
|
|
command's pname:pCreateInfos parameter
|
|
* [[VUID-VkComputePipelineCreateInfo-flags-00699]]
|
|
If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT
|
|
flag, and pname:basePipelineIndex is not -1, pname:basePipelineHandle
|
|
must: be dlink:VK_NULL_HANDLE
|
|
* [[VUID-VkComputePipelineCreateInfo-flags-00700]]
|
|
If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT
|
|
flag, and pname:basePipelineHandle is not dlink:VK_NULL_HANDLE,
|
|
pname:basePipelineIndex must: be -1
|
|
* [[VUID-VkComputePipelineCreateInfo-stage-00701]]
|
|
The pname:stage member of pname:stage must: be
|
|
ename:VK_SHADER_STAGE_COMPUTE_BIT
|
|
* [[VUID-VkComputePipelineCreateInfo-stage-00702]]
|
|
The shader code for the entry point identified by pname:stage and the
|
|
rest of the state identified by this structure must: adhere to the
|
|
pipeline linking rules described in the <<interfaces,Shader Interfaces>>
|
|
chapter
|
|
* [[VUID-VkComputePipelineCreateInfo-layout-00703]]
|
|
pname:layout must: be
|
|
<<descriptorsets-pipelinelayout-consistency,consistent>> with the layout
|
|
of the compute shader specified in pname:stage
|
|
* [[VUID-VkComputePipelineCreateInfo-layout-01687]]
|
|
The number of resources in pname:layout accessible to the compute shader
|
|
stage must: be less than or equal to
|
|
sname:VkPhysicalDeviceLimits::pname:maxPerStageResources
|
|
****
|
|
|
|
include::../validity/structs/VkComputePipelineCreateInfo.txt[]
|
|
--
|
|
|
|
[open,refpage='VkPipelineShaderStageCreateInfo',desc='Structure specifying parameters of a newly created pipeline shader stage',type='structs']
|
|
--
|
|
|
|
The sname:VkPipelineShaderStageCreateInfo structure is defined as:
|
|
|
|
include::../api/structs/VkPipelineShaderStageCreateInfo.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:flags is reserved for future use.
|
|
* pname:stage is a elink:VkShaderStageFlagBits value specifying a single
|
|
pipeline stage.
|
|
* pname:module is a sname:VkShaderModule object that contains the shader
|
|
for this stage.
|
|
* pname:pName is a pointer to a null-terminated UTF-8 string specifying
|
|
the entry point name of the shader for this stage.
|
|
* pname:pSpecializationInfo is a pointer to slink:VkSpecializationInfo, as
|
|
described in <<pipelines-specialization-constants,Specialization
|
|
Constants>>, and can: be `NULL`.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkPipelineShaderStageCreateInfo-stage-00704]]
|
|
If the <<features-features-geometryShader,geometry shaders>> feature is
|
|
not enabled, pname:stage must: not be ename:VK_SHADER_STAGE_GEOMETRY_BIT
|
|
* [[VUID-VkPipelineShaderStageCreateInfo-stage-00705]]
|
|
If the <<features-features-tessellationShader,tessellation shaders>>
|
|
feature is not enabled, pname:stage must: not be
|
|
ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or
|
|
ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT
|
|
* [[VUID-VkPipelineShaderStageCreateInfo-stage-00706]]
|
|
pname:stage must: not be ename:VK_SHADER_STAGE_ALL_GRAPHICS, or
|
|
ename:VK_SHADER_STAGE_ALL
|
|
* [[VUID-VkPipelineShaderStageCreateInfo-pName-00707]]
|
|
pname:pName must: be the name of an code:OpEntryPoint in pname:module
|
|
with an execution model that matches pname:stage
|
|
* [[VUID-VkPipelineShaderStageCreateInfo-maxClipDistances-00708]]
|
|
If the identified entry point includes any variable in its interface
|
|
that is declared with the code:ClipDistance code:BuiltIn decoration,
|
|
that variable must: not have an array size greater than
|
|
sname:VkPhysicalDeviceLimits::pname:maxClipDistances
|
|
* [[VUID-VkPipelineShaderStageCreateInfo-maxCullDistances-00709]]
|
|
If the identified entry point includes any variable in its interface
|
|
that is declared with the code:CullDistance code:BuiltIn decoration,
|
|
that variable must: not have an array size greater than
|
|
sname:VkPhysicalDeviceLimits::pname:maxCullDistances
|
|
* [[VUID-VkPipelineShaderStageCreateInfo-maxCombinedClipAndCullDistances-00710]]
|
|
If the identified entry point includes any variables in its interface
|
|
that are declared with the code:ClipDistance or code:CullDistance
|
|
code:BuiltIn decoration, those variables must: not have array sizes
|
|
which sum to more than
|
|
sname:VkPhysicalDeviceLimits::pname:maxCombinedClipAndCullDistances
|
|
* [[VUID-VkPipelineShaderStageCreateInfo-maxSampleMaskWords-00711]]
|
|
If the identified entry point includes any variable in its interface
|
|
that is declared with the code:SampleMask code:BuiltIn decoration, that
|
|
variable must: not have an array size greater than
|
|
sname:VkPhysicalDeviceLimits::pname:maxSampleMaskWords
|
|
* [[VUID-VkPipelineShaderStageCreateInfo-stage-00712]]
|
|
If pname:stage is ename:VK_SHADER_STAGE_VERTEX_BIT, the identified entry
|
|
point must: not include any input variable in its interface that is
|
|
decorated with code:CullDistance
|
|
* [[VUID-VkPipelineShaderStageCreateInfo-stage-00713]]
|
|
If pname:stage is ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT or
|
|
ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, and the identified
|
|
entry point has an code:OpExecutionMode instruction that specifies a
|
|
patch size with code:OutputVertices, the patch size must: be greater
|
|
than `0` and less than or equal to
|
|
sname:VkPhysicalDeviceLimits::pname:maxTessellationPatchSize
|
|
* [[VUID-VkPipelineShaderStageCreateInfo-stage-00714]]
|
|
If pname:stage is ename:VK_SHADER_STAGE_GEOMETRY_BIT, the identified
|
|
entry point must: have an code:OpExecutionMode instruction that
|
|
specifies a maximum output vertex count that is greater than `0` and
|
|
less than or equal to
|
|
sname:VkPhysicalDeviceLimits::pname:maxGeometryOutputVertices
|
|
* [[VUID-VkPipelineShaderStageCreateInfo-stage-00715]]
|
|
If pname:stage is ename:VK_SHADER_STAGE_GEOMETRY_BIT, the identified
|
|
entry point must: have an code:OpExecutionMode instruction that
|
|
specifies an invocation count that is greater than `0` and less than or
|
|
equal to
|
|
sname:VkPhysicalDeviceLimits::pname:maxGeometryShaderInvocations
|
|
* [[VUID-VkPipelineShaderStageCreateInfo-stage-00716]]
|
|
If pname:stage is ename:VK_SHADER_STAGE_GEOMETRY_BIT, and the identified
|
|
entry point writes to code:Layer for any primitive, it must: write the
|
|
same value to code:Layer for all vertices of a given primitive
|
|
* [[VUID-VkPipelineShaderStageCreateInfo-stage-00717]]
|
|
If pname:stage is ename:VK_SHADER_STAGE_GEOMETRY_BIT, and the identified
|
|
entry point writes to code:ViewportIndex for any primitive, it must:
|
|
write the same value to code:ViewportIndex for all vertices of a given
|
|
primitive
|
|
* [[VUID-VkPipelineShaderStageCreateInfo-stage-00718]]
|
|
If pname:stage is ename:VK_SHADER_STAGE_FRAGMENT_BIT, the identified
|
|
entry point must: not include any output variables in its interface
|
|
decorated with code:CullDistance
|
|
* [[VUID-VkPipelineShaderStageCreateInfo-stage-00719]]
|
|
If pname:stage is ename:VK_SHADER_STAGE_FRAGMENT_BIT, and the identified
|
|
entry point writes to code:FragDepth in any execution path, it must:
|
|
write to code:FragDepth in all execution paths
|
|
ifdef::VK_EXT_shader_stencil_export[]
|
|
* [[VUID-VkPipelineShaderStageCreateInfo-stage-01511]]
|
|
If pname:stage is ename:VK_SHADER_STAGE_FRAGMENT_BIT, and the identified
|
|
entry point writes to code:FragStencilRefEXT in any execution path, it
|
|
must: write to code:FragStencilRefEXT in all execution paths
|
|
endif::VK_EXT_shader_stencil_export[]
|
|
****
|
|
|
|
include::../validity/structs/VkPipelineShaderStageCreateInfo.txt[]
|
|
--
|
|
|
|
[open,refpage='VkShaderStageFlagBits',desc='Bitmask specifying a pipeline stage',type='enums']
|
|
--
|
|
|
|
Commands and structures which need to specify one or more shader stages do
|
|
so using a bitmask whose bits correspond to stages.
|
|
Bits which can: be set to specify shader stages are:
|
|
|
|
include::../api/enums/VkShaderStageFlagBits.txt[]
|
|
|
|
* ename:VK_SHADER_STAGE_VERTEX_BIT specifies the vertex stage.
|
|
* ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT specifies the
|
|
tessellation control stage.
|
|
* ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT specifies the
|
|
tessellation evaluation stage.
|
|
* ename:VK_SHADER_STAGE_GEOMETRY_BIT specifies the geometry stage.
|
|
* ename:VK_SHADER_STAGE_FRAGMENT_BIT specifies the fragment stage.
|
|
* ename:VK_SHADER_STAGE_COMPUTE_BIT specifies the compute stage.
|
|
* ename:VK_SHADER_STAGE_ALL_GRAPHICS is a combination of bits used as
|
|
shorthand to specify all graphics stages defined above (excluding the
|
|
compute stage).
|
|
* ename:VK_SHADER_STAGE_ALL is a combination of bits used as shorthand to
|
|
specify all shader stages supported by the device, including all
|
|
additional stages which are introduced by extensions.
|
|
|
|
--
|
|
|
|
|
|
[[pipelines-graphics]]
|
|
== Graphics Pipelines
|
|
|
|
Graphics pipelines consist of multiple shader stages, multiple
|
|
fixed-function pipeline stages, and a pipeline layout.
|
|
|
|
[open,refpage='vkCreateGraphicsPipelines',desc='Create graphics pipelines',type='protos']
|
|
--
|
|
|
|
To create graphics pipelines, call:
|
|
|
|
include::../api/protos/vkCreateGraphicsPipelines.txt[]
|
|
|
|
* pname:device is the logical device that creates the graphics pipelines.
|
|
* pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that
|
|
pipeline caching is disabled; or the handle of a valid
|
|
<<pipelines-cache,pipeline cache>> object, in which case use of that
|
|
cache is enabled for the duration of the command.
|
|
* pname:createInfoCount is the length of the pname:pCreateInfos and
|
|
pname:pPipelines arrays.
|
|
* pname:pCreateInfos is an array of sname:VkGraphicsPipelineCreateInfo
|
|
structures.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
* pname:pPipelines is a pointer to an array in which the resulting
|
|
graphics pipeline objects are returned.
|
|
|
|
The slink:VkGraphicsPipelineCreateInfo structure includes an array of shader
|
|
create info structures containing all the desired active shader stages, as
|
|
well as creation info to define all relevant fixed-function stages, and a
|
|
pipeline layout.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkCreateGraphicsPipelines-flags-00720]]
|
|
If the pname:flags member of any element of pname:pCreateInfos contains
|
|
the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the
|
|
pname:basePipelineIndex member of that same element is not `-1`,
|
|
pname:basePipelineIndex must: be less than the index into
|
|
pname:pCreateInfos that corresponds to that element
|
|
* [[VUID-vkCreateGraphicsPipelines-flags-00721]]
|
|
If the pname:flags member of any element of pname:pCreateInfos contains
|
|
the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline
|
|
must: have been created with the
|
|
ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set
|
|
****
|
|
|
|
include::../validity/protos/vkCreateGraphicsPipelines.txt[]
|
|
--
|
|
|
|
[open,refpage='VkGraphicsPipelineCreateInfo',desc='Structure specifying parameters of a newly created graphics pipeline',type='structs']
|
|
--
|
|
|
|
The sname:VkGraphicsPipelineCreateInfo structure is defined as:
|
|
|
|
include::../api/structs/VkGraphicsPipelineCreateInfo.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:flags is a bitmask of elink:VkPipelineCreateFlagBits specifying
|
|
how the pipeline will be generated.
|
|
* pname:stageCount is the number of entries in the pname:pStages array.
|
|
* pname:pStages is an array of size pname:stageCount structures of type
|
|
slink:VkPipelineShaderStageCreateInfo describing the set of the shader
|
|
stages to be included in the graphics pipeline.
|
|
* pname:pVertexInputState is a pointer to an instance of the
|
|
slink:VkPipelineVertexInputStateCreateInfo structure.
|
|
* pname:pInputAssemblyState is a pointer to an instance of the
|
|
slink:VkPipelineInputAssemblyStateCreateInfo structure which determines
|
|
input assembly behavior, as described in <<drawing, Drawing Commands>>.
|
|
* pname:pTessellationState is a pointer to an instance of the
|
|
slink:VkPipelineTessellationStateCreateInfo structure, and is ignored if
|
|
the pipeline does not include a tessellation control shader stage and
|
|
tessellation evaluation shader stage.
|
|
* pname:pViewportState is a pointer to an instance of the
|
|
slink:VkPipelineViewportStateCreateInfo structure, and is ignored if the
|
|
pipeline has rasterization disabled.
|
|
* pname:pRasterizationState is a pointer to an instance of the
|
|
slink:VkPipelineRasterizationStateCreateInfo structure.
|
|
* pname:pMultisampleState is a pointer to an instance of the
|
|
slink:VkPipelineMultisampleStateCreateInfo, and is ignored if the
|
|
pipeline has rasterization disabled.
|
|
* pname:pDepthStencilState is a pointer to an instance of the
|
|
slink:VkPipelineDepthStencilStateCreateInfo structure, and is ignored if
|
|
the pipeline has rasterization disabled or if the subpass of the render
|
|
pass the pipeline is created against does not use a depth/stencil
|
|
attachment.
|
|
* pname:pColorBlendState is a pointer to an instance of the
|
|
slink:VkPipelineColorBlendStateCreateInfo structure, and is ignored if
|
|
the pipeline has rasterization disabled or if the subpass of the render
|
|
pass the pipeline is created against does not use any color attachments.
|
|
* pname:pDynamicState is a pointer to
|
|
slink:VkPipelineDynamicStateCreateInfo and is used to indicate which
|
|
properties of the pipeline state object are dynamic and can: be changed
|
|
independently of the pipeline state.
|
|
This can: be `NULL`, which means no state in the pipeline is considered
|
|
dynamic.
|
|
* pname:layout is the description of binding locations used by both the
|
|
pipeline and descriptor sets used with the pipeline.
|
|
* pname:renderPass is a handle to a render pass object describing the
|
|
environment in which the pipeline will be used; the pipeline must: only
|
|
be used with an instance of any render pass compatible with the one
|
|
provided.
|
|
See <<renderpass-compatibility,Render Pass Compatibility>> for more
|
|
information.
|
|
* pname:subpass is the index of the subpass in the render pass where this
|
|
pipeline will be used.
|
|
* pname:basePipelineHandle is a pipeline to derive from.
|
|
* pname:basePipelineIndex is an index into the pname:pCreateInfos
|
|
parameter to use as a pipeline to derive from.
|
|
|
|
The parameters pname:basePipelineHandle and pname:basePipelineIndex are
|
|
described in more detail in <<pipelines-pipeline-derivatives,Pipeline
|
|
Derivatives>>.
|
|
|
|
pname:pStages points to an array of slink:VkPipelineShaderStageCreateInfo
|
|
structures, which were previously described in <<pipelines-compute,Compute
|
|
Pipelines>>.
|
|
|
|
pname:pDynamicState points to a structure of type
|
|
slink:VkPipelineDynamicStateCreateInfo.
|
|
|
|
ifdef::VK_NV_glsl_shader[]
|
|
If any shader stage fails to compile,
|
|
ifdef::VK_EXT_debug_report[]
|
|
the compile log will be reported back to the application, and
|
|
endif::VK_EXT_debug_report[]
|
|
ename:VK_ERROR_INVALID_SHADER_NV will be generated.
|
|
endif::VK_NV_glsl_shader[]
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-flags-00722]]
|
|
If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT
|
|
flag, and pname:basePipelineIndex is -1, pname:basePipelineHandle must:
|
|
be a valid handle to a graphics sname:VkPipeline
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-flags-00723]]
|
|
If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT
|
|
flag, and pname:basePipelineHandle is dlink:VK_NULL_HANDLE,
|
|
pname:basePipelineIndex must: be a valid index into the calling
|
|
command's pname:pCreateInfos parameter
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-flags-00724]]
|
|
If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT
|
|
flag, and pname:basePipelineIndex is not -1, pname:basePipelineHandle
|
|
must: be dlink:VK_NULL_HANDLE
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-flags-00725]]
|
|
If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT
|
|
flag, and pname:basePipelineHandle is not dlink:VK_NULL_HANDLE,
|
|
pname:basePipelineIndex must: be -1
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-stage-00726]]
|
|
The pname:stage member of each element of pname:pStages must: be unique
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-stage-00727]]
|
|
The pname:stage member of one element of pname:pStages must: be
|
|
ename:VK_SHADER_STAGE_VERTEX_BIT
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-stage-00728]]
|
|
The pname:stage member of each element of pname:pStages must: not be
|
|
ename:VK_SHADER_STAGE_COMPUTE_BIT
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pStages-00729]]
|
|
If pname:pStages includes a tessellation control shader stage, it must:
|
|
include a tessellation evaluation shader stage
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pStages-00730]]
|
|
If pname:pStages includes a tessellation evaluation shader stage, it
|
|
must: include a tessellation control shader stage
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pStages-00731]]
|
|
If pname:pStages includes a tessellation control shader stage and a
|
|
tessellation evaluation shader stage, pname:pTessellationState must: be
|
|
a valid pointer to a valid sname:VkPipelineTessellationStateCreateInfo
|
|
structure
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pStages-00732]]
|
|
If pname:pStages includes tessellation shader stages, the shader code of
|
|
at least one stage must: contain an code:OpExecutionMode instruction
|
|
that specifies the type of subdivision in the pipeline
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pStages-00733]]
|
|
If pname:pStages includes tessellation shader stages, and the shader
|
|
code of both stages contain an code:OpExecutionMode instruction that
|
|
specifies the type of subdivision in the pipeline, they must: both
|
|
specify the same subdivision mode
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pStages-00734]]
|
|
If pname:pStages includes tessellation shader stages, the shader code of
|
|
at least one stage must: contain an code:OpExecutionMode instruction
|
|
that specifies the output patch size in the pipeline
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pStages-00735]]
|
|
If pname:pStages includes tessellation shader stages, and the shader
|
|
code of both contain an code:OpExecutionMode instruction that specifies
|
|
the out patch size in the pipeline, they must: both specify the same
|
|
patch size
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pStages-00736]]
|
|
If pname:pStages includes tessellation shader stages, the pname:topology
|
|
member of pname:pInputAssembly must: be
|
|
ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-topology-00737]]
|
|
If the pname:topology member of pname:pInputAssembly is
|
|
ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST, pname:pStages must: include
|
|
tessellation shader stages
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pStages-00738]]
|
|
If pname:pStages includes a geometry shader stage, and does not include
|
|
any tessellation shader stages, its shader code must: contain an
|
|
code:OpExecutionMode instruction that specifies an input primitive type
|
|
that is <<shaders-geometry-execution, compatible>> with the primitive
|
|
topology specified in pname:pInputAssembly
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pStages-00739]]
|
|
If pname:pStages includes a geometry shader stage, and also includes
|
|
tessellation shader stages, its shader code must: contain an
|
|
code:OpExecutionMode instruction that specifies an input primitive type
|
|
that is <<shaders-geometry-execution, compatible>> with the primitive
|
|
topology that is output by the tessellation stages
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pStages-00740]]
|
|
If pname:pStages includes a fragment shader stage and a geometry shader
|
|
stage, and the fragment shader code reads from an input variable that is
|
|
decorated with code:PrimitiveID, then the geometry shader code must:
|
|
write to a matching output variable, decorated with code:PrimitiveID, in
|
|
all execution paths
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pStages-00741]]
|
|
If pname:pStages includes a fragment shader stage, its shader code must:
|
|
not read from any input attachment that is defined as
|
|
ename:VK_ATTACHMENT_UNUSED in pname:subpass
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pStages-00742]]
|
|
The shader code for the entry points identified by pname:pStages, and
|
|
the rest of the state identified by this structure must: adhere to the
|
|
pipeline linking rules described in the <<interfaces,Shader Interfaces>>
|
|
chapter
|
|
// The block of VU below come in alternate versions when the extension is
|
|
// enabled.
|
|
ifndef::VK_KHR_maintenance2[]
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-subpass-00743]]
|
|
If rasterization is not disabled and pname:subpass uses a depth/stencil
|
|
attachment in pname:renderPass that has a layout of
|
|
ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL or
|
|
ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL_KHR in
|
|
the sname:VkAttachmentReference defined by pname:subpass, the
|
|
pname:depthWriteEnable member of pname:pDepthStencilState must: be
|
|
ename:VK_FALSE
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-subpass-00744]]
|
|
If rasterization is not disabled and pname:subpass uses a depth/stencil
|
|
attachment in pname:renderPass that has a layout of
|
|
ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL or
|
|
ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL_KHR in
|
|
the sname:VkAttachmentReference defined by pname:subpass, the
|
|
pname:failOp, pname:passOp and pname:depthFailOp members of each of the
|
|
pname:front and pname:back members of pname:pDepthStencilState must: be
|
|
ename:VK_STENCIL_OP_KEEP
|
|
endif::VK_KHR_maintenance2[]
|
|
// The nested ifdefs are there in anticipation of the hoped-for day when the
|
|
// VU extractor and validation layers can handle VU with imbedded
|
|
// conditionals.
|
|
ifdef::VK_KHR_maintenance2[]
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-subpass-01756]]
|
|
If rasterization is not disabled and pname:subpass uses a depth/stencil
|
|
attachment in pname:renderpass that has a layout of
|
|
ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL
|
|
// ifdef::VK_KHR_maintenance2[]
|
|
or ename:VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL_KHR
|
|
// endif::VK_KHR_maintenance2[]
|
|
in the sname:VkAttachmentReference defined by pname:subpass, the
|
|
pname:depthWriteEnable member of pname:pDepthStencilState must: be
|
|
ename:VK_FALSE
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-subpass-01757]]
|
|
If rasterization is not disabled and pname:subpass uses a depth/stencil
|
|
attachment in pname:renderpass that has a layout of
|
|
ename:VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL
|
|
// ifdef::VK_KHR_maintenance2[]
|
|
or ename:VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL_KHR
|
|
// endif::VK_KHR_maintenance2[]
|
|
in the sname:VkAttachmentReference defined by pname:subpass, the
|
|
pname:failOp, pname:passOp and pname:depthFailOp members of each of the
|
|
pname:front and pname:back members of pname:pDepthStencilState must: be
|
|
ename:VK_STENCIL_OP_KEEP
|
|
endif::VK_KHR_maintenance2[]
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-subpass-00745]]
|
|
If rasterization is not disabled and the subpass uses color attachments,
|
|
then for each color attachment in the subpass the pname:blendEnable
|
|
member of the corresponding element of the pname:pAttachment member of
|
|
pname:pColorBlendState must: be ename:VK_FALSE if the pname:format of
|
|
the attachment does not support color blend operations, as specified by
|
|
the ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT flag in
|
|
sname:VkFormatProperties::pname:linearTilingFeatures or
|
|
sname:VkFormatProperties::pname:optimalTilingFeatures returned by
|
|
fname:vkGetPhysicalDeviceFormatProperties
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-attachmentCount-00746]]
|
|
If rasterization is not disabled and the subpass uses color attachments,
|
|
the pname:attachmentCount member of pname:pColorBlendState must: be
|
|
equal to the pname:colorAttachmentCount used to create pname:subpass
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00747]]
|
|
If no element of the pname:pDynamicStates member of pname:pDynamicState
|
|
is ename:VK_DYNAMIC_STATE_VIEWPORT, the pname:pViewports member of
|
|
pname:pViewportState must: be a valid pointer to an array of
|
|
pname:pViewportState::pname:viewportCount sname:VkViewport structures
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00748]]
|
|
If no element of the pname:pDynamicStates member of pname:pDynamicState
|
|
is ename:VK_DYNAMIC_STATE_SCISSOR, the pname:pScissors member of
|
|
pname:pViewportState must: be a valid pointer to an array of
|
|
pname:pViewportState::pname:scissorCount sname:VkRect2D structures
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00749]]
|
|
If the wide lines feature is not enabled, and no element of the
|
|
pname:pDynamicStates member of pname:pDynamicState is
|
|
ename:VK_DYNAMIC_STATE_LINE_WIDTH, the pname:lineWidth member of
|
|
pname:pRasterizationState must: be `1.0`
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00750]]
|
|
If the pname:rasterizerDiscardEnable member of pname:pRasterizationState
|
|
is ename:VK_FALSE, pname:pViewportState must: be a valid pointer to a
|
|
valid sname:VkPipelineViewportStateCreateInfo structure
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00751]]
|
|
If the pname:rasterizerDiscardEnable member of pname:pRasterizationState
|
|
is ename:VK_FALSE, pname:pMultisampleState must: be a valid pointer to a
|
|
valid sname:VkPipelineMultisampleStateCreateInfo structure
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00752]]
|
|
If the pname:rasterizerDiscardEnable member of pname:pRasterizationState
|
|
is ename:VK_FALSE, and pname:subpass uses a depth/stencil attachment,
|
|
pname:pDepthStencilState must: be a valid pointer to a valid
|
|
sname:VkPipelineDepthStencilStateCreateInfo structure
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00753]]
|
|
If the pname:rasterizerDiscardEnable member of pname:pRasterizationState
|
|
is ename:VK_FALSE, and pname:subpass uses color attachments,
|
|
pname:pColorBlendState must: be a valid pointer to a valid
|
|
sname:VkPipelineColorBlendStateCreateInfo structure
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00754]]
|
|
If the depth bias clamping feature is not enabled, no element of the
|
|
pname:pDynamicStates member of pname:pDynamicState is
|
|
ename:VK_DYNAMIC_STATE_DEPTH_BIAS, and the pname:depthBiasEnable member
|
|
of pname:pRasterizationState is ename:VK_TRUE, the pname:depthBiasClamp
|
|
member of pname:pRasterizationState must: be `0.0`
|
|
ifndef::VK_EXT_depth_range_unrestricted[]
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00755]]
|
|
If no element of the pname:pDynamicStates member of pname:pDynamicState
|
|
is ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS, and the
|
|
pname:depthBoundsTestEnable member of pname:pDepthStencilState is
|
|
ename:VK_TRUE, the pname:minDepthBounds and pname:maxDepthBounds members
|
|
of pname:pDepthStencilState must: be between `0.0` and `1.0`, inclusive
|
|
endif::VK_EXT_depth_range_unrestricted[]
|
|
ifdef::VK_EXT_sample_locations[]
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-01521]]
|
|
If no element of the pname:pDynamicStates member of pname:pDynamicState
|
|
is ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT, and the
|
|
pname:sampleLocationsEnable member of a
|
|
slink:VkPipelineSampleLocationsStateCreateInfoEXT structure chained to
|
|
the pname:pNext chain of pname:pMultisampleState is ename:VK_TRUE,
|
|
pname:sampleLocationsInfo.sampleLocationGridSize.width must: evenly
|
|
divide
|
|
slink:VkMultisamplePropertiesEXT::pname:sampleLocationGridSize.width as
|
|
returned by flink:vkGetPhysicalDeviceMultisamplePropertiesEXT with a
|
|
pname:samples parameter equaling pname:rasterizationSamples
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-01522]]
|
|
If no element of the pname:pDynamicStates member of pname:pDynamicState
|
|
is ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT, and the
|
|
pname:sampleLocationsEnable member of a
|
|
slink:VkPipelineSampleLocationsStateCreateInfoEXT structure chained to
|
|
the pname:pNext chain of pname:pMultisampleState is ename:VK_TRUE,
|
|
pname:sampleLocationsInfo.sampleLocationGridSize.height must: evenly
|
|
divide
|
|
slink:VkMultisamplePropertiesEXT::pname:sampleLocationGridSize.height as
|
|
returned by flink:vkGetPhysicalDeviceMultisamplePropertiesEXT with a
|
|
pname:samples parameter equaling pname:rasterizationSamples
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-01523]]
|
|
If no element of the pname:pDynamicStates member of pname:pDynamicState
|
|
is ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT, and the
|
|
pname:sampleLocationsEnable member of a
|
|
slink:VkPipelineSampleLocationsStateCreateInfoEXT structure chained to
|
|
the pname:pNext chain of pname:pMultisampleState is ename:VK_TRUE,
|
|
pname:sampleLocationsInfo.sampleLocationsPerPixel must: equal
|
|
pname:rasterizationSamples
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-sampleLocationsEnable-01524]]
|
|
If the pname:sampleLocationsEnable member of a
|
|
slink:VkPipelineSampleLocationsStateCreateInfoEXT structure chained to
|
|
the pname:pNext chain of pname:pMultisampleState is ename:VK_TRUE, the
|
|
fragment shader code must: not statically use the extended instruction
|
|
code:InterpolateAtSample
|
|
endif::VK_EXT_sample_locations[]
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-layout-00756]]
|
|
pname:layout must: be
|
|
<<descriptorsets-pipelinelayout-consistency,consistent>> with all
|
|
shaders specified in pname:pStages
|
|
ifndef::VK_AMD_mixed_attachment_samples[]
|
|
ifndef::VK_NV_framebuffer_mixed_samples[]
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-subpass-00757]]
|
|
If pname:subpass uses color and/or depth/stencil attachments, then the
|
|
pname:rasterizationSamples member of pname:pMultisampleState must: be
|
|
the same as the sample count for those subpass attachments
|
|
endif::VK_NV_framebuffer_mixed_samples[]
|
|
endif::VK_AMD_mixed_attachment_samples[]
|
|
ifdef::VK_AMD_mixed_attachment_samples[]
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-subpass-01505]]
|
|
If pname:subpass uses color and/or depth/stencil attachments, then the
|
|
pname:rasterizationSamples member of pname:pMultisampleState must: equal
|
|
the maximum of the sample counts of those subpass attachments
|
|
endif::VK_AMD_mixed_attachment_samples[]
|
|
ifdef::VK_NV_framebuffer_mixed_samples[]
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-subpass-01411]]
|
|
If pname:subpass has a depth/stencil attachment and depth test, stencil
|
|
test, or depth bounds test are enabled, then the
|
|
pname:rasterizationSamples member of pname:pMultisampleState must: be
|
|
the same as the sample count of the depth/stencil attachment
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-subpass-01412]]
|
|
If pname:subpass has any color attachments, then the
|
|
pname:rasterizationSamples member of pname:pMultisampleState must: be
|
|
greater than or equal to the sample count for those subpass attachments
|
|
endif::VK_NV_framebuffer_mixed_samples[]
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-subpass-00758]]
|
|
If pname:subpass does not use any color and/or depth/stencil
|
|
attachments, then the pname:rasterizationSamples member of
|
|
pname:pMultisampleState must: follow the rules for a
|
|
<<renderpass-noattachments, zero-attachment subpass>>
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-subpass-00759]]
|
|
pname:subpass must: be a valid subpass within pname:renderPass
|
|
ifdef::VK_KHX_multiview[]
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-renderPass-00760]]
|
|
If the pname:renderPass has multiview enabled and pname:subpass has more
|
|
than one bit set in the view mask and pname:multiviewTessellationShader
|
|
is not enabled, then pname:pStages must: not include tessellation
|
|
shaders.
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-renderPass-00761]]
|
|
If the pname:renderPass has multiview enabled and pname:subpass has more
|
|
than one bit set in the view mask and pname:multiviewGeometryShader is
|
|
not enabled, then pname:pStages must: not include a geometry shader.
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-renderPass-00762]]
|
|
If the pname:renderPass has multiview enabled and pname:subpass has more
|
|
than one bit set in the view mask, shaders in the pipeline must: not
|
|
write to the code:Layer built-in output
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-renderPass-00763]]
|
|
If the pname:renderPass has multiview enabled, then all shaders must:
|
|
not include variables decorated with the code:Layer built-in decoration
|
|
in their interfaces.
|
|
endif::VK_KHX_multiview[]
|
|
ifdef::VK_KHX_device_group[]
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-flags-00764]]
|
|
pname:flags must: not contain the
|
|
ename:VK_PIPELINE_CREATE_DISPATCH_BASE_KHX flag.
|
|
endif::VK_KHX_device_group[]
|
|
ifdef::VK_KHR_maintenance2[]
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pStages-01565]]
|
|
If pname:pStages includes a fragment shader stage and an input
|
|
attachment was referenced by the
|
|
slink:VkRenderPassInputAttachmentAspectCreateInfoKHR at pname:renderPass
|
|
create time, its shader code must: not read from any aspect that was not
|
|
specified in the pname:aspectMask of the corresponding
|
|
slink:VkInputAttachmentAspectReferenceKHR structure.
|
|
endif::VK_KHR_maintenance2[]
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-layout-01688]]
|
|
The number of resources in pname:layout accessible to each shader stage
|
|
that is used by the pipeline must: be less than or equal to
|
|
sname:VkPhysicalDeviceLimits::pname:maxPerStageResources
|
|
ifdef::VK_NV_clip_space_w_scaling[]
|
|
* [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-01715]]
|
|
If no element of the pname:pDynamicStates member of pname:pDynamicState
|
|
is ename:VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV, and the
|
|
pname:viewportWScalingEnable member of a
|
|
slink:VkPipelineViewportWScalingStateCreateInfoNV structure, chained to
|
|
the pname:pNext chain of pname:pViewportState, is ename:VK_TRUE, the
|
|
pname:pViewportWScalings member of the
|
|
slink:VkPipelineViewportWScalingStateCreateInfoNV must: be a pointer to
|
|
an array of
|
|
slink:VkPipelineViewportWScalingStateCreateInfoNV::pname:viewportCount
|
|
valid slink:VkViewportWScalingNV structures
|
|
endif::VK_NV_clip_space_w_scaling[]
|
|
****
|
|
|
|
include::../validity/structs/VkGraphicsPipelineCreateInfo.txt[]
|
|
--
|
|
|
|
[open,refpage='VkPipelineCreateFlagBits',desc='Bitmask controlling how a pipeline is created',type='enums']
|
|
--
|
|
|
|
Possible values of the pname:flags member of
|
|
slink:VkGraphicsPipelineCreateInfo and slink:VkComputePipelineCreateInfo,
|
|
specifying how a pipeline is created, are:
|
|
|
|
include::../api/enums/VkPipelineCreateFlagBits.txt[]
|
|
|
|
* ename:VK_PIPELINE_CREATE_DISABLE_OPTIMIZATION_BIT specifies that the
|
|
created pipeline will not be optimized.
|
|
Using this flag may: reduce the time taken to create the pipeline.
|
|
* ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT specifies that the
|
|
pipeline to be created is allowed to be the parent of a pipeline that
|
|
will be created in a subsequent call to flink:vkCreateGraphicsPipelines
|
|
or flink:vkCreateComputePipelines.
|
|
* ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT specifies that the pipeline to
|
|
be created will be a child of a previously created parent pipeline.
|
|
ifdef::VK_KHX_device_group[]
|
|
ifdef::VK_KHX_multiview[]
|
|
* ename:VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT_KHX specifies
|
|
that any shader input variables decorated as code:DeviceIndex will be
|
|
assigned values as if they were decorated as code:ViewIndex.
|
|
endif::VK_KHX_multiview[]
|
|
* ename:VK_PIPELINE_CREATE_DISPATCH_BASE_KHX specifies that a compute
|
|
pipeline can: be used with flink:vkCmdDispatchBaseKHX with a non-zero
|
|
base workgroup.
|
|
endif::VK_KHX_device_group[]
|
|
|
|
It is valid to set both ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT and
|
|
ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT.
|
|
This allows a pipeline to be both a parent and possibly a child in a
|
|
pipeline hierarchy.
|
|
See <<pipelines-pipeline-derivatives,Pipeline Derivatives>> for more
|
|
information.
|
|
|
|
--
|
|
|
|
[open,refpage='VkPipelineDynamicStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline dynamic state',type='structs']
|
|
--
|
|
|
|
The sname:VkPipelineDynamicStateCreateInfo structure is defined as:
|
|
|
|
include::../api/structs/VkPipelineDynamicStateCreateInfo.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:flags is reserved for future use.
|
|
* pname:dynamicStateCount is the number of elements in the
|
|
pname:pDynamicStates array.
|
|
* pname:pDynamicStates is an array of elink:VkDynamicState values
|
|
specifying which pieces of pipeline state will use the values from
|
|
dynamic state commands rather than from pipeline state creation info.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkPipelineDynamicStateCreateInfo-pDynamicStates-01442]]
|
|
Each element of pname:pDynamicStates must: be unique
|
|
****
|
|
|
|
include::../validity/structs/VkPipelineDynamicStateCreateInfo.txt[]
|
|
--
|
|
|
|
[open,refpage='VkDynamicState',desc='Indicate which dynamic state is taken from dynamic state commands',type='enums']
|
|
--
|
|
|
|
The source of different pieces of dynamic state is specified by the
|
|
slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates property of the
|
|
currently active pipeline, each of whose elements must: be one of the
|
|
values:
|
|
|
|
include::../api/enums/VkDynamicState.txt[]
|
|
|
|
* ename:VK_DYNAMIC_STATE_VIEWPORT specifies that the pname:pViewports
|
|
state in sname:VkPipelineViewportStateCreateInfo will be ignored and
|
|
must: be set dynamically with flink:vkCmdSetViewport before any draw
|
|
commands.
|
|
The number of viewports used by a pipeline is still specified by the
|
|
pname:viewportCount member of sname:VkPipelineViewportStateCreateInfo.
|
|
* ename:VK_DYNAMIC_STATE_SCISSOR specifies that the pname:pScissors state
|
|
in sname:VkPipelineViewportStateCreateInfo will be ignored and must: be
|
|
set dynamically with flink:vkCmdSetScissor before any draw commands.
|
|
The number of scissor rectangles used by a pipeline is still specified
|
|
by the pname:scissorCount member of
|
|
sname:VkPipelineViewportStateCreateInfo.
|
|
* ename:VK_DYNAMIC_STATE_LINE_WIDTH specifies that the pname:lineWidth
|
|
state in sname:VkPipelineRasterizationStateCreateInfo will be ignored
|
|
and must: be set dynamically with flink:vkCmdSetLineWidth before any
|
|
draw commands that generate line primitives for the rasterizer.
|
|
* ename:VK_DYNAMIC_STATE_DEPTH_BIAS specifies that the
|
|
pname:depthBiasConstantFactor, pname:depthBiasClamp and
|
|
pname:depthBiasSlopeFactor states in
|
|
sname:VkPipelineRasterizationStateCreateInfo will be ignored and must:
|
|
be set dynamically with flink:vkCmdSetDepthBias before any draws are
|
|
performed with pname:depthBiasEnable in
|
|
sname:VkPipelineRasterizationStateCreateInfo set to ename:VK_TRUE.
|
|
* ename:VK_DYNAMIC_STATE_BLEND_CONSTANTS specifies that the
|
|
pname:blendConstants state in sname:VkPipelineColorBlendStateCreateInfo
|
|
will be ignored and must: be set dynamically with
|
|
flink:vkCmdSetBlendConstants before any draws are performed with a
|
|
pipeline state with sname:VkPipelineColorBlendAttachmentState member
|
|
pname:blendEnable set to ename:VK_TRUE and any of the blend functions
|
|
using a constant blend color.
|
|
* ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS specifies that the
|
|
pname:minDepthBounds and pname:maxDepthBounds states of
|
|
slink:VkPipelineDepthStencilStateCreateInfo will be ignored and must: be
|
|
set dynamically with flink:vkCmdSetDepthBounds before any draws are
|
|
performed with a pipeline state with
|
|
sname:VkPipelineDepthStencilStateCreateInfo member
|
|
pname:depthBoundsTestEnable set to ename:VK_TRUE.
|
|
* ename:VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK specifies that the
|
|
pname:compareMask state in sname:VkPipelineDepthStencilStateCreateInfo
|
|
for both pname:front and pname:back will be ignored and must: be set
|
|
dynamically with flink:vkCmdSetStencilCompareMask before any draws are
|
|
performed with a pipeline state with
|
|
sname:VkPipelineDepthStencilStateCreateInfo member
|
|
pname:stencilTestEnable set to ename:VK_TRUE
|
|
* ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK specifies that the
|
|
pname:writeMask state in sname:VkPipelineDepthStencilStateCreateInfo for
|
|
both pname:front and pname:back will be ignored and must: be set
|
|
dynamically with flink:vkCmdSetStencilWriteMask before any draws are
|
|
performed with a pipeline state with
|
|
sname:VkPipelineDepthStencilStateCreateInfo member
|
|
pname:stencilTestEnable set to ename:VK_TRUE
|
|
* ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE specifies that the
|
|
pname:reference state in sname:VkPipelineDepthStencilStateCreateInfo for
|
|
both pname:front and pname:back will be ignored and must: be set
|
|
dynamically with flink:vkCmdSetStencilReference before any draws are
|
|
performed with a pipeline state with
|
|
sname:VkPipelineDepthStencilStateCreateInfo member
|
|
pname:stencilTestEnable set to ename:VK_TRUE
|
|
ifdef::VK_NV_clip_space_w_scaling[]
|
|
* ename:VK_DYNAMIC_STATE_VIEWPORT_W_SCALING_NV specifies that the
|
|
pname:pViewportScalings state in
|
|
sname:VkPipelineViewportWScalingStateCreateInfoNV will be ignored and
|
|
must: be set dynamically with flink:vkCmdSetViewportWScalingNV before
|
|
any draws are performed with a pipeline state with
|
|
sname:VkPipelineViewportWScalingStateCreateInfo member
|
|
pname:viewportScalingEnable set to ename:VK_TRUE
|
|
endif::VK_NV_clip_space_w_scaling[]
|
|
ifdef::VK_EXT_discard_rectangles[]
|
|
* ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLES_EXT specifies that the
|
|
pname:pDiscardRectangles state in
|
|
slink:VkPipelineDiscardRectangleStateCreateInfoEXT will be ignored and
|
|
must: be set dynamically with flink:vkCmdSetDiscardRectangleEXT before
|
|
any draw or clear commands.
|
|
The elink:VkDiscardRectangleModeEXT and the number of active discard
|
|
rectangles is still specified by the pname:discardRectangleMode and
|
|
pname:discardRectangleCount members of
|
|
sname:VkPipelineDiscardRectangleStateCreateInfoEXT.
|
|
endif::VK_EXT_discard_rectangles[]
|
|
ifdef::VK_EXT_sample_locations[]
|
|
* ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT specifies that the
|
|
pname:sampleLocationsInfo state in
|
|
slink:VkPipelineSampleLocationsStateCreateInfoEXT will be ignored and
|
|
must: be set dynamically with flink:vkCmdSetSampleLocationsEXT before
|
|
any draw or clear commands.
|
|
Enabling custom sample locations is still indicated by the
|
|
pname:sampleLocationsEnable member of
|
|
sname:VkPipelineSampleLocationsStateCreateInfoEXT.
|
|
endif::VK_EXT_sample_locations[]
|
|
|
|
--
|
|
|
|
|
|
=== Valid Combinations of Stages for Graphics Pipelines
|
|
|
|
If tessellation shader stages are omitted, the tessellation shading and
|
|
fixed-function stages of the pipeline are skipped.
|
|
|
|
If a geometry shader is omitted, the geometry shading stage is skipped.
|
|
|
|
If a fragment shader is omitted, the results of fragment processing are
|
|
undefined.
|
|
Specifically, any fragment color outputs are considered to have undefined
|
|
values, and the fragment depth is considered to be unmodified.
|
|
This can: be useful for depth-only rendering.
|
|
|
|
Presence of a shader stage in a pipeline is indicated by including a valid
|
|
sname:VkPipelineShaderStageCreateInfo with pname:module and pname:pName
|
|
selecting an entry point from a shader module, where that entry point is
|
|
valid for the stage specified by pname:stage.
|
|
|
|
Presence of some of the fixed-function stages in the pipeline is implicitly
|
|
derived from enabled shaders and provided state.
|
|
For example, the fixed-function tessellator is always present when the
|
|
pipeline has valid Tessellation Control and Tessellation Evaluation shaders.
|
|
|
|
.For example:
|
|
* Depth/stencil-only rendering in a subpass with no color attachments
|
|
** Active Pipeline Shader Stages
|
|
*** Vertex Shader
|
|
** Required: Fixed-Function Pipeline Stages
|
|
*** slink:VkPipelineVertexInputStateCreateInfo
|
|
*** slink:VkPipelineInputAssemblyStateCreateInfo
|
|
*** slink:VkPipelineViewportStateCreateInfo
|
|
*** slink:VkPipelineRasterizationStateCreateInfo
|
|
*** slink:VkPipelineMultisampleStateCreateInfo
|
|
*** slink:VkPipelineDepthStencilStateCreateInfo
|
|
* Color-only rendering in a subpass with no depth/stencil attachment
|
|
** Active Pipeline Shader Stages
|
|
*** Vertex Shader
|
|
*** Fragment Shader
|
|
** Required: Fixed-Function Pipeline Stages
|
|
*** slink:VkPipelineVertexInputStateCreateInfo
|
|
*** slink:VkPipelineInputAssemblyStateCreateInfo
|
|
*** slink:VkPipelineViewportStateCreateInfo
|
|
*** slink:VkPipelineRasterizationStateCreateInfo
|
|
*** slink:VkPipelineMultisampleStateCreateInfo
|
|
*** slink:VkPipelineColorBlendStateCreateInfo
|
|
* Rendering pipeline with tessellation and geometry shaders
|
|
** Active Pipeline Shader Stages
|
|
*** Vertex Shader
|
|
*** Tessellation Control Shader
|
|
*** Tessellation Evaluation Shader
|
|
*** Geometry Shader
|
|
*** Fragment Shader
|
|
** Required: Fixed-Function Pipeline Stages
|
|
*** slink:VkPipelineVertexInputStateCreateInfo
|
|
*** slink:VkPipelineInputAssemblyStateCreateInfo
|
|
*** slink:VkPipelineTessellationStateCreateInfo
|
|
*** slink:VkPipelineViewportStateCreateInfo
|
|
*** slink:VkPipelineRasterizationStateCreateInfo
|
|
*** slink:VkPipelineMultisampleStateCreateInfo
|
|
*** slink:VkPipelineDepthStencilStateCreateInfo
|
|
*** slink:VkPipelineColorBlendStateCreateInfo
|
|
|
|
|
|
[[pipelines-destruction]]
|
|
== Pipeline destruction
|
|
|
|
[open,refpage='vkDestroyPipeline',desc='Destroy a pipeline object',type='protos']
|
|
--
|
|
|
|
To destroy a graphics or compute pipeline, call:
|
|
|
|
include::../api/protos/vkDestroyPipeline.txt[]
|
|
|
|
* pname:device is the logical device that destroys the pipeline.
|
|
* pname:pipeline is the handle of the pipeline to destroy.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkDestroyPipeline-pipeline-00765]]
|
|
All submitted commands that refer to pname:pipeline must: have completed
|
|
execution
|
|
* [[VUID-vkDestroyPipeline-pipeline-00766]]
|
|
If sname:VkAllocationCallbacks were provided when pname:pipeline was
|
|
created, a compatible set of callbacks must: be provided here
|
|
* [[VUID-vkDestroyPipeline-pipeline-00767]]
|
|
If no sname:VkAllocationCallbacks were provided when pname:pipeline was
|
|
created, pname:pAllocator must: be `NULL`
|
|
****
|
|
|
|
include::../validity/protos/vkDestroyPipeline.txt[]
|
|
--
|
|
|
|
|
|
[[pipelines-multiple]]
|
|
== Multiple Pipeline Creation
|
|
|
|
Multiple pipelines can: be created simultaneously by passing an array of
|
|
sname:VkGraphicsPipelineCreateInfo or sname:VkComputePipelineCreateInfo
|
|
structures into the flink:vkCreateGraphicsPipelines and
|
|
flink:vkCreateComputePipelines commands, respectively.
|
|
Applications can: group together similar pipelines to be created in a single
|
|
call, and implementations are encouraged to look for reuse opportunities
|
|
within a group-create.
|
|
|
|
When an application attempts to create many pipelines in a single command,
|
|
it is possible that some subset may: fail creation.
|
|
In that case, the corresponding entries in the pname:pPipelines output array
|
|
will be filled with dlink:VK_NULL_HANDLE values.
|
|
If any pipeline fails creation (for example, due to out of memory errors),
|
|
the ftext:vkCreate*Pipelines commands will return an error code.
|
|
The implementation will attempt to create all pipelines, and only return
|
|
dlink:VK_NULL_HANDLE values for those that actually failed.
|
|
|
|
|
|
[[pipelines-pipeline-derivatives]]
|
|
== Pipeline Derivatives
|
|
|
|
A pipeline derivative is a child pipeline created from a parent pipeline,
|
|
where the child and parent are expected to have much commonality.
|
|
The goal of derivative pipelines is that they be cheaper to create using the
|
|
parent as a starting point, and that it be more efficient (on either host or
|
|
device) to switch/bind between children of the same parent.
|
|
|
|
A derivative pipeline is created by setting the
|
|
ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag in the
|
|
stext:Vk*PipelineCreateInfo structure.
|
|
If this is set, then exactly one of pname:basePipelineHandle or
|
|
pname:basePipelineIndex members of the structure must: have a valid
|
|
handle/index, and indicates the parent pipeline.
|
|
If pname:basePipelineHandle is used, the parent pipeline must: have already
|
|
been created.
|
|
If pname:basePipelineIndex is used, then the parent is being created in the
|
|
same command.
|
|
dlink:VK_NULL_HANDLE acts as the invalid handle for
|
|
pname:basePipelineHandle, and -1 is the invalid index for
|
|
pname:basePipelineIndex.
|
|
If pname:basePipelineIndex is used, the base pipeline must: appear earlier
|
|
in the array.
|
|
The base pipeline must: have been created with the
|
|
ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set.
|
|
|
|
|
|
[[pipelines-cache]]
|
|
== Pipeline Cache
|
|
|
|
[open,refpage='VkPipelineCache',desc='Opaque handle to a pipeline cache object',type='handles']
|
|
--
|
|
|
|
Pipeline cache objects allow the result of pipeline construction to be
|
|
reused between pipelines and between runs of an application.
|
|
Reuse between pipelines is achieved by passing the same pipeline cache
|
|
object when creating multiple related pipelines.
|
|
Reuse across runs of an application is achieved by retrieving pipeline cache
|
|
contents in one run of an application, saving the contents, and using them
|
|
to preinitialize a pipeline cache on a subsequent run.
|
|
The contents of the pipeline cache objects are managed by the
|
|
implementation.
|
|
Applications can: manage the host memory consumed by a pipeline cache object
|
|
and control the amount of data retrieved from a pipeline cache object.
|
|
|
|
Pipeline cache objects are represented by sname:VkPipelineCache handles:
|
|
|
|
include::../api/handles/VkPipelineCache.txt[]
|
|
|
|
--
|
|
|
|
[open,refpage='vkCreatePipelineCache',desc='Creates a new pipeline cache',type='protos']
|
|
--
|
|
|
|
To create pipeline cache objects, call:
|
|
|
|
include::../api/protos/vkCreatePipelineCache.txt[]
|
|
|
|
* pname:device is the logical device that creates the pipeline cache
|
|
object.
|
|
* pname:pCreateInfo is a pointer to a sname:VkPipelineCacheCreateInfo
|
|
structure that contains the initial parameters for the pipeline cache
|
|
object.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
* pname:pPipelineCache is a pointer to a sname:VkPipelineCache handle in
|
|
which the resulting pipeline cache object is returned.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Applications can: track and manage the total host memory size of a pipeline
|
|
cache object using the pname:pAllocator.
|
|
Applications can: limit the amount of data retrieved from a pipeline cache
|
|
object in fname:vkGetPipelineCacheData.
|
|
Implementations should: not internally limit the total number of entries
|
|
added to a pipeline cache object or the total host memory consumed.
|
|
====
|
|
|
|
Once created, a pipeline cache can: be passed to the
|
|
fname:vkCreateGraphicsPipelines and fname:vkCreateComputePipelines commands.
|
|
If the pipeline cache passed into these commands is not
|
|
dlink:VK_NULL_HANDLE, the implementation will query it for possible reuse
|
|
opportunities and update it with new content.
|
|
The use of the pipeline cache object in these commands is internally
|
|
synchronized, and the same pipeline cache object can: be used in multiple
|
|
threads simultaneously.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Implementations should: make every effort to limit any critical sections to
|
|
the actual accesses to the cache, which is expected to be significantly
|
|
shorter than the duration of the fname:vkCreateGraphicsPipelines and
|
|
fname:vkCreateComputePipelines commands.
|
|
====
|
|
|
|
include::../validity/protos/vkCreatePipelineCache.txt[]
|
|
--
|
|
|
|
[open,refpage='VkPipelineCacheCreateInfo',desc='Structure specifying parameters of a newly created pipeline cache',type='structs']
|
|
--
|
|
|
|
The sname:VkPipelineCacheCreateInfo structure is defined as:
|
|
|
|
include::../api/structs/VkPipelineCacheCreateInfo.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:flags is reserved for future use.
|
|
* pname:initialDataSize is the number of bytes in pname:pInitialData.
|
|
If pname:initialDataSize is zero, the pipeline cache will initially be
|
|
empty.
|
|
* pname:pInitialData is a pointer to previously retrieved pipeline cache
|
|
data.
|
|
If the pipeline cache data is incompatible (as defined below) with the
|
|
device, the pipeline cache will be initially empty.
|
|
If pname:initialDataSize is zero, pname:pInitialData is ignored.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkPipelineCacheCreateInfo-initialDataSize-00768]]
|
|
If pname:initialDataSize is not `0`, it must: be equal to the size of
|
|
pname:pInitialData, as returned by fname:vkGetPipelineCacheData when
|
|
pname:pInitialData was originally retrieved
|
|
* [[VUID-VkPipelineCacheCreateInfo-initialDataSize-00769]]
|
|
If pname:initialDataSize is not `0`, pname:pInitialData must: have been
|
|
retrieved from a previous call to fname:vkGetPipelineCacheData
|
|
****
|
|
|
|
include::../validity/structs/VkPipelineCacheCreateInfo.txt[]
|
|
--
|
|
|
|
[open,refpage='vkMergePipelineCaches',desc='Combine the data stores of pipeline caches',type='protos']
|
|
--
|
|
|
|
Pipeline cache objects can: be merged using the command:
|
|
|
|
include::../api/protos/vkMergePipelineCaches.txt[]
|
|
|
|
* pname:device is the logical device that owns the pipeline cache objects.
|
|
* pname:dstCache is the handle of the pipeline cache to merge results
|
|
into.
|
|
* pname:srcCacheCount is the length of the pname:pSrcCaches array.
|
|
* pname:pSrcCaches is an array of pipeline cache handles, which will be
|
|
merged into pname:dstCache.
|
|
The previous contents of pname:dstCache are included after the merge.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
The details of the merge operation are implementation dependent, but
|
|
implementations should: merge the contents of the specified pipelines and
|
|
prune duplicate entries.
|
|
====
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkMergePipelineCaches-dstCache-00770]]
|
|
pname:dstCache must: not appear in the list of source caches
|
|
****
|
|
|
|
include::../validity/protos/vkMergePipelineCaches.txt[]
|
|
--
|
|
|
|
[open,refpage='vkGetPipelineCacheData',desc='Get the data store from a pipeline cache',type='protos']
|
|
--
|
|
|
|
Data can: be retrieved from a pipeline cache object using the command:
|
|
|
|
include::../api/protos/vkGetPipelineCacheData.txt[]
|
|
|
|
* pname:device is the logical device that owns the pipeline cache.
|
|
* pname:pipelineCache is the pipeline cache to retrieve data from.
|
|
* pname:pDataSize is a pointer to a value related to the amount of data in
|
|
the pipeline cache, as described below.
|
|
* pname:pData is either `NULL` or a pointer to a buffer.
|
|
|
|
If pname:pData is `NULL`, then the maximum size of the data that can: be
|
|
retrieved from the pipeline cache, in bytes, is returned in pname:pDataSize.
|
|
Otherwise, pname:pDataSize must: point to a variable set by the user to the
|
|
size of the buffer, in bytes, pointed to by pname:pData, and on return the
|
|
variable is overwritten with the amount of data actually written to
|
|
pname:pData.
|
|
|
|
If pname:pDataSize is less than the maximum size that can: be retrieved by
|
|
the pipeline cache, at most pname:pDataSize bytes will be written to
|
|
pname:pData, and fname:vkGetPipelineCacheData will return
|
|
ename:VK_INCOMPLETE.
|
|
Any data written to pname:pData is valid and can: be provided as the
|
|
pname:pInitialData member of the sname:VkPipelineCacheCreateInfo structure
|
|
passed to fname:vkCreatePipelineCache.
|
|
|
|
Two calls to fname:vkGetPipelineCacheData with the same parameters must:
|
|
retrieve the same data unless a command that modifies the contents of the
|
|
cache is called between them.
|
|
|
|
[[pipelines-cache-header]]
|
|
Applications can: store the data retrieved from the pipeline cache, and use
|
|
these data, possibly in a future run of the application, to populate new
|
|
pipeline cache objects.
|
|
The results of pipeline compiles, however, may: depend on the vendor ID,
|
|
device ID, driver version, and other details of the device.
|
|
To enable applications to detect when previously retrieved data is
|
|
incompatible with the device, the initial bytes written to pname:pData must:
|
|
be a header consisting of the following members:
|
|
|
|
.Layout for pipeline cache header version ename:VK_PIPELINE_CACHE_HEADER_VERSION_ONE
|
|
[width="85%",cols="8%,21%,71%",options="header"]
|
|
|====
|
|
| Offset | Size | Meaning
|
|
| 0 | 4 | length in bytes of the entire pipeline cache header
|
|
written as a stream of bytes, with the least
|
|
significant byte first
|
|
| 4 | 4 | a elink:VkPipelineCacheHeaderVersion value
|
|
written as a stream of bytes, with the least
|
|
significant byte first
|
|
| 8 | 4 | a vendor ID equal to
|
|
sname:VkPhysicalDeviceProperties::pname:vendorID
|
|
written as a stream of bytes, with the least
|
|
significant byte first
|
|
| 12 | 4 | a device ID equal to
|
|
sname:VkPhysicalDeviceProperties::pname:deviceID
|
|
written as a stream of bytes, with the least
|
|
significant byte first
|
|
| 16 | ename:VK_UUID_SIZE | a pipeline cache ID equal to
|
|
sname:VkPhysicalDeviceProperties::pname:pipelineCacheUUID
|
|
|====
|
|
|
|
The first four bytes encode the length of the entire pipeline cache header,
|
|
in bytes.
|
|
This value includes all fields in the header including the pipeline cache
|
|
version field and the size of the length field.
|
|
|
|
The next four bytes encode the pipeline cache version, as described for
|
|
elink:VkPipelineCacheHeaderVersion.
|
|
A consumer of the pipeline cache should: use the cache version to interpret
|
|
the remainder of the cache header.
|
|
|
|
If pname:pDataSize is less than what is necessary to store this header,
|
|
nothing will be written to pname:pData and zero will be written to
|
|
pname:pDataSize.
|
|
|
|
include::../validity/protos/vkGetPipelineCacheData.txt[]
|
|
--
|
|
|
|
[open,refpage='VkPipelineCacheHeaderVersion',desc='Encode pipeline cache version',type='enums',xrefs='vkCreatePipelineCache vkGetPipelineCacheData']
|
|
--
|
|
Possible values of the second group of four bytes in the header returned by
|
|
flink:vkGetPipelineCacheData, encoding the pipeline cache version, are:
|
|
|
|
include::../api/enums/VkPipelineCacheHeaderVersion.txt[]
|
|
|
|
* ename:VK_PIPELINE_CACHE_HEADER_VERSION_ONE specifies version one of the
|
|
pipeline cache.
|
|
--
|
|
|
|
[open,refpage='vkDestroyPipelineCache',desc='Destroy a pipeline cache object',type='protos']
|
|
--
|
|
|
|
To destroy a pipeline cache, call:
|
|
|
|
include::../api/protos/vkDestroyPipelineCache.txt[]
|
|
|
|
* pname:device is the logical device that destroys the pipeline cache
|
|
object.
|
|
* pname:pipelineCache is the handle of the pipeline cache to destroy.
|
|
* pname:pAllocator controls host memory allocation as described in the
|
|
<<memory-allocation, Memory Allocation>> chapter.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkDestroyPipelineCache-pipelineCache-00771]]
|
|
If sname:VkAllocationCallbacks were provided when pname:pipelineCache
|
|
was created, a compatible set of callbacks must: be provided here
|
|
* [[VUID-vkDestroyPipelineCache-pipelineCache-00772]]
|
|
If no sname:VkAllocationCallbacks were provided when pname:pipelineCache
|
|
was created, pname:pAllocator must: be `NULL`
|
|
****
|
|
|
|
include::../validity/protos/vkDestroyPipelineCache.txt[]
|
|
--
|
|
|
|
|
|
[[pipelines-specialization-constants]]
|
|
== Specialization Constants
|
|
|
|
Specialization constants are a mechanism whereby constants in a SPIR-V
|
|
module can: have their constant value specified at the time the
|
|
sname:VkPipeline is created.
|
|
This allows a SPIR-V module to have constants that can: be modified while
|
|
executing an application that uses the Vulkan API.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Specialization constants are useful to allow a compute shader to have its
|
|
local workgroup size changed at runtime by the user, for example.
|
|
====
|
|
|
|
Each instance of the sname:VkPipelineShaderStageCreateInfo structure
|
|
contains a parameter pname:pSpecializationInfo, which can: be `NULL` to
|
|
indicate no specialization constants, or point to a
|
|
sname:VkSpecializationInfo structure.
|
|
|
|
[open,refpage='VkSpecializationInfo',desc='Structure specifying specialization info',type='structs']
|
|
--
|
|
|
|
The sname:VkSpecializationInfo structure is defined as:
|
|
|
|
include::../api/structs/VkSpecializationInfo.txt[]
|
|
|
|
* pname:mapEntryCount is the number of entries in the pname:pMapEntries
|
|
array.
|
|
* pname:pMapEntries is a pointer to an array of
|
|
sname:VkSpecializationMapEntry which maps constant IDs to offsets in
|
|
pname:pData.
|
|
* pname:dataSize is the byte size of the pname:pData buffer.
|
|
* pname:pData contains the actual constant values to specialize with.
|
|
|
|
pname:pMapEntries points to a structure of type
|
|
slink:VkSpecializationMapEntry.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkSpecializationInfo-offset-00773]]
|
|
The pname:offset member of each element of pname:pMapEntries must: be
|
|
less than pname:dataSize
|
|
* [[VUID-VkSpecializationInfo-pMapEntries-00774]]
|
|
The pname:size member of each element of pname:pMapEntries must: be less
|
|
than or equal to pname:dataSize minus pname:offset
|
|
* [[VUID-VkSpecializationInfo-mapEntryCount-00775]]
|
|
If pname:mapEntryCount is not `0`, pname:pMapEntries must: be a valid
|
|
pointer to an array of pname:mapEntryCount valid
|
|
sname:VkSpecializationMapEntry structures
|
|
****
|
|
|
|
include::../validity/structs/VkSpecializationInfo.txt[]
|
|
--
|
|
|
|
[open,refpage='VkSpecializationMapEntry',desc='Structure specifying a specialization map entry',type='structs']
|
|
--
|
|
|
|
The sname:VkSpecializationMapEntry structure is defined as:
|
|
|
|
include::../api/structs/VkSpecializationMapEntry.txt[]
|
|
|
|
* pname:constantID is the ID of the specialization constant in SPIR-V.
|
|
* pname:offset is the byte offset of the specialization constant value
|
|
within the supplied data buffer.
|
|
* pname:size is the byte size of the specialization constant value within
|
|
the supplied data buffer.
|
|
|
|
If a pname:constantID value is not a specialization constant ID used in the
|
|
shader, that map entry does not affect the behavior of the pipeline.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-VkSpecializationMapEntry-constantID-00776]]
|
|
For a pname:constantID specialization constant declared in a shader,
|
|
pname:size must: match the byte size of the pname:constantID.
|
|
If the specialization constant is of type code:boolean, pname:size must:
|
|
be the byte size of basetype:VkBool32
|
|
****
|
|
|
|
include::../validity/structs/VkSpecializationMapEntry.txt[]
|
|
--
|
|
|
|
In human readable SPIR-V:
|
|
|
|
[source,glsl]
|
|
---------------------------------------------------
|
|
OpDecorate %x SpecId 13 ; decorate .x component of WorkgroupSize with ID 13
|
|
OpDecorate %y SpecId 42 ; decorate .y component of WorkgroupSize with ID 42
|
|
OpDecorate %z SpecId 3 ; decorate .z component of WorkgroupSize with ID 3
|
|
OpDecorate %wgsize BuiltIn WorkgroupSize ; decorate WorkgroupSize onto constant
|
|
%i32 = OpTypeInt 32 0 ; declare an unsigned 32-bit type
|
|
%uvec3 = OpTypeVector %i32 3 ; declare a 3 element vector type of unsigned 32-bit
|
|
%x = OpSpecConstant %i32 1 ; declare the .x component of WorkgroupSize
|
|
%y = OpSpecConstant %i32 1 ; declare the .y component of WorkgroupSize
|
|
%z = OpSpecConstant %i32 1 ; declare the .z component of WorkgroupSize
|
|
%wgsize = OpSpecConstantComposite %uvec3 %x %y %z ; declare WorkgroupSize
|
|
---------------------------------------------------
|
|
|
|
From the above we have three specialization constants, one for each of the
|
|
x, y & z elements of the WorkgroupSize vector.
|
|
|
|
Now to specialize the above via the specialization constants mechanism:
|
|
|
|
[source,c++]
|
|
---------------------------------------------------
|
|
const VkSpecializationMapEntry entries[] =
|
|
{
|
|
{
|
|
13, // constantID
|
|
0 * sizeof(uint32_t), // offset
|
|
sizeof(uint32_t) // size
|
|
},
|
|
{
|
|
42, // constantID
|
|
1 * sizeof(uint32_t), // offset
|
|
sizeof(uint32_t) // size
|
|
},
|
|
{
|
|
3, // constantID
|
|
2 * sizeof(uint32_t), // offset
|
|
sizeof(uint32_t) // size
|
|
}
|
|
};
|
|
|
|
const uint32_t data[] = { 16, 8, 4 }; // our workgroup size is 16x8x4
|
|
|
|
const VkSpecializationInfo info =
|
|
{
|
|
3, // mapEntryCount
|
|
entries, // pMapEntries
|
|
3 * sizeof(uint32_t), // dataSize
|
|
data, // pData
|
|
};
|
|
---------------------------------------------------
|
|
|
|
Then when calling flink:vkCreateComputePipelines, and passing the
|
|
sname:VkSpecializationInfo we defined as the pname:pSpecializationInfo
|
|
parameter of slink:VkPipelineShaderStageCreateInfo, we will create a compute
|
|
pipeline with the runtime specified local workgroup size.
|
|
|
|
Another example would be that an application has a SPIR-V module that has
|
|
some platform-dependent constants they wish to use.
|
|
|
|
In human readable SPIR-V:
|
|
|
|
// [source,glsl]
|
|
[source,glsl]
|
|
---------------------------------------------------
|
|
OpDecorate %1 SpecId 0 ; decorate our signed 32-bit integer constant
|
|
OpDecorate %2 SpecId 12 ; decorate our 32-bit floating-point constant
|
|
%i32 = OpTypeInt 32 1 ; declare a signed 32-bit type
|
|
%float = OpTypeFloat 32 ; declare a 32-bit floating-point type
|
|
%1 = OpSpecConstant %i32 -1 ; some signed 32-bit integer constant
|
|
%2 = OpSpecConstant %float 0.5 ; some 32-bit floating-point constant
|
|
---------------------------------------------------
|
|
|
|
From the above we have two specialization constants, one is a signed 32-bit
|
|
integer and the second is a 32-bit floating-point.
|
|
|
|
Now to specialize the above via the specialization constants mechanism:
|
|
|
|
[source,c++]
|
|
---------------------------------------------------
|
|
struct SpecializationData {
|
|
int32_t data0;
|
|
float data1;
|
|
};
|
|
|
|
const VkSpecializationMapEntry entries[] =
|
|
{
|
|
{
|
|
0, // constantID
|
|
offsetof(SpecializationData, data0), // offset
|
|
sizeof(SpecializationData::data0) // size
|
|
},
|
|
{
|
|
12, // constantID
|
|
offsetof(SpecializationData, data1), // offset
|
|
sizeof(SpecializationData::data1) // size
|
|
}
|
|
};
|
|
|
|
SpecializationData data;
|
|
data.data0 = -42; // set the data for the 32-bit integer
|
|
data.data1 = 42.0f; // set the data for the 32-bit floating-point
|
|
|
|
const VkSpecializationInfo info =
|
|
{
|
|
2, // mapEntryCount
|
|
entries, // pMapEntries
|
|
sizeof(data), // dataSize
|
|
&data, // pData
|
|
};
|
|
---------------------------------------------------
|
|
|
|
It is legal for a SPIR-V module with specializations to be compiled into a
|
|
pipeline where no specialization info was provided.
|
|
SPIR-V specialization constants contain default values such that if a
|
|
specialization is not provided, the default value will be used.
|
|
In the examples above, it would be valid for an application to only
|
|
specialize some of the specialization constants within the SPIR-V module,
|
|
and let the other constants use their default values encoded within the
|
|
OpSpecConstant declarations.
|
|
|
|
|
|
[[pipelines-binding]]
|
|
== Pipeline Binding
|
|
|
|
[open,refpage='vkCmdBindPipeline',desc='Bind a pipeline object to a command buffer',type='protos']
|
|
--
|
|
|
|
Once a pipeline has been created, it can: be bound to the command buffer
|
|
using the command:
|
|
|
|
include::../api/protos/vkCmdBindPipeline.txt[]
|
|
|
|
* pname:commandBuffer is the command buffer that the pipeline will be
|
|
bound to.
|
|
* pname:pipelineBindPoint is a elink:VkPipelineBindPoint value specifying
|
|
whether to bind to the compute or graphics bind point.
|
|
Binding one does not disturb the other.
|
|
* pname:pipeline is the pipeline to be bound.
|
|
|
|
Once bound, a pipeline binding affects subsequent graphics or compute
|
|
commands in the command buffer until a different pipeline is bound to the
|
|
bind point.
|
|
The pipeline bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE controls the
|
|
behavior of flink:vkCmdDispatch and flink:vkCmdDispatchIndirect.
|
|
The pipeline bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS controls the
|
|
behavior of all <<drawing, drawing commands>>.
|
|
No other commands are affected by the pipeline state.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkCmdBindPipeline-pipelineBindPoint-00777]]
|
|
If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_COMPUTE, the
|
|
sname:VkCommandPool that pname:commandBuffer was allocated from must:
|
|
support compute operations
|
|
* [[VUID-vkCmdBindPipeline-pipelineBindPoint-00778]]
|
|
If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_GRAPHICS, the
|
|
sname:VkCommandPool that pname:commandBuffer was allocated from must:
|
|
support graphics operations
|
|
* [[VUID-vkCmdBindPipeline-pipelineBindPoint-00779]]
|
|
If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_COMPUTE,
|
|
pname:pipeline must: be a compute pipeline
|
|
* [[VUID-vkCmdBindPipeline-pipelineBindPoint-00780]]
|
|
If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_GRAPHICS,
|
|
pname:pipeline must: be a graphics pipeline
|
|
* [[VUID-vkCmdBindPipeline-pipeline-00781]]
|
|
If the <<features-features-variableMultisampleRate,variable multisample
|
|
rate>> feature is not supported, pname:pipeline is a graphics pipeline,
|
|
the current subpass has no attachments, and this is not the first call
|
|
to this function with a graphics pipeline after transitioning to the
|
|
current subpass, then the sample count specified by this pipeline must:
|
|
match that set in the previous pipeline
|
|
ifdef::VK_EXT_sample_locations[]
|
|
* [[VUID-vkCmdBindPipeline-variableSampleLocations-01525]]
|
|
If
|
|
slink:VkPhysicalDeviceSampleLocationsPropertiesEXT::pname:variableSampleLocations
|
|
is ename:VK_FALSE, and pname:pipeline is a graphics pipeline created
|
|
with a slink:VkPipelineSampleLocationsStateCreateInfoEXT structure
|
|
having its pname:sampleLocationsEnable member set to ename:VK_TRUE but
|
|
without ename:VK_DYNAMIC_STATE_SAMPLE_LOCATIONS_EXT enabled then the
|
|
current render pass instance must: have been begun by specifying a
|
|
slink:VkRenderPassSampleLocationsBeginInfoEXT structure whose
|
|
pname:pPostSubpassSampleLocations member contains an element with a
|
|
pname:subpassIndex matching the current subpass index and the
|
|
pname:sampleLocationsInfo member of that element must: match the
|
|
pname:sampleLocationsInfo specified in
|
|
slink:VkPipelineSampleLocationsStateCreateInfoEXT when the pipeline was
|
|
created
|
|
endif::VK_EXT_sample_locations[]
|
|
****
|
|
|
|
include::../validity/protos/vkCmdBindPipeline.txt[]
|
|
--
|
|
|
|
[open,refpage='VkPipelineBindPoint',desc='Specify the bind point of a pipeline object to a command buffer',type='enums']
|
|
--
|
|
|
|
Possible values of flink:vkCmdBindPipeline::pname:pipelineBindPoint,
|
|
specifying the bind point of a pipeline object, are:
|
|
|
|
include::../api/enums/VkPipelineBindPoint.txt[]
|
|
|
|
* ename:VK_PIPELINE_BIND_POINT_COMPUTE specifies binding as a compute
|
|
pipeline.
|
|
* ename:VK_PIPELINE_BIND_POINT_GRAPHICS specifies binding as a graphics
|
|
pipeline.
|
|
|
|
--
|
|
|
|
ifdef::VK_AMD_shader_info[]
|
|
include::VK_AMD_shader_info.txt[]
|
|
endif::VK_AMD_shader_info[]
|