| // Copyright 2015-2021 The Khronos Group, Inc. |
| // |
| // SPDX-License-Identifier: CC-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_, |
| ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] |
| a _ray tracing pipeline_, |
| endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] |
| or a _compute pipeline_. |
| |
| ifdef::VK_NV_mesh_shader[] |
| The graphics pipeline can be operated in two modes, as either _primitive |
| shading_ or _mesh shading_ pipeline. |
| |
| *Primitive Shading* |
| |
| endif::VK_NV_mesh_shader[] |
| |
| 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. |
| |
| ifdef::VK_NV_mesh_shader[] |
| *Mesh Shading* |
| |
| When using the <<mesh,_mesh shading_>> pipeline input primitives are not |
| assembled implicitly, but explicitly through the (<<shaders-mesh,Mesh |
| Shader>>). |
| The work on the mesh pipeline is initiated by the application |
| <<drawing-mesh-shading,drawing>> a set of mesh tasks. |
| |
| If an optional (<<shaders-task,Task Shader>>) is active, each task triggers |
| the execution of a task shader workgroup that will generate a new set of |
| tasks upon completion. |
| Each of these spawned tasks, or each of the original dispatched tasks if no |
| task shader is present, triggers the execution of a mesh shader workgroup |
| that produces an output mesh with a variable-sized number of primitives |
| assembled from vertices stored in the output mesh. |
| |
| *Common* |
| endif::VK_NV_mesh_shader[] |
| |
| 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 _fragments_ associated with a region of |
| the framebuffer, from a two-dimensional description of a point, line |
| segment, or triangle. |
| These fragments are processed by <<fragops,fragment operations>> to |
| determine whether generated values will be written to the framebuffer. |
| <<fragops-shader, Fragment shading>> determines the values to be written to |
| the framebuffer attachments. |
| Framebuffer operations then 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]] |
| ifndef::VK_NV_mesh_shader[] |
| image::{images}/pipeline.svg[title="Block diagram of the Vulkan pipeline",align="center",opts="{imageopts}"] |
| endif::VK_NV_mesh_shader[] |
| ifdef::VK_NV_mesh_shader[] |
| image::{images}/pipelinemesh.svg[title="Block diagram of the Vulkan pipeline",align="center",opts="{imageopts}"] |
| endif::VK_NV_mesh_shader[] |
| |
| 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 current state using |
| flink:vkCmdBindPipeline. |
| Any pipeline object state that is specified as <<pipelines-dynamic-state, |
| dynamic>> is not applied to the current state when the pipeline object is |
| bound, but is instead set by dynamic state setting commands. |
| |
| No state, including dynamic state, is inherited from one command buffer to |
| another. |
| |
| |
| [open,refpage='VkPipeline',desc='Opaque handle to a pipeline object',type='handles'] |
| -- |
| Compute, |
| ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] |
| ray tracing, |
| endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] |
| and graphics pipelines are each represented by sname:VkPipeline handles: |
| |
| include::{generated}/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 slink:VkPipelineShaderStageCreateInfo structure |
| contained within the slink:VkComputePipelineCreateInfo structure. |
| |
| [open,refpage='vkCreateComputePipelines',desc='Creates a new compute pipeline object',type='protos'] |
| -- |
| To create compute pipelines, call: |
| |
| include::{generated}/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 a pointer to an array of |
| slink: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 of slink:VkPipeline handles 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 |
| ifdef::VK_EXT_pipeline_creation_cache_control[] |
| * [[VUID-vkCreateComputePipelines-pipelineCache-02873]] |
| If pname:pipelineCache was created with |
| ename:VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT, host |
| access to pname:pipelineCache must: be |
| <<fundamentals-threadingbehavior,externally synchronized>> |
| endif::VK_EXT_pipeline_creation_cache_control[] |
| **** |
| |
| include::{generated}/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::{generated}/api/structs/VkComputePipelineCreateInfo.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is a bitmask of elink:VkPipelineCreateFlagBits specifying |
| how the pipeline will be generated. |
| * pname:stage is a slink:VkPipelineShaderStageCreateInfo structure |
| 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>>. |
| |
| .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 |
| ifdef::VK_KHR_pipeline_library[] |
| * [[VUID-VkComputePipelineCreateInfo-flags-03364]] |
| pname:flags must: not include ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR |
| endif::VK_KHR_pipeline_library[] |
| ifdef::VK_KHR_ray_tracing_pipeline[] |
| * [[VUID-VkComputePipelineCreateInfo-flags-03365]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR |
| * [[VUID-VkComputePipelineCreateInfo-flags-03366]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR |
| * [[VUID-VkComputePipelineCreateInfo-flags-03367]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR |
| * [[VUID-VkComputePipelineCreateInfo-flags-03368]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR |
| * [[VUID-VkComputePipelineCreateInfo-flags-03369]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR |
| * [[VUID-VkComputePipelineCreateInfo-flags-03370]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR |
| * [[VUID-VkComputePipelineCreateInfo-flags-03576]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR |
| endif::VK_KHR_ray_tracing_pipeline[] |
| ifdef::VK_NV_ray_tracing_motion_blur[] |
| * [[VUID-VkComputePipelineCreateInfo-flags-04945]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV |
| endif::VK_NV_ray_tracing_motion_blur[] |
| ifdef::VK_NV_device_generated_commands[] |
| * [[VUID-VkComputePipelineCreateInfo-flags-02874]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV |
| endif::VK_NV_device_generated_commands[] |
| ifdef::VK_EXT_pipeline_creation_cache_control[] |
| * [[VUID-VkComputePipelineCreateInfo-pipelineCreationCacheControl-02875]] |
| If the <<features-pipelineCreationCacheControl, |
| pname:pipelineCreationCacheControl>> feature is not enabled, pname:flags |
| must: not include |
| ename:VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT or |
| ename:VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT |
| endif::VK_EXT_pipeline_creation_cache_control[] |
| **** |
| |
| include::{generated}/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::{generated}/api/structs/VkPipelineShaderStageCreateInfo.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is a bitmask of elink:VkPipelineShaderStageCreateFlagBits |
| specifying how the pipeline shader stage will be generated. |
| * pname:stage is a elink:VkShaderStageFlagBits value specifying a single |
| pipeline stage. |
| * pname:module is a slink:VkShaderModule object containing 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 a slink:VkSpecializationInfo |
| structure, as described in |
| <<pipelines-specialization-constants,Specialization Constants>>, or |
| `NULL`. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkPipelineShaderStageCreateInfo-stage-00704]] |
| If the <<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-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 |
| ifdef::VK_NV_mesh_shader[] |
| * [[VUID-VkPipelineShaderStageCreateInfo-stage-02091]] |
| If the <<features-meshShader,mesh shader>> feature is not enabled, |
| pname:stage must: not be ename:VK_SHADER_STAGE_MESH_BIT_NV |
| * [[VUID-VkPipelineShaderStageCreateInfo-stage-02092]] |
| If the <<features-taskShader,task shader>> feature is not enabled, |
| pname:stage must: not be ename:VK_SHADER_STAGE_TASK_BIT_NV |
| endif::VK_NV_mesh_shader[] |
| * [[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-02596]] |
| If pname:stage is a |
| <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader |
| stage>>, 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-02597]] |
| If pname:stage is a |
| <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader |
| stage>>, 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[] |
| ifdef::VK_NV_mesh_shader[] |
| * [[VUID-VkPipelineShaderStageCreateInfo-stage-02093]] |
| If pname:stage is ename:VK_SHADER_STAGE_MESH_BIT_NV, the identified |
| entry point must: have an code:OpExecutionMode instruction that |
| specifies a maximum output vertex count, code:OutputVertices, that is |
| greater than `0` and less than or equal to |
| sname:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshOutputVertices |
| * [[VUID-VkPipelineShaderStageCreateInfo-stage-02094]] |
| If pname:stage is ename:VK_SHADER_STAGE_MESH_BIT_NV, the identified |
| entry point must: have an code:OpExecutionMode instruction that |
| specifies a maximum output primitive count, code:OutputPrimitivesNV, |
| that is greater than `0` and less than or equal to |
| sname:VkPhysicalDeviceMeshShaderPropertiesNV::pname:maxMeshOutputPrimitives |
| endif::VK_NV_mesh_shader[] |
| ifdef::VK_EXT_subgroup_size_control[] |
| * [[VUID-VkPipelineShaderStageCreateInfo-flags-02784]] |
| If pname:flags has the |
| ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT |
| flag set, the <<features-subgroupSizeControl, |
| pname:subgroupSizeControl>> feature must: be enabled |
| * [[VUID-VkPipelineShaderStageCreateInfo-flags-02785]] |
| If pname:flags has the |
| ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT |
| flag set, the <<features-computeFullSubgroups, |
| pname:computeFullSubgroups>> feature must: be enabled |
| * [[VUID-VkPipelineShaderStageCreateInfo-pNext-02754]] |
| If a slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT |
| structure is included in the pname:pNext chain, pname:flags must: not |
| have the |
| ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT |
| flag set |
| * [[VUID-VkPipelineShaderStageCreateInfo-pNext-02755]] |
| If a slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT |
| structure is included in the pname:pNext chain, the |
| <<features-subgroupSizeControl, pname:subgroupSizeControl>> feature |
| must: be enabled, and pname:stage must: be a valid bit specified in |
| <<limits-required-subgroup-size-stages, |
| pname:requiredSubgroupSizeStages>> |
| * [[VUID-VkPipelineShaderStageCreateInfo-pNext-02756]] |
| If a slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT |
| structure is included in the pname:pNext chain and pname:stage is |
| ename:VK_SHADER_STAGE_COMPUTE_BIT, the local workgroup size of the |
| shader must: be less than or equal to the product of |
| slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT::pname:requiredSubgroupSize |
| and |
| <<limits-max-subgroups-per-workgroup,pname:maxComputeWorkgroupSubgroups>> |
| * [[VUID-VkPipelineShaderStageCreateInfo-pNext-02757]] |
| If a slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT |
| structure is included in the pname:pNext chain, and pname:flags has the |
| ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT |
| flag set, the local workgroup size in the X dimension of the pipeline |
| must: be a multiple of |
| slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT::pname:requiredSubgroupSize |
| * [[VUID-VkPipelineShaderStageCreateInfo-flags-02758]] |
| If pname:flags has both the |
| ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT and |
| ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT |
| flags set, the local workgroup size in the X dimension of the pipeline |
| must: be a multiple of |
| <<limits-max-subgroup-size,pname:maxSubgroupSize>> |
| * [[VUID-VkPipelineShaderStageCreateInfo-flags-02759]] |
| If pname:flags has the |
| ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT |
| flag set and pname:flags does not have the |
| ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT |
| flag set and no |
| slink:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT structure |
| is included in the pname:pNext chain, the local workgroup size in the X |
| dimension of the pipeline must: be a multiple of |
| <<limits-subgroup-size,pname:subgroupSize>> |
| endif::VK_EXT_subgroup_size_control[] |
| * [[VUID-VkPipelineShaderStageCreateInfo-module-04145]] |
| The SPIR-V code that was used to create pname:module must: be valid as |
| described by the <<spirv-spec,Khronos SPIR-V Specification>> after |
| applying the specializations provided in pname:pSpecializationInfo, if |
| any, and then converting all specialization constants into fixed |
| constants |
| **** |
| |
| include::{generated}/validity/structs/VkPipelineShaderStageCreateInfo.txt[] |
| -- |
| |
| [open,refpage='VkPipelineShaderStageCreateFlags',desc='Bitmask of VkPipelineShaderStageCreateFlagBits',type='flags'] |
| -- |
| include::{generated}/api/flags/VkPipelineShaderStageCreateFlags.txt[] |
| |
| tname:VkPipelineShaderStageCreateFlags is a bitmask type for setting a mask |
| of zero or more elink:VkPipelineShaderStageCreateFlagBits. |
| -- |
| |
| [open,refpage='VkPipelineShaderStageCreateFlagBits',desc='Bitmask controlling how a pipeline shader stage is created',type='enums'] |
| -- |
| Possible values of the pname:flags member of |
| slink:VkPipelineShaderStageCreateInfo specifying how a pipeline shader stage |
| is created, are: |
| |
| include::{generated}/api/enums/VkPipelineShaderStageCreateFlagBits.txt[] |
| |
| ifdef::VK_EXT_subgroup_size_control[] |
| * ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT |
| specifies that the |
| <<interfaces-builtin-variables-sgs,code:SubgroupSize>> may: vary in the |
| shader stage. |
| * ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT |
| specifies that the subgroup sizes must: be launched with all invocations |
| active in the compute stage. |
| |
| [NOTE] |
| .Note |
| ==== |
| If ename:VK_PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT |
| and ename:VK_PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT are |
| specified and <<limits-max-subgroup-size,pname:minSubgroupSize>> does not |
| equal <<limits-max-subgroup-size,pname:maxSubgroupSize>> and no |
| <<pipelines-required-subgroup-size, required subgroup size>> is specified, |
| then the only way to guarantee that the 'X' dimension of the local workgroup |
| size is a multiple of <<interfaces-builtin-variables-sgs,code:SubgroupSize>> |
| is to make it a multiple of pname:maxSubgroupSize. |
| Under these conditions, you are guaranteed full subgroups but not any |
| particular subgroup size. |
| ==== |
| |
| endif::VK_EXT_subgroup_size_control[] |
| -- |
| |
| [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::{generated}/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. |
| ifdef::VK_NV_mesh_shader[] |
| * ename:VK_SHADER_STAGE_TASK_BIT_NV specifies the task stage. |
| * ename:VK_SHADER_STAGE_MESH_BIT_NV specifies the mesh stage. |
| endif::VK_NV_mesh_shader[] |
| ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] |
| * ename:VK_SHADER_STAGE_RAYGEN_BIT_KHR specifies the ray generation stage. |
| * ename:VK_SHADER_STAGE_ANY_HIT_BIT_KHR specifies the any-hit stage. |
| * ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR specifies the closest hit |
| stage. |
| * ename:VK_SHADER_STAGE_MISS_BIT_KHR specifies the miss stage. |
| * ename:VK_SHADER_STAGE_INTERSECTION_BIT_KHR specifies the intersection |
| stage. |
| * ename:VK_SHADER_STAGE_CALLABLE_BIT_KHR specifies the callable stage. |
| endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] |
| |
| [NOTE] |
| .Note |
| ==== |
| ename:VK_SHADER_STAGE_ALL_GRAPHICS only includes the original five graphics |
| stages included in Vulkan 1.0, and not any stages added by extensions. |
| Thus, it may not have the desired effect in all cases. |
| ==== |
| -- |
| |
| [open,refpage='VkShaderStageFlags',desc='Bitmask of VkShaderStageFlagBits',type='flags'] |
| -- |
| include::{generated}/api/flags/VkShaderStageFlags.txt[] |
| |
| tname:VkShaderStageFlags is a bitmask type for setting a mask of zero or |
| more elink:VkShaderStageFlagBits. |
| -- |
| |
| ifdef::VK_EXT_subgroup_size_control[] |
| [open,refpage='VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT',desc='Structure specifying the required subgroup size of a newly created pipeline shader stage',type='structs'] |
| -- |
| The sname:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT structure |
| is defined as: |
| |
| include::{generated}/api/structs/VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT.txt[] |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * [[pipelines-required-subgroup-size]] pname:requiredSubgroupSize is an |
| unsigned integer value that specifies the required subgroup size for the |
| newly created pipeline shader stage. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT-requiredSubgroupSize-02760]] |
| pname:requiredSubgroupSize must: be a power-of-two integer |
| * [[VUID-VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT-requiredSubgroupSize-02761]] |
| pname:requiredSubgroupSize must: be greater or equal to |
| <<limits-min-subgroup-size,minSubgroupSize>> |
| * [[VUID-VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT-requiredSubgroupSize-02762]] |
| pname:requiredSubgroupSize must: be less than or equal to |
| <<limits-max-subgroup-size,maxSubgroupSize>> |
| **** |
| |
| |
| If a sname:VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT structure |
| is included in the pname:pNext chain of |
| slink:VkPipelineShaderStageCreateInfo, it specifies that the pipeline shader |
| stage being compiled has a required subgroup size. |
| |
| include::{generated}/validity/structs/VkPipelineShaderStageRequiredSubgroupSizeCreateInfoEXT.txt[] |
| -- |
| endif::VK_EXT_subgroup_size_control[] |
| |
| ifdef::VK_HUAWEI_subpass_shading[] |
| [open,refpage='VkSubpassShadingPipelineCreateInfoHUAWEI',desc='Structure specifying parameters of a newly created subpass shading pipeline',type='structs'] |
| -- |
| A subpass shading pipeline is a compute pipeline which must: be called only |
| in a subpass of a render pass with work dimensions specified by render area |
| size. |
| The subpass shading pipeline shader is a compute shader allowed to access |
| input attachments specified in the calling subpass. |
| To create a subpass shading pipeline, call flink:vkCreateComputePipelines |
| with slink:VkSubpassShadingPipelineCreateInfoHUAWEI in the pname:pNext chain |
| of slink:VkComputePipelineCreateInfo. |
| |
| The sname:VkSubpassShadingPipelineCreateInfoHUAWEI structure is defined as: |
| |
| include::{generated}/api/structs/VkSubpassShadingPipelineCreateInfoHUAWEI.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * 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 a render pass instance 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. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkSubpassShadingPipelineCreateInfoHUAWEI-subpass-04946]] |
| pname:subpass must: be created with |
| ename:VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI bind point |
| **** |
| |
| include::{generated}/validity/structs/VkSubpassShadingPipelineCreateInfoHUAWEI.txt[] |
| -- |
| |
| [open,refpage='vkGetDeviceSubpassShadingMaxWorkgroupSizeHUAWEI',desc='Query maximum supported subpass shading workgroup size for a give render pass',type='protos'] |
| -- |
| A subpass shading pipeline's workgroup size is a 2D vector with number of |
| power-of-two in width and height. |
| The maximum number of width and height is implementation dependent, and may: |
| vary for different formats and sample counts of attachments in a render |
| pass. |
| |
| To query the maximum workgroup size, call: |
| |
| include::{generated}/api/protos/vkGetDeviceSubpassShadingMaxWorkgroupSizeHUAWEI.txt[] |
| |
| * pname:device is a handle to a local device object that was used to |
| create the given render pass. |
| * 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 a render pass instance compatible |
| with the one provided. |
| See <<renderpass-compatibility,Render Pass Compatibility>> for more |
| information. |
| * pname:pMaxWorkgroupSize is a pointer to a slink:VkExtent2D structure. |
| |
| include::{generated}/validity/protos/vkGetDeviceSubpassShadingMaxWorkgroupSizeHUAWEI.txt[] |
| -- |
| endif::VK_HUAWEI_subpass_shading[] |
| |
| |
| [[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::{generated}/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 a pointer to an array of |
| slink: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 of slink:VkPipeline handles in |
| which the resulting graphics pipeline objects are returned. |
| |
| The slink:VkGraphicsPipelineCreateInfo structure includes an array of |
| slink:VkPipelineShaderStageCreateInfo structures for each of the desired |
| active shader stages, as well as creation information for 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 |
| ifdef::VK_EXT_pipeline_creation_cache_control[] |
| * [[VUID-vkCreateGraphicsPipelines-pipelineCache-02876]] |
| If pname:pipelineCache was created with |
| ename:VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT, host |
| access to pname:pipelineCache must: be |
| <<fundamentals-threadingbehavior,externally synchronized>> |
| endif::VK_EXT_pipeline_creation_cache_control[] |
| **** |
| |
| ifdef::VK_EXT_pipeline_creation_cache_control[] |
| [NOTE] |
| .Note |
| ==== |
| An implicit cache may be provided by the implementation or a layer. |
| For this reason, it is still valid to set |
| ename:VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT on |
| pname:flags for any element of pname:pCreateInfos while passing |
| dlink:VK_NULL_HANDLE for pname:pipelineCache. |
| ==== |
| endif::VK_EXT_pipeline_creation_cache_control[] |
| |
| include::{generated}/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::{generated}/api/structs/VkGraphicsPipelineCreateInfo.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is a bitmask of elink:VkPipelineCreateFlagBits specifying |
| how the pipeline will be generated. |
| * pname:stageCount is the number of entries in the pname:pStages array. |
| * pname:pStages is a pointer to an array of pname:stageCount |
| slink:VkPipelineShaderStageCreateInfo structures describing the set of |
| the shader stages to be included in the graphics pipeline. |
| * pname:pVertexInputState is a pointer to a |
| slink:VkPipelineVertexInputStateCreateInfo structure. |
| ifdef::VK_NV_mesh_shader[] |
| It is ignored if the pipeline includes a mesh shader stage. |
| endif::VK_NV_mesh_shader[] |
| ifdef::VK_EXT_vertex_input_dynamic_state[] |
| It is ignored if the pipeline is created with the |
| ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT dynamic state set. |
| endif::VK_EXT_vertex_input_dynamic_state[] |
| * pname:pInputAssemblyState is a pointer to a |
| slink:VkPipelineInputAssemblyStateCreateInfo structure which determines |
| input assembly behavior, as described in <<drawing, Drawing Commands>>. |
| ifdef::VK_NV_mesh_shader[] |
| It is ignored if the pipeline includes a mesh shader stage. |
| endif::VK_NV_mesh_shader[] |
| * pname:pTessellationState is a pointer to a |
| 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 a |
| slink:VkPipelineViewportStateCreateInfo structure, and is ignored if the |
| pipeline has rasterization disabled. |
| * pname:pRasterizationState is a pointer to a |
| slink:VkPipelineRasterizationStateCreateInfo structure. |
| * pname:pMultisampleState is a pointer to a |
| slink:VkPipelineMultisampleStateCreateInfo structure, and is ignored if |
| the pipeline has rasterization disabled. |
| * pname:pDepthStencilState is a pointer to a |
| slink:VkPipelineDepthStencilStateCreateInfo structure, and is ignored if |
| the pipeline has rasterization disabled or if no depth/stencil |
| attachment is used. |
| * pname:pColorBlendState is a pointer to a |
| slink:VkPipelineColorBlendStateCreateInfo structure, and is ignored if |
| the pipeline has rasterization disabled or if no color attachments are |
| used. |
| * pname:pDynamicState is a pointer to a |
| slink:VkPipelineDynamicStateCreateInfo structure, 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 a render pass instance 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>>. |
| |
| 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[] |
| |
| [[pipeline-graphics-subsets]] |
| The state required for a graphics pipeline is divided into |
| <<pipeline-graphics-subsets-vertex-input, vertex input state>>, |
| <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader |
| state>>, <<pipeline-graphics-subsets-fragment-shader,fragment shader |
| state>>, and <<pipeline-graphics-subsets-fragment-output,fragment output |
| state>>. |
| |
| [[pipeline-graphics-subsets-vertex-input]] |
| Vertex input state is defined by: |
| |
| * slink:VkPipelineVertexInputStateCreateInfo |
| * slink:VkPipelineInputAssemblyStateCreateInfo |
| |
| [[pipeline-graphics-subsets-pre-rasterization]] |
| Pre-rasterization shader state is defined by: |
| |
| * slink:VkPipelineShaderStageCreateInfo entries for: |
| ** Vertex shaders |
| ** Tessellation control shaders |
| ** Tessellation evaluation shaders |
| ** Geometry shaders |
| ifdef::VK_NV_mesh_shader[] |
| ** Task shaders |
| ** Mesh shaders |
| endif::VK_NV_mesh_shader[] |
| * Within the slink:VkPipelineLayout, all bindings that affect the |
| specified shader stages |
| * slink:VkPipelineViewportStateCreateInfo |
| * slink:VkPipelineRasterizationStateCreateInfo |
| * slink:VkPipelineTessellationStateCreateInfo if tessellation stages are |
| included. |
| * slink:VkRenderPass and pname:subpass parameter |
| ifdef::VK_EXT_discard_rectangles[] |
| * slink:VkPipelineDiscardRectangleStateCreateInfoEXT |
| endif::VK_EXT_discard_rectangles[] |
| ifdef::VK_KHR_fragment_shading_rate[] |
| * slink:VkPipelineFragmentShadingRateStateCreateInfoKHR |
| ifdef::VK_NV_fragment_shading_rate_enums[] |
| * slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV |
| endif::VK_NV_fragment_shading_rate_enums[] |
| endif::VK_KHR_fragment_shading_rate[] |
| |
| [[pipeline-graphics-subsets-fragment-shader]] |
| Fragment shader state is defined by: |
| |
| * A slink:VkPipelineShaderStageCreateInfo entry for the fragment shader |
| * Within the slink:VkPipelineLayout, all bindings that affect the fragment |
| shader |
| * slink:VkPipelineMultisampleStateCreateInfo |
| * slink:VkPipelineDepthStencilStateCreateInfo |
| * slink:VkRenderPass and pname:subpass parameter |
| ifdef::VK_KHR_fragment_shading_rate[] |
| * slink:VkPipelineFragmentShadingRateStateCreateInfoKHR |
| ifdef::VK_NV_fragment_shading_rate_enums[] |
| * slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV |
| endif::VK_NV_fragment_shading_rate_enums[] |
| endif::VK_KHR_fragment_shading_rate[] |
| |
| [[pipeline-graphics-subsets-fragment-output]] |
| Fragment output state is defined by: |
| |
| * slink:VkPipelineColorBlendStateCreateInfo |
| * The pname:alphaToCoverageEnable and pname:alphaToOneEnable members of |
| slink:VkPipelineMultisampleStateCreateInfo. |
| * slink:VkRenderPass and pname:subpass parameter |
| |
| [[pipeline-graphics-subsets-complete]] |
| A complete graphics pipeline always includes |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, with other subsets included depending on that state. |
| If the <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization |
| shader state>> includes a vertex shader, then |
| <<pipeline-graphics-subsets-vertex-input, vertex input state>> is included |
| in a complete graphics pipeline. |
| If the value of |
| slink:VkPipelineRasterizationStateCreateInfo::pname:rasterizerDiscardEnable |
| in the <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization |
| shader state>> is ename:VK_FALSE |
| ifdef::VK_EXT_extended_dynamic_state2[] |
| or the ename:VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE_EXT dynamic state is |
| enabled |
| endif::VK_EXT_extended_dynamic_state2[] |
| <<pipeline-graphics-subsets-fragment-shader, fragment shader state>> and |
| <<pipeline-graphics-subsets-fragment-output, fragment output interface |
| state>> is included in a complete graphics pipeline. |
| |
| Pipelines must: be created with a complete set of pipeline state. |
| |
| .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 |
| ifndef::VK_NV_mesh_shader[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-stage-00727]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> the pname:stage member of one element of pname:pStages must: be |
| ename:VK_SHADER_STAGE_VERTEX_BIT |
| endif::VK_NV_mesh_shader[] |
| ifdef::VK_NV_mesh_shader[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pStages-02095]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> the geometric shader stages provided in pname:pStages must: be |
| either from the mesh shading pipeline (pname:stage is |
| ename:VK_SHADER_STAGE_TASK_BIT_NV or ename:VK_SHADER_STAGE_MESH_BIT_NV) |
| or from the primitive shading pipeline (pname:stage is |
| ename:VK_SHADER_STAGE_VERTEX_BIT, |
| ename:VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, |
| ename:VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, or |
| ename:VK_SHADER_STAGE_GEOMETRY_BIT) |
| * [[VUID-VkGraphicsPipelineCreateInfo-stage-02096]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> the pname:stage member of one element of pname:pStages must: be |
| either ename:VK_SHADER_STAGE_VERTEX_BIT or |
| ename:VK_SHADER_STAGE_MESH_BIT_NV |
| endif::VK_NV_mesh_shader[] |
| * [[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 the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> and pname:pStages includes a tessellation control shader stage, |
| it must: include a tessellation evaluation shader stage |
| * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00730]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> and pname:pStages includes a tessellation evaluation shader |
| stage, it must: include a tessellation control shader stage |
| * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00731]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> and pname:pStages includes a tessellation control shader stage |
| and a tessellation evaluation shader stage, pname:pTessellationState |
| must: be a valid pointer to a valid |
| slink:VkPipelineTessellationStateCreateInfo structure |
| * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00732]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> and 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 the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> and 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 the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> and 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 the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> and 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 the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> and 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 pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> and 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 the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> and 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 the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> and 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 the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> and <<pipeline-graphics-subsets-fragment-shader, fragment shader |
| state>>, it includes both a fragment shader and a geometry shader, 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 |
| ifdef::VK_NV_mesh_shader[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-PrimitiveId-06264]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, it includes a mesh shader and the fragment shader code reads |
| from an input variable that is decorated with code:PrimitiveId, then the |
| mesh shader code must: write to a matching output variable, decorated |
| with code:PrimitiveId, in all execution paths |
| endif::VK_NV_mesh_shader[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06038]] |
| If pname:renderPass is not dlink:VK_NULL_HANDLE and the pipeline is |
| being created with <<pipeline-graphics-subsets-fragment-shader, fragment |
| shader state>> the fragment shader must: not read from any input |
| attachment that is defined as ename:VK_ATTACHMENT_UNUSED in |
| pname:subpass |
| * [[VUID-VkGraphicsPipelineCreateInfo-pStages-00742]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> and multiple pre-rasterization shader stages are included in |
| pname:pStages, the shader code for the entry points identified by those |
| 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 |
| * [[VUID-VkGraphicsPipelineCreateInfo-None-04889]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> and <<pipeline-graphics-subsets-fragment-shader, fragment shader |
| state>>, the fragment shader and last |
| <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader |
| stage>> and any relevant state must: adhere to the pipeline linking |
| rules described in the <<interfaces,Shader Interfaces>> chapter |
| * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06039]] |
| If pname:renderPass is not dlink:VK_NULL_HANDLE, the pipeline is being |
| created with <<pipeline-graphics-subsets-fragment-shader, fragment |
| shader state>>, and pname:subpass uses a depth/stencil attachment in |
| pname:renderPass with a read-only layout for the depth aspect in the |
| slink:VkAttachmentReference defined by pname:subpass, the |
| pname:depthWriteEnable member of pname:pDepthStencilState must: be |
| ename:VK_FALSE |
| * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06040]] |
| If pname:renderPass is not dlink:VK_NULL_HANDLE, the pipeline is being |
| created with <<pipeline-graphics-subsets-fragment-shader, fragment |
| shader state>>, and pname:subpass uses a depth/stencil attachment in |
| pname:renderPass with a read-only layout for the stencil aspect in the |
| slink: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 |
| * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06041]] |
| If pname:renderPass is not dlink:VK_NULL_HANDLE, and the pipeline is |
| being created with <<pipeline-graphics-subsets-fragment-output, fragment |
| output interface state>>, then for each color attachment in the subpass, |
| if the <<potential-format-features,potential format features>> of the |
| format of the corresponding attachment description do not contain |
| ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT, then the |
| pname:blendEnable member of the corresponding element of the |
| pname:pAttachments member of pname:pColorBlendState must: be |
| ename:VK_FALSE |
| * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06042]] |
| If pname:renderPass is not dlink:VK_NULL_HANDLE, and the pipeline is |
| being created with <<pipeline-graphics-subsets-fragment-output, fragment |
| output interface state>>, 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 |
| ifndef::VK_EXT_extended_dynamic_state[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00747]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, and 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->viewportCount valid |
| sname:VkViewport structures |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00748]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, and 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->scissorCount sname:VkRect2D |
| structures |
| endif::VK_EXT_extended_dynamic_state[] |
| ifdef::VK_EXT_extended_dynamic_state[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04130]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, and no element of the pname:pDynamicStates member of |
| pname:pDynamicState is ename:VK_DYNAMIC_STATE_VIEWPORT or |
| ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT, the pname:pViewports |
| member of pname:pViewportState must: be a valid pointer to an array of |
| pname:pViewportState->viewportCount valid sname:VkViewport structures |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04131]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, and no element of the pname:pDynamicStates member of |
| pname:pDynamicState is ename:VK_DYNAMIC_STATE_SCISSOR or |
| ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT, the pname:pScissors |
| member of pname:pViewportState must: be a valid pointer to an array of |
| pname:pViewportState->scissorCount sname:VkRect2D structures |
| endif::VK_EXT_extended_dynamic_state[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00749]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, and 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 pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, and the pname:rasterizerDiscardEnable member of |
| pname:pRasterizationState is ename:VK_FALSE, pname:pViewportState must: |
| be a valid pointer to a valid slink:VkPipelineViewportStateCreateInfo |
| structure |
| ifdef::VK_EXT_extended_dynamic_state2[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pViewportState-04892]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, and the graphics pipeline state was created with the |
| ename:VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE_EXT dynamic state |
| enabled, pname:pViewportState must: be a valid pointer to a valid |
| slink:VkPipelineViewportStateCreateInfo structure |
| endif::VK_EXT_extended_dynamic_state2[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-rasterizerDiscardEnable-00751]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, |
| pname:pMultisampleState must: be a valid pointer to a valid |
| slink:VkPipelineMultisampleStateCreateInfo structure |
| * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06043]] |
| If pname:renderPass is not dlink:VK_NULL_HANDLE, the pipeline is being |
| created with <<pipeline-graphics-subsets-fragment-shader, fragment |
| shader state>>, and pname:subpass uses a depth/stencil attachment, |
| pname:pDepthStencilState must: be a valid pointer to a valid |
| slink:VkPipelineDepthStencilStateCreateInfo structure |
| * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06044]] |
| If pname:renderPass is not dlink:VK_NULL_HANDLE, the pipeline is being |
| created with <<pipeline-graphics-subsets-fragment-output, fragment |
| output interface state>>, and pname:subpass uses color attachments, |
| pname:pColorBlendState must: be a valid pointer to a valid |
| slink:VkPipelineColorBlendStateCreateInfo structure |
| * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06045]] |
| If pname:renderPass is not dlink:VK_NULL_HANDLE and the pipeline is |
| being created with <<pipeline-graphics-subsets-fragment-output, fragment |
| output interface state>>, pname:pColorBlendState->attachmentCount must: |
| be greater than the index of all color attachments that are not |
| ename:VK_ATTACHMENT_UNUSED for the pname:subpass index in |
| pname:renderPass |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-00754]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, 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 the pipeline is being created with |
| <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, |
| and 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_depth_range_unrestricted[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-02510]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, |
| and the `apiext:VK_EXT_depth_range_unrestricted` extension is not |
| enabled and 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 the pipeline is being created with |
| <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, |
| and 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 included in |
| 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 the pipeline is being created with |
| <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, |
| and 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 included in |
| 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 the pipeline is being created with |
| <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, |
| and 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 included in |
| the pname:pNext chain of pname:pMultisampleState is ename:VK_TRUE, |
| pname:sampleLocationsInfo.sampleLocationsPerPixel must: equal |
| pname:rasterizationSamples |
| * [[VUID-VkGraphicsPipelineCreateInfo-sampleLocationsEnable-01524]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, |
| and the pname:sampleLocationsEnable member of a |
| slink:VkPipelineSampleLocationsStateCreateInfoEXT structure included in |
| 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 |
| * [[VUID-VkGraphicsPipelineCreateInfo-subpass-00757]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, |
| and neither the `apiext:VK_AMD_mixed_attachment_samples` nor the |
| `apiext:VK_NV_framebuffer_mixed_samples` extensions are enabled, and 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 |
| ifdef::VK_AMD_mixed_attachment_samples[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-subpass-01505]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, |
| and the `apiext:VK_AMD_mixed_attachment_samples` extension is enabled, |
| and 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 the pipeline is being created with |
| <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, |
| and the `apiext:VK_NV_framebuffer_mixed_samples` extension is enabled, |
| and 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 the pipeline is being created with |
| <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, |
| and the `apiext:VK_NV_framebuffer_mixed_samples` extension is enabled, |
| and 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[] |
| ifdef::VK_NV_coverage_reduction_mode[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-coverageReductionMode-02722]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, |
| and the `apiext:VK_NV_coverage_reduction_mode` extension is enabled, the |
| coverage reduction mode specified by |
| slink:VkPipelineCoverageReductionStateCreateInfoNV::pname:coverageReductionMode, |
| the pname:rasterizationSamples member of pname:pMultisampleState and the |
| sample counts for the color and depth/stencil attachments (if the |
| subpass has them) must: be a valid combination returned by |
| fname:vkGetPhysicalDeviceSupportedFramebufferMixedSamplesCombinationsNV |
| endif::VK_NV_coverage_reduction_mode[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-subpass-00758]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-fragment-shader, fragment shader state>> and |
| 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-renderPass-06046]] |
| If pname:renderPass is a valid renderPass, pname:subpass must: be a |
| valid subpass within pname:renderPass |
| ifdef::VK_VERSION_1_1,VK_KHR_multiview[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06047]] |
| If pname:renderPass is a valid renderPass, the pipeline is being created |
| with <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization |
| shader state>>, and 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-06048]] |
| If pname:renderPass is a valid renderPass, the pipeline is being created |
| with <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization |
| shader state>>, and 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-06049]] |
| If pname:renderPass is a valid renderPass, the pipeline is being created |
| with <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization |
| shader state>>, and 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-06050]] |
| If pname:renderPass is a valid renderPass and the pipeline is being |
| created with <<pipeline-graphics-subsets-pre-rasterization, |
| pre-rasterization shader state>>, and 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_VERSION_1_1,VK_KHR_multiview[] |
| ifdef::VK_VERSION_1_1,VK_KHR_device_group[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-flags-00764]] |
| pname:flags must: not contain the ename:VK_PIPELINE_CREATE_DISPATCH_BASE |
| flag |
| endif::VK_VERSION_1_1,VK_KHR_device_group[] |
| ifdef::VK_VERSION_1_1,VK_KHR_maintenance2,VK_KHR_create_renderpass2[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pStages-01565]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-fragment-shader, fragment shader state>> and |
| an input attachment was referenced by an pname:aspectMask at |
| pname:renderPass creation time, the fragment shader must: only read from |
| the aspects that were specified for that input attachment |
| endif::VK_VERSION_1_1,VK_KHR_maintenance2,VK_KHR_create_renderpass2[] |
| * [[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 the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, and 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, included in |
| 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[] |
| ifdef::VK_NV_scissor_exclusive[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04056]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, and no element of the pname:pDynamicStates member of |
| pname:pDynamicState is ename:VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV, and |
| if pname:pViewportState->pNext chain includes a |
| slink:VkPipelineViewportExclusiveScissorStateCreateInfoNV structure, and |
| if its pname:exclusiveScissorCount member is not `0`, then its |
| pname:pExclusiveScissors member must: be a valid pointer to an array of |
| pname:exclusiveScissorCount slink:VkRect2D structures |
| endif::VK_NV_scissor_exclusive[] |
| ifdef::VK_NV_shading_rate_image[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04057]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, and no element of the pname:pDynamicStates member of |
| pname:pDynamicState is |
| ename:VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV, and if |
| pname:pViewportState->pNext chain includes a |
| slink:VkPipelineViewportShadingRateImageStateCreateInfoNV structure, |
| then its pname:pShadingRatePalettes member must: be a valid pointer to |
| an array of pname:viewportCount valid slink:VkShadingRatePaletteNV |
| structures |
| endif::VK_NV_shading_rate_image[] |
| ifdef::VK_EXT_discard_rectangles[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04058]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, and no element of the pname:pDynamicStates member of |
| pname:pDynamicState is ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT, and |
| if pname:pNext chain includes a |
| slink:VkPipelineDiscardRectangleStateCreateInfoEXT structure, and if its |
| pname:discardRectangleCount member is not `0`, then its |
| pname:pDiscardRectangles member must: be a valid pointer to an array of |
| pname:discardRectangleCount slink:VkRect2D structures |
| endif::VK_EXT_discard_rectangles[] |
| ifndef::VK_EXT_vertex_input_dynamic_state[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pStages-02097]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-vertex-input, vertex input state>>, |
| pname:pVertexInputState must: be a valid pointer to a valid |
| slink:VkPipelineVertexInputStateCreateInfo structure |
| endif::VK_EXT_vertex_input_dynamic_state[] |
| ifndef::VK_EXT_vertex_input_dynamic_state[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pVertexInputState-04910]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-vertex-input, vertex input state>>, and |
| ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT is not set, |
| pname:pVertexInputState must: be a valid pointer to a valid |
| slink:VkPipelineVertexInputStateCreateInfo structure |
| endif::VK_EXT_vertex_input_dynamic_state[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pStages-02098]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-vertex-input, vertex input state>>, |
| pname:pInputAssemblyState must: be a valid pointer to a valid |
| slink:VkPipelineInputAssemblyStateCreateInfo structure |
| ifdef::VK_EXT_transform_feedback[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pStages-02317]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, the code:Xfb execution mode can: be specified by no more than |
| one shader stage in pname:pStages |
| * [[VUID-VkGraphicsPipelineCreateInfo-pStages-02318]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, and any shader stage in pname:pStages specifies code:Xfb |
| execution mode it must: be the last |
| <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader |
| stage>> |
| * [[VUID-VkGraphicsPipelineCreateInfo-rasterizationStream-02319]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, and a |
| slink:VkPipelineRasterizationStateStreamCreateInfoEXT::pname:rasterizationStream |
| value other than zero is specified, all variables in the output |
| interface of the entry point being compiled decorated with |
| code:Position, code:PointSize, code:ClipDistance, or code:CullDistance |
| must: be decorated with identical code:Stream values that match the |
| pname:rasterizationStream |
| * [[VUID-VkGraphicsPipelineCreateInfo-rasterizationStream-02320]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, and |
| slink:VkPipelineRasterizationStateStreamCreateInfoEXT::pname:rasterizationStream |
| is zero, or not specified, all variables in the output interface of the |
| entry point being compiled decorated with code:Position, code:PointSize, |
| code:ClipDistance, or code:CullDistance must: be decorated with a |
| code:Stream value of zero, or must: not specify the code:Stream |
| decoration |
| * [[VUID-VkGraphicsPipelineCreateInfo-geometryStreams-02321]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, and the last |
| <<pipeline-graphics-subsets-pre-rasterization,pre-rasterization shader |
| stage>> is a geometry shader, and that geometry shader uses the |
| code:GeometryStreams capability, then |
| sname:VkPhysicalDeviceTransformFeedbackFeaturesEXT::pname:geometryStreams |
| feature must: be enabled |
| ifdef::VK_NV_mesh_shader[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-None-02322]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, and there are any mesh shader stages in the pipeline there |
| must: not be any shader stage in the pipeline with a code:Xfb execution |
| mode |
| endif::VK_NV_mesh_shader[] |
| endif::VK_EXT_transform_feedback[] |
| ifdef::VK_EXT_line_rasterization[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-lineRasterizationMode-02766]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> and at least one of <<pipeline-graphics-subsets-fragment-output, |
| fragment output interface state>> or |
| <<pipeline-graphics-subsets-fragment-shader, fragment shader state>>, |
| the pname:lineRasterizationMode member of a |
| slink:VkPipelineRasterizationLineStateCreateInfoEXT structure included |
| in the pname:pNext chain of pname:pRasterizationState is |
| ename:VK_LINE_RASTERIZATION_MODE_BRESENHAM_EXT or |
| ename:VK_LINE_RASTERIZATION_MODE_RECTANGULAR_SMOOTH_EXT, then the |
| pname:alphaToCoverageEnable, pname:alphaToOneEnable, and |
| pname:sampleShadingEnable members of pname:pMultisampleState must: all |
| be ename:VK_FALSE |
| * [[VUID-VkGraphicsPipelineCreateInfo-stippledLineEnable-02767]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, the pname:stippledLineEnable member of |
| slink:VkPipelineRasterizationLineStateCreateInfoEXT is ename:VK_TRUE, |
| and no element of the pname:pDynamicStates member of pname:pDynamicState |
| is ename:VK_DYNAMIC_STATE_LINE_STIPPLE_EXT, then the |
| pname:lineStippleFactor member of |
| slink:VkPipelineRasterizationLineStateCreateInfoEXT must: be in the |
| range [eq]#[1,256]# |
| endif::VK_EXT_line_rasterization[] |
| ifdef::VK_KHR_pipeline_library[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-flags-03371]] |
| pname:flags must: not include ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR |
| endif::VK_KHR_pipeline_library[] |
| ifdef::VK_KHR_ray_tracing_pipeline[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-flags-03372]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR |
| * [[VUID-VkGraphicsPipelineCreateInfo-flags-03373]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR |
| * [[VUID-VkGraphicsPipelineCreateInfo-flags-03374]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR |
| * [[VUID-VkGraphicsPipelineCreateInfo-flags-03375]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR |
| * [[VUID-VkGraphicsPipelineCreateInfo-flags-03376]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR |
| * [[VUID-VkGraphicsPipelineCreateInfo-flags-03377]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR |
| * [[VUID-VkGraphicsPipelineCreateInfo-flags-03577]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR |
| endif::VK_KHR_ray_tracing_pipeline[] |
| ifdef::VK_NV_ray_tracing_motion_blur[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-flags-04947]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV |
| endif::VK_NV_ray_tracing_motion_blur[] |
| ifdef::VK_EXT_extended_dynamic_state[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-03378]] |
| If the <<features-extendedDynamicState, extendedDynamicState>> feature |
| is not enabled, there must: be no element of the pname:pDynamicStates |
| member of pname:pDynamicState set to |
| ename:VK_DYNAMIC_STATE_CULL_MODE_EXT, |
| ename:VK_DYNAMIC_STATE_FRONT_FACE_EXT, |
| ename:VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY_EXT, |
| ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT, |
| ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT, |
| ename:VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE_EXT, |
| ename:VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE_EXT, |
| ename:VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE_EXT, |
| ename:VK_DYNAMIC_STATE_DEPTH_COMPARE_OP_EXT, |
| ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE_EXT, |
| ename:VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE_EXT, or |
| ename:VK_DYNAMIC_STATE_STENCIL_OP_EXT |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-03379]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, and ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT is included |
| in the pname:pDynamicStates array then pname:viewportCount must: be zero |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-03380]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, and ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT is included |
| in the pname:pDynamicStates array then pname:scissorCount must: be zero |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04132]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, and ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT is included |
| in the pname:pDynamicStates array then ename:VK_DYNAMIC_STATE_VIEWPORT |
| must: not be present |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04133]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>>, and ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT is included |
| in the pname:pDynamicStates array then ename:VK_DYNAMIC_STATE_SCISSOR |
| must: not be present |
| endif::VK_EXT_extended_dynamic_state[] |
| ifdef::VK_EXT_extended_dynamic_state2[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04868]] |
| If the <<features-extendedDynamicState2, extendedDynamicState2>> feature |
| is not enabled, there must: be no element of the pname:pDynamicStates |
| member of pname:pDynamicState set to |
| ename:VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE_EXT, |
| ename:VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE_EXT, or |
| ename:VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE_EXT |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04869]] |
| If the <<features-extendedDynamicState2LogicOp, |
| extendedDynamicState2LogicOp>> feature is not enabled, there must: be no |
| element of the pname:pDynamicStates member of pname:pDynamicState set to |
| ename:VK_DYNAMIC_STATE_LOGIC_OP_EXT |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04870]] |
| If the <<features-extendedDynamicState2PatchControlPoints, |
| extendedDynamicState2PatchControlPoints>> feature is not enabled, there |
| must: be no element of the pname:pDynamicStates member of |
| pname:pDynamicState set to |
| ename:VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT |
| endif::VK_EXT_extended_dynamic_state2[] |
| ifdef::VK_NV_device_generated_commands[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-flags-02877]] |
| If pname:flags includes |
| ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV, then the |
| <<features-deviceGeneratedCommands, |
| sname:VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV::pname:deviceGeneratedCommands>> |
| feature must: be enabled |
| ifdef::VK_EXT_transform_feedback[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-flags-02966]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> and pname:flags includes |
| ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV, then all stages must: |
| not specify code:Xfb execution mode |
| endif::VK_EXT_transform_feedback[] |
| endif::VK_NV_device_generated_commands[] |
| ifdef::VK_EXT_pipeline_creation_cache_control[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pipelineCreationCacheControl-02878]] |
| If the <<features-pipelineCreationCacheControl, |
| pname:pipelineCreationCacheControl>> feature is not enabled, pname:flags |
| must: not include |
| ename:VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT or |
| ename:VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT |
| endif::VK_EXT_pipeline_creation_cache_control[] |
| ifdef::VK_KHR_fragment_shading_rate[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04494]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader |
| state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not |
| included in pname:pDynamicState->pDynamicStates, |
| slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.width |
| must: be greater than or equal to `1` |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04495]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader |
| state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not |
| included in pname:pDynamicState->pDynamicStates, |
| slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.height |
| must: be greater than or equal to `1` |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04496]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader |
| state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not |
| included in pname:pDynamicState->pDynamicStates, |
| slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.width |
| must: be a power-of-two value |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04497]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader |
| state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not |
| included in pname:pDynamicState->pDynamicStates, |
| slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.height |
| must: be a power-of-two value |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04498]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader |
| state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not |
| included in pname:pDynamicState->pDynamicStates, |
| slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.width |
| must: be less than or equal to `4` |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04499]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader |
| state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not |
| included in pname:pDynamicState->pDynamicStates, |
| slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.height |
| must: be less than or equal to `4` |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04500]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader |
| state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not |
| included in pname:pDynamicState->pDynamicStates, and the |
| <<features-pipelineFragmentShadingRate, |
| pname:pipelineFragmentShadingRate feature>> is not enabled, |
| slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.width |
| and |
| slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:fragmentSize.height |
| must: both be equal to `1` |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04501]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader |
| state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not |
| included in pname:pDynamicState->pDynamicStates, and the |
| <<features-primitiveFragmentShadingRate, |
| pname:primitiveFragmentShadingRate feature>> is not enabled, |
| slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:combinerOps[0] |
| must: be ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04502]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader |
| state>> and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not |
| included in pname:pDynamicState->pDynamicStates, and the |
| <<features-attachmentFragmentShadingRate, |
| pname:attachmentFragmentShadingRate feature>> is not enabled, |
| slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:combinerOps[1] |
| must: be ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR |
| ifdef::VK_EXT_extended_dynamic_state[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-primitiveFragmentShadingRateWithMultipleViewports-04503]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> and the |
| <<limits-primitiveFragmentShadingRateWithMultipleViewports, |
| pname:primitiveFragmentShadingRateWithMultipleViewports>> limit is not |
| supported, ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT is not |
| included in pname:pDynamicState->pDynamicStates, and |
| slink:VkPipelineViewportStateCreateInfo::pname:viewportCount is greater |
| than `1`, entry points specified in pname:pStages must: not write to the |
| code:PrimitiveShadingRateKHR built-in |
| endif::VK_EXT_extended_dynamic_state[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-primitiveFragmentShadingRateWithMultipleViewports-04504]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> and the |
| <<limits-primitiveFragmentShadingRateWithMultipleViewports, |
| pname:primitiveFragmentShadingRateWithMultipleViewports>> limit is not |
| supported, and entry points specified in pname:pStages write to the |
| code:ViewportIndex built-in, they must: not also write to the |
| code:PrimitiveShadingRateKHR built-in |
| ifdef::VK_NV_viewport_array2[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-primitiveFragmentShadingRateWithMultipleViewports-04505]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> and the |
| <<limits-primitiveFragmentShadingRateWithMultipleViewports, |
| pname:primitiveFragmentShadingRateWithMultipleViewports>> limit is not |
| supported, and entry points specified in pname:pStages write to the |
| code:ViewportMaskNV built-in, they must: not also write to the |
| code:PrimitiveShadingRateKHR built-in |
| endif::VK_NV_viewport_array2[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-fragmentShadingRateNonTrivialCombinerOps-04506]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader |
| state>>, the <<limits-fragmentShadingRateNonTrivialCombinerOps, |
| pname:fragmentShadingRateNonTrivialCombinerOps>> limit is not supported, |
| and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in |
| pname:pDynamicState->pDynamicStates, elements of |
| slink:VkPipelineFragmentShadingRateStateCreateInfoKHR::pname:combinerOps |
| must: be ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR or |
| ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR |
| endif::VK_KHR_fragment_shading_rate[] |
| ifdef::VK_NV_fragment_shading_rate_enums[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04569]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader |
| state>>, and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not |
| included in pname:pDynamicState->pDynamicStates, and the |
| <<features-fragmentShadingRateEnums, pname:fragmentShadingRateEnums |
| feature>> is not enabled, |
| slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV::pname:shadingRateType |
| must: be equal to ename:VK_FRAGMENT_SHADING_RATE_TYPE_FRAGMENT_SIZE_NV |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04570]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader |
| state>>, and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not |
| included in pname:pDynamicState->pDynamicStates, and the |
| <<features-pipelineFragmentShadingRate, |
| pname:pipelineFragmentShadingRate feature>> is not enabled, |
| slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV::pname:shadingRate |
| must: be equal to |
| ename:VK_FRAGMENT_SHADING_RATE_1_INVOCATION_PER_PIXEL_NV |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04571]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader |
| state>>, and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not |
| included in pname:pDynamicState->pDynamicStates, and the |
| <<features-primitiveFragmentShadingRate, |
| pname:primitiveFragmentShadingRate feature>> is not enabled, |
| slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV::pname:combinerOps[0] |
| must: be ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicState-04572]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader |
| state>>, and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not |
| included in pname:pDynamicState->pDynamicStates, and the |
| <<features-attachmentFragmentShadingRate, |
| pname:attachmentFragmentShadingRate feature>> is not enabled, |
| slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV::pname:combinerOps[1] |
| must: be ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR |
| * [[VUID-VkGraphicsPipelineCreateInfo-fragmentShadingRateNonTrivialCombinerOps-04573]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader |
| state>>, and the <<limits-fragmentShadingRateNonTrivialCombinerOps, |
| pname:fragmentShadingRateNonTrivialCombinerOps>> limit is not supported |
| and ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR is not included in |
| pname:pDynamicState->pDynamicStates, elements of |
| slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV::pname:combinerOps |
| must: be ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_KEEP_KHR or |
| ename:VK_FRAGMENT_SHADING_RATE_COMBINER_OP_REPLACE_KHR |
| * [[VUID-VkGraphicsPipelineCreateInfo-None-04574]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader |
| state>>, and the <<features-supersampleFragmentShadingRates, |
| supersampleFragmentShadingRates feature>> is not enabled, |
| slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV::pname:shadingRate |
| must: not be equal to |
| ename:VK_FRAGMENT_SHADING_RATE_2_INVOCATIONS_PER_PIXEL_NV, |
| ename:VK_FRAGMENT_SHADING_RATE_4_INVOCATIONS_PER_PIXEL_NV, |
| ename:VK_FRAGMENT_SHADING_RATE_8_INVOCATIONS_PER_PIXEL_NV, or |
| ename:VK_FRAGMENT_SHADING_RATE_16_INVOCATIONS_PER_PIXEL_NV |
| * [[VUID-VkGraphicsPipelineCreateInfo-None-04575]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> or <<pipeline-graphics-subsets-fragment-shader, fragment shader |
| state>>, and the <<features-noInvocationFragmentShadingRates, |
| noInvocationFragmentShadingRates feature>> is not enabled, |
| slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV::pname:shadingRate |
| must: not be equal to ename:VK_FRAGMENT_SHADING_RATE_NO_INVOCATIONS_NV |
| endif::VK_NV_fragment_shading_rate_enums[] |
| ifdef::VK_KHR_ray_tracing_pipeline[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-03578]] |
| All elements of the pname:pDynamicStates member of pname:pDynamicState |
| must: not be ename:VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR |
| endif::VK_KHR_ray_tracing_pipeline[] |
| ifdef::VK_EXT_vertex_input_dynamic_state[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04807]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-pre-rasterization, pre-rasterization shader |
| state>> and the <<features-vertexInputDynamicState, |
| vertexInputDynamicState>> feature is not enabled, there must: be no |
| element of the pname:pDynamicStates member of pname:pDynamicState set to |
| ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT |
| endif::VK_EXT_vertex_input_dynamic_state[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-None-04893]] |
| The pipeline must: be created with a |
| <<pipeline-graphics-subsets-complete, complete set of state>> |
| ifdef::VK_EXT_color_write_enable[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-pDynamicStates-04800]] |
| If the <<features-colorWriteEnable, colorWriteEnable>> feature is not |
| enabled, there must: be no element of the pname:pDynamicStates member of |
| pname:pDynamicState set to ename:VK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXT |
| endif::VK_EXT_color_write_enable[] |
| ifdef::VK_QCOM_render_pass_shader_resolve[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-rasterizationSamples-04899]] |
| If the pipeline is being created with fragment shader state, and the |
| apiext:VK_QCOM_render_pass_shader_resolve extension is enabled, and if |
| subpass has any input attachments, and if the subpass description |
| contains ename:VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM, then the |
| sample count of the input attachments must: equal |
| pname:rasterizationSamples |
| * [[VUID-VkGraphicsPipelineCreateInfo-sampleShadingEnable-04900]] |
| If the pipeline is being created with fragment shader state, and the |
| apiext:VK_QCOM_render_pass_shader_resolve extension is enabled, and if |
| the subpass description contains |
| ename:VK_SUBPASS_DESCRIPTION_FRAGMENT_REGION_BIT_QCOM, then |
| pname:sampleShadingEnable must: be false |
| * [[VUID-VkGraphicsPipelineCreateInfo-flags-04901]] |
| If pname:flags includes |
| ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, then the subpass |
| must: be the last subpass in a subpass dependency chain |
| * [[VUID-VkGraphicsPipelineCreateInfo-flags-04902]] |
| If pname:flags includes |
| ename:VK_SUBPASS_DESCRIPTION_SHADER_RESOLVE_BIT_QCOM, and if |
| pname:pResolveAttachments is not `NULL`, then each resolve attachment |
| must: be ename:VK_ATTACHMENT_UNUSED |
| endif::VK_QCOM_render_pass_shader_resolve[] |
| ifndef::VK_KHR_dynamic_rendering[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06051]] |
| pname:renderPass must: not be dlink:VK_NULL_HANDLE |
| endif::VK_KHR_dynamic_rendering[] |
| ifdef::VK_KHR_dynamic_rendering[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-dynamicRendering-06052]] |
| If the <<features-dynamicRendering,pname:dynamicRendering>> feature is |
| not enabled, pname:renderPass must: not be dlink:VK_NULL_HANDLE |
| * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06053]] |
| If pname:renderPass is dlink:VK_NULL_HANDLE, the pipeline is being |
| created with <<pipeline-graphics-subsets-fragment-shader, fragment |
| shader state>>, and either of |
| slink:VkPipelineRenderingCreateInfoKHR::depthAttachmentFormat or |
| slink:VkPipelineRenderingCreateInfoKHR::stencilAttachmentFormat are not |
| ename:VK_FORMAT_UNDEFINED, pname:pDepthStencilState must: be a valid |
| pointer to a valid slink:VkPipelineDepthStencilStateCreateInfo structure |
| * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06054]] |
| If pname:renderPass is dlink:VK_NULL_HANDLE, the pipeline is being |
| created with <<pipeline-graphics-subsets-fragment-output, fragment |
| output interface state>>, and |
| slink:VkPipelineRenderingCreateInfoKHR::colorAttachmentCount is not |
| equal to `0`, pname:pColorBlendState must: be a valid pointer to a valid |
| slink:VkPipelineColorBlendStateCreateInfo structure |
| * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06055]] |
| If pname:renderPass is dlink:VK_NULL_HANDLE and the pipeline is being |
| created with <<pipeline-graphics-subsets-fragment-output, fragment |
| output interface state>>, pname:pColorBlendState->attachmentCount must: |
| be equal to slink:VkPipelineRenderingCreateInfoKHR::colorAttachmentCount |
| * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06056]] |
| If pname:renderPass is dlink:VK_NULL_HANDLE and the pipeline is being |
| created with <<pipeline-graphics-subsets-fragment-shader, fragment |
| shader state>> the fragment shader must: not read from any input |
| attachment |
| ifdef::VK_KHR_multiview,VK_VERSION_1_1[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06057]] |
| If pname:renderPass is dlink:VK_NULL_HANDLE, the pipeline is being |
| created with <<pipeline-graphics-subsets-pre-rasterization, |
| pre-rasterization shader state>>, the pname:viewMask member of a |
| slink:VkPipelineRenderingCreateInfoKHR structure included in the |
| pname:pNext chain is not `0`, and the |
| <<features-multiview-tess,pname:multiviewTessellationShader>> feature is |
| not enabled, then pname:pStages must: not include tessellation shaders |
| * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06058]] |
| If pname:renderPass is dlink:VK_NULL_HANDLE, the pipeline is being |
| created with <<pipeline-graphics-subsets-pre-rasterization, |
| pre-rasterization shader state>>, the pname:viewMask member of a |
| slink:VkPipelineRenderingCreateInfoKHR structure included in the |
| pname:pNext chain is not `0`, and the |
| <<features-multiview-gs,pname:multiviewGeometryShader>> feature is not |
| enabled, then pname:pStages must: not include a geometry shader |
| * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06059]] |
| If pname:renderPass is dlink:VK_NULL_HANDLE, the pipeline is being |
| created with <<pipeline-graphics-subsets-pre-rasterization, |
| pre-rasterization shader state>>, and the pname:viewMask member of a |
| slink:VkPipelineRenderingCreateInfoKHR structure included in the |
| pname:pNext chain is not `0`, shaders in pname:pStages must: not include |
| variables decorated with the code:Layer built-in decoration in their |
| interfaces |
| * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06060]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-fragment-output, fragment output interface |
| state>> and pname:renderPass is dlink:VK_NULL_HANDLE, |
| pname:pColorBlendState->attachmentCount must: be equal to the |
| pname:colorAttachmentCount member of the |
| slink:VkPipelineRenderingCreateInfoKHR structure included in the |
| pname:pNext chain |
| * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06061]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-fragment-shader, fragment shader state>> and |
| pname:renderPass is dlink:VK_NULL_HANDLE, fragment shaders in |
| pname:pStages must: not include the code:InputAttachment capability |
| * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06062]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-fragment-output, fragment output interface |
| state>> and pname:renderPass is dlink:VK_NULL_HANDLE, for each color |
| attachment format defined by the pname:pColorAttachmentFormats member of |
| slink:VkPipelineRenderingCreateInfoKHR, if its |
| <<potential-format-features,potential format features>> do not contain |
| ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BLEND_BIT, then the |
| pname:blendEnable member of the corresponding element of the |
| pname:pAttachments member of pname:pColorBlendState must: be |
| ename:VK_FALSE |
| endif::VK_KHR_multiview,VK_VERSION_1_1[] |
| ifdef::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] |
| * [[VUID-VkGraphicsPipelineCreateInfo-renderPass-06063]] |
| If the pipeline is being created with |
| <<pipeline-graphics-subsets-fragment-output, fragment output interface |
| state>> and pname:renderPass is dlink:VK_NULL_HANDLE, if the pname:pNext |
| chain includes slink:VkAttachmentSampleCountInfoAMD or |
| sname:VkAttachmentSampleCountInfoNV, the pname:colorAttachmentCount |
| member of that structure must: be equal to the value of |
| slink:VkPipelineRenderingCreateInfoKHR::pname:colorAttachmentCount |
| endif::VK_AMD_mixed_attachment_samples,VK_NV_framebuffer_mixed_samples[] |
| endif::VK_KHR_dynamic_rendering[] |
| **** |
| |
| include::{generated}/validity/structs/VkGraphicsPipelineCreateInfo.txt[] |
| -- |
| |
| ifdef::VK_KHR_dynamic_rendering[] |
| [open,refpage='VkPipelineRenderingCreateInfoKHR',desc='Structure specifying attachment formats',type='structs'] |
| -- |
| The sname:VkPipelineRenderingCreateInfoKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkPipelineRenderingCreateInfoKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:viewMask is the viewMask used for rendering. |
| * pname:colorAttachmentCount is the number of entries in |
| pname:pColorAttachmentFormats |
| * pname:pColorAttachmentFormats is an array of elink:VkFormat values |
| defining the format of color attachments used in this pipeline. |
| * pname:depthAttachmentFormat is a elink:VkFormat value defining the |
| format of the depth attachment used in this pipeline. |
| * pname:stencilAttachmentFormat is a elink:VkFormat value defining the |
| format of the stencil attachment used in this pipeline. |
| |
| When a pipeline is created without a slink:VkRenderPass, if this structure |
| is present in the pname:pNext chain of slink:VkGraphicsPipelineCreateInfo, |
| it specifies the view mask and format of attachments used for rendering. |
| If this structure is not specified, and the pipeline does not include a |
| slink:VkRenderPass, pname:viewMask and pname:colorAttachmentCount are `0`, |
| and pname:depthAttachmentFormat and pname:stencilAttachmentFormat are |
| ename:VK_FORMAT_UNDEFINED. |
| If a graphics pipeline is created with a valid slink:VkRenderPass, |
| parameters of this structure are ignored. |
| |
| If pname:depthAttachmentFormat, pname:stencilAttachmentFormat, or any |
| element of pname:pColorAttachmentFormats is ename:VK_FORMAT_UNDEFINED, it |
| indicates that the corresponding attachment is unused within the render |
| pass. |
| Valid formats indicate that an attachment can: be used - but it is still |
| valid to set the attachment to `NULL` when beginning rendering. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkPipelineRenderingCreateInfoKHR-pColorAttachmentFormats-06064]] |
| If any element of pname:pColorAttachmentFormats is not |
| ename:VK_FORMAT_UNDEFINED, it must: be a format with |
| <<potential-format-features, potential format features>> that include |
| ename:VK_FORMAT_FEATURE_COLOR_ATTACHMENT_BIT |
| * [[VUID-VkPipelineRenderingCreateInfoKHR-depthAttachmentFormat-06065]] |
| If pname:depthAttachmentFormat is not ename:VK_FORMAT_UNDEFINED, it |
| must: be a format with <<potential-format-features, potential format |
| features>> that include |
| ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT |
| * [[VUID-VkPipelineRenderingCreateInfoKHR-stencilAttachmentFormat-06164]] |
| If pname:stencilAttachmentFormat is not ename:VK_FORMAT_UNDEFINED, it |
| must: be a format with <<potential-format-features, potential format |
| features>> that include |
| ename:VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT |
| * [[VUID-VkPipelineRenderingCreateInfoKHR-depthAttachmentFormat-06165]] |
| If pname:depthAttachmentFormat is not ename:VK_FORMAT_UNDEFINED and |
| pname:stencilAttachmentFormat is not ename:VK_FORMAT_UNDEFINED, |
| pname:depthAttachmentFormat must: equal pname:stencilAttachmentFormat |
| * [[VUID-VkPipelineRenderingCreateInfoKHR-multiview-06066]] |
| If the <<features-multiview,pname:multiview>> feature is not enabled, |
| pname:viewMask must: be `0` |
| ifdef::VK_VERSION_1_1,VK_KHR_multiview[] |
| * [[VUID-VkPipelineRenderingCreateInfoKHR-viewMask-06067]] |
| The index of the most significant bit in pname:viewMask must: be less |
| than <<limits-maxMultiviewViewCount,pname:maxMultiviewViewCount>> |
| endif::VK_VERSION_1_1,VK_KHR_multiview[] |
| **** |
| |
| include::{generated}/validity/structs/VkPipelineRenderingCreateInfoKHR.txt[] |
| -- |
| endif::VK_KHR_dynamic_rendering[] |
| |
| [open,refpage='VkPipelineCreateFlagBits',desc='Bitmask controlling how a pipeline is created',type='enums'] |
| -- |
| Possible values of the pname:flags member of |
| slink:VkGraphicsPipelineCreateInfo, |
| ifdef::VK_KHR_ray_tracing_pipeline[slink:VkRayTracingPipelineCreateInfoKHR,] |
| ifdef::VK_NV_ray_tracing[slink:VkRayTracingPipelineCreateInfoNV,] |
| and slink:VkComputePipelineCreateInfo, specifying how a pipeline is created, |
| are: |
| |
| include::{generated}/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 pipeline creation call. |
| * 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_VERSION_1_1,VK_KHR_device_group[] |
| ifdef::VK_VERSION_1_1,VK_KHR_multiview[] |
| * ename:VK_PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT specifies that |
| any shader input variables decorated as code:ViewIndex will be assigned |
| values as if they were decorated as code:DeviceIndex. |
| endif::VK_VERSION_1_1,VK_KHR_multiview[] |
| * ename:VK_PIPELINE_CREATE_DISPATCH_BASE specifies that a compute pipeline |
| can: be used with flink:vkCmdDispatchBase with a non-zero base |
| workgroup. |
| endif::VK_VERSION_1_1,VK_KHR_device_group[] |
| ifdef::VK_NV_ray_tracing[] |
| * ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV specifies that a pipeline |
| is created with all shaders in the deferred state. |
| Before using the pipeline the application must: call |
| flink:vkCompileDeferredNV exactly once on each shader in the pipeline |
| before using the pipeline. |
| endif::VK_NV_ray_tracing[] |
| ifdef::VK_KHR_pipeline_executable_properties[] |
| * ename:VK_PIPELINE_CREATE_CAPTURE_STATISTICS_BIT_KHR specifies that the |
| shader compiler should capture statistics for the pipeline executables |
| produced by the compile process which can: later be retrieved by calling |
| flink:vkGetPipelineExecutableStatisticsKHR. |
| Enabling this flag must: not affect the final compiled pipeline but may: |
| disable pipeline caching or otherwise affect pipeline creation time. |
| * ename:VK_PIPELINE_CREATE_CAPTURE_INTERNAL_REPRESENTATIONS_BIT_KHR |
| specifies that the shader compiler should capture the internal |
| representations of pipeline executables produced by the compile process |
| which can: later be retrieved by calling |
| flink:vkGetPipelineExecutableInternalRepresentationsKHR. |
| Enabling this flag must: not affect the final compiled pipeline but may: |
| disable pipeline caching or otherwise affect pipeline creation time. |
| endif::VK_KHR_pipeline_executable_properties[] |
| ifdef::VK_KHR_pipeline_library[] |
| * ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR specifies that the pipeline |
| cannot: be used directly, and instead defines a _pipeline library_ that |
| can: be combined with other pipelines using the |
| slink:VkPipelineLibraryCreateInfoKHR structure. |
| ifdef::VK_KHR_ray_tracing_pipeline[] |
| This is available in ray tracing pipelines. |
| endif::VK_KHR_ray_tracing_pipeline[] |
| endif::VK_KHR_pipeline_library[] |
| ifdef::VK_KHR_ray_tracing_pipeline[] |
| * ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR |
| specifies that an any-hit shader will always be present when an any-hit |
| shader would be executed. |
| A NULL any-hit shader is an any-hit shader which is effectively |
| ename:VK_SHADER_UNUSED_KHR, such as from a shader group consisting |
| entirely of zeros. |
| * ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR |
| specifies that a closest hit shader will always be present when a |
| closest hit shader would be executed. |
| A NULL closest hit shader is a closest hit shader which is effectively |
| ename:VK_SHADER_UNUSED_KHR, such as from a shader group consisting |
| entirely of zeros. |
| * ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR |
| specifies that a miss shader will always be present when a miss shader |
| would be executed. |
| A NULL miss shader is a miss shader which is effectively |
| ename:VK_SHADER_UNUSED_KHR, such as from a shader group consisting |
| entirely of zeros. |
| * ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR |
| specifies that an intersection shader will always be present when an |
| intersection shader would be executed. |
| A NULL intersection shader is an intersection shader which is |
| effectively ename:VK_SHADER_UNUSED_KHR, such as from a shader group |
| consisting entirely of zeros. |
| * ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR specifies |
| that triangle primitives will be skipped during traversal using |
| code:OpTraceRayKHR. |
| * ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR specifies that |
| AABB primitives will be skipped during traversal using |
| code:OpTraceRayKHR. |
| * ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR |
| specifies that the shader group handles can: be saved and reused on a |
| subsequent run (e.g. for trace capture and replay). |
| endif::VK_KHR_ray_tracing_pipeline[] |
| ifdef::VK_NV_device_generated_commands[] |
| * ename:VK_PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV specifies that the |
| pipeline can be used in combination with <<device-generated-commands>>. |
| endif::VK_NV_device_generated_commands[] |
| ifdef::VK_EXT_pipeline_creation_cache_control[] |
| * ename:VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT |
| specifies that pipeline creation will fail if a compile is required for |
| creation of a valid slink:VkPipeline object; |
| ename:VK_PIPELINE_COMPILE_REQUIRED_EXT will be returned by pipeline |
| creation, and the slink:VkPipeline will be set to dlink:VK_NULL_HANDLE. |
| * When creating multiple pipelines, |
| ename:VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT specifies that |
| control will be returned to the application on failure of the |
| corresponding pipeline rather than continuing to create additional |
| pipelines. |
| endif::VK_EXT_pipeline_creation_cache_control[] |
| ifdef::VK_NV_ray_tracing_motion_blur[] |
| * ename:VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV specifies that |
| the pipeline is allowed to use code:OpTraceRayMotionNV. |
| endif::VK_NV_ray_tracing_motion_blur[] |
| ifdef::VK_KHR_dynamic_rendering[] |
| ifdef::VK_KHR_fragment_shading_rate[] |
| * ename:VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR |
| specifies that the pipeline will be used with a fragment shading rate |
| attachment. |
| endif::VK_KHR_fragment_shading_rate[] |
| ifdef::VK_EXT_fragment_density_map[] |
| * ename:VK_PIPELINE_RASTERIZATION_STATE_CREATE_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT |
| specifies that the pipeline will be used with a fragment density map |
| attachment. |
| endif::VK_EXT_fragment_density_map[] |
| endif::VK_KHR_dynamic_rendering[] |
| |
| 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='VkPipelineCreateFlags',desc='Bitmask of VkPipelineCreateFlagBits',type='flags'] |
| -- |
| include::{generated}/api/flags/VkPipelineCreateFlags.txt[] |
| |
| tname:VkPipelineCreateFlags is a bitmask type for setting a mask of zero or |
| more elink:VkPipelineCreateFlagBits. |
| -- |
| |
| [open,refpage='VkPipelineDynamicStateCreateInfo',desc='Structure specifying parameters of a newly created pipeline dynamic state',type='structs'] |
| -- |
| The sname:VkPipelineDynamicStateCreateInfo structure is defined as: |
| |
| include::{generated}/api/structs/VkPipelineDynamicStateCreateInfo.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is reserved for future use. |
| * pname:dynamicStateCount is the number of elements in the |
| pname:pDynamicStates array. |
| * pname:pDynamicStates is a pointer to 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 |
| information. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkPipelineDynamicStateCreateInfo-pDynamicStates-01442]] |
| Each element of pname:pDynamicStates must: be unique |
| **** |
| |
| include::{generated}/validity/structs/VkPipelineDynamicStateCreateInfo.txt[] |
| -- |
| |
| [open,refpage='VkPipelineDynamicStateCreateFlags',desc='Reserved for future use',type='flags'] |
| -- |
| include::{generated}/api/flags/VkPipelineDynamicStateCreateFlags.txt[] |
| |
| tname:VkPipelineDynamicStateCreateFlags is a bitmask type for setting a |
| mask, but is currently reserved for future use. |
| -- |
| |
| [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::{generated}/api/enums/VkDynamicState.txt[] |
| |
| * ename:VK_DYNAMIC_STATE_VIEWPORT specifies that the pname:pViewports |
| state in slink:VkPipelineViewportStateCreateInfo will be ignored and |
| must: be set dynamically with flink:vkCmdSetViewport before any drawing |
| commands. |
| The number of viewports used by a pipeline is still specified by the |
| pname:viewportCount member of slink:VkPipelineViewportStateCreateInfo. |
| * ename:VK_DYNAMIC_STATE_SCISSOR specifies that the pname:pScissors state |
| in slink:VkPipelineViewportStateCreateInfo will be ignored and must: be |
| set dynamically with flink:vkCmdSetScissor before any drawing commands. |
| The number of scissor rectangles used by a pipeline is still specified |
| by the pname:scissorCount member of |
| slink:VkPipelineViewportStateCreateInfo. |
| * ename:VK_DYNAMIC_STATE_LINE_WIDTH specifies that the pname:lineWidth |
| state in slink:VkPipelineRasterizationStateCreateInfo will be ignored |
| and must: be set dynamically with flink:vkCmdSetLineWidth before any |
| drawing 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 |
| slink:VkPipelineRasterizationStateCreateInfo will be ignored and must: |
| be set dynamically with flink:vkCmdSetDepthBias before any draws are |
| performed with pname:depthBiasEnable in |
| slink:VkPipelineRasterizationStateCreateInfo set to ename:VK_TRUE. |
| * ename:VK_DYNAMIC_STATE_BLEND_CONSTANTS specifies that the |
| pname:blendConstants state in slink: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 |
| slink:VkPipelineDepthStencilStateCreateInfo member |
| pname:depthBoundsTestEnable set to ename:VK_TRUE. |
| * ename:VK_DYNAMIC_STATE_STENCIL_COMPARE_MASK specifies that the |
| pname:compareMask state in slink: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 |
| slink:VkPipelineDepthStencilStateCreateInfo member |
| pname:stencilTestEnable set to ename:VK_TRUE |
| * ename:VK_DYNAMIC_STATE_STENCIL_WRITE_MASK specifies that the |
| pname:writeMask state in slink: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 |
| slink:VkPipelineDepthStencilStateCreateInfo member |
| pname:stencilTestEnable set to ename:VK_TRUE |
| * ename:VK_DYNAMIC_STATE_STENCIL_REFERENCE specifies that the |
| pname:reference state in slink: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 |
| slink: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 |
| slink:VkPipelineViewportWScalingStateCreateInfoNV will be ignored and |
| must: be set dynamically with flink:vkCmdSetViewportWScalingNV before |
| any draws are performed with a pipeline state with |
| slink:VkPipelineViewportWScalingStateCreateInfoNV 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_RECTANGLE_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 |
| slink: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 |
| slink:VkPipelineSampleLocationsStateCreateInfoEXT. |
| endif::VK_EXT_sample_locations[] |
| ifdef::VK_NV_scissor_exclusive[] |
| * ename:VK_DYNAMIC_STATE_EXCLUSIVE_SCISSOR_NV specifies that the |
| pname:pExclusiveScissors state in |
| slink:VkPipelineViewportExclusiveScissorStateCreateInfoNV will be |
| ignored and must: be set dynamically with |
| flink:vkCmdSetExclusiveScissorNV before any drawing commands. |
| The number of exclusive scissor rectangles used by a pipeline is still |
| specified by the pname:exclusiveScissorCount member of |
| slink:VkPipelineViewportExclusiveScissorStateCreateInfoNV. |
| endif::VK_NV_scissor_exclusive[] |
| ifdef::VK_NV_shading_rate_image[] |
| * ename:VK_DYNAMIC_STATE_VIEWPORT_SHADING_RATE_PALETTE_NV specifies that |
| the pname:pShadingRatePalettes state in |
| slink:VkPipelineViewportShadingRateImageStateCreateInfoNV will be |
| ignored and must: be set dynamically with |
| flink:vkCmdSetViewportShadingRatePaletteNV before any drawing commands. |
| * ename:VK_DYNAMIC_STATE_VIEWPORT_COARSE_SAMPLE_ORDER_NV specifies that |
| the coarse sample order state in |
| slink:VkPipelineViewportCoarseSampleOrderStateCreateInfoNV will be |
| ignored and must: be set dynamically with |
| flink:vkCmdSetCoarseSampleOrderNV before any drawing commands. |
| endif::VK_NV_shading_rate_image[] |
| ifdef::VK_EXT_line_rasterization[] |
| * ename:VK_DYNAMIC_STATE_LINE_STIPPLE_EXT specifies that the |
| pname:lineStippleFactor and pname:lineStipplePattern state in |
| slink:VkPipelineRasterizationLineStateCreateInfoEXT will be ignored and |
| must: be set dynamically with flink:vkCmdSetLineStippleEXT before any |
| draws are performed with a pipeline state with |
| slink:VkPipelineRasterizationLineStateCreateInfoEXT member |
| pname:stippledLineEnable set to ename:VK_TRUE. |
| endif::VK_EXT_line_rasterization[] |
| ifdef::VK_EXT_extended_dynamic_state[] |
| * ename:VK_DYNAMIC_STATE_CULL_MODE_EXT specifies that the pname:cullMode |
| state in slink:VkPipelineRasterizationStateCreateInfo will be ignored |
| and must: be set dynamically with flink:vkCmdSetCullModeEXT before any |
| drawing commands. |
| * ename:VK_DYNAMIC_STATE_FRONT_FACE_EXT specifies that the pname:frontFace |
| state in slink:VkPipelineRasterizationStateCreateInfo will be ignored |
| and must: be set dynamically with flink:vkCmdSetFrontFaceEXT before any |
| drawing commands. |
| * ename:VK_DYNAMIC_STATE_PRIMITIVE_TOPOLOGY_EXT specifies that the |
| pname:topology state in slink:VkPipelineInputAssemblyStateCreateInfo |
| only specifies the <<drawing-primitive-topology-class, topology class>>, |
| and the specific topology order and adjacency must: be set dynamically |
| with flink:vkCmdSetPrimitiveTopologyEXT before any drawing commands. |
| * ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT specifies that the |
| pname:viewportCount and pname:pViewports state in |
| slink:VkPipelineViewportStateCreateInfo will be ignored and must: be set |
| dynamically with flink:vkCmdSetViewportWithCountEXT before any draw |
| call. |
| * ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT specifies that the |
| pname:scissorCount and pname:pScissors state in |
| slink:VkPipelineViewportStateCreateInfo will be ignored and must: be set |
| dynamically with flink:vkCmdSetScissorWithCountEXT before any draw call. |
| * ename:VK_DYNAMIC_STATE_VERTEX_INPUT_BINDING_STRIDE_EXT specifies that |
| the pname:stride state in slink:VkVertexInputBindingDescription will be |
| ignored and must: be set dynamically with |
| flink:vkCmdBindVertexBuffers2EXT before any draw call. |
| * ename:VK_DYNAMIC_STATE_DEPTH_TEST_ENABLE_EXT specifies that the |
| pname:depthTestEnable state in |
| slink:VkPipelineDepthStencilStateCreateInfo will be ignored and must: be |
| set dynamically with flink:vkCmdSetDepthTestEnableEXT before any draw |
| call. |
| * ename:VK_DYNAMIC_STATE_DEPTH_WRITE_ENABLE_EXT specifies that the |
| pname:depthWriteEnable state in |
| slink:VkPipelineDepthStencilStateCreateInfo will be ignored and must: be |
| set dynamically with flink:vkCmdSetDepthWriteEnableEXT before any draw |
| call. |
| * ename:VK_DYNAMIC_STATE_DEPTH_COMPARE_OP_EXT specifies that the |
| pname:depthCompareOp state in |
| slink:VkPipelineDepthStencilStateCreateInfo will be ignored and must: be |
| set dynamically with flink:vkCmdSetDepthCompareOpEXT before any draw |
| call. |
| * ename:VK_DYNAMIC_STATE_DEPTH_BOUNDS_TEST_ENABLE_EXT specifies that the |
| pname:depthBoundsTestEnable state in |
| slink:VkPipelineDepthStencilStateCreateInfo will be ignored and must: be |
| set dynamically with flink:vkCmdSetDepthBoundsTestEnableEXT before any |
| draw call. |
| * ename:VK_DYNAMIC_STATE_STENCIL_TEST_ENABLE_EXT specifies that the |
| pname:stencilTestEnable state in |
| slink:VkPipelineDepthStencilStateCreateInfo will be ignored and must: be |
| set dynamically with flink:vkCmdSetStencilTestEnableEXT before any draw |
| call. |
| * ename:VK_DYNAMIC_STATE_STENCIL_OP_EXT specifies that the pname:failOp, |
| pname:passOp, pname:depthFailOp, and pname:compareOp states in |
| sname:VkPipelineDepthStencilStateCreateInfo for both pname:front and |
| pname:back will be ignored and must: be set dynamically with |
| flink:vkCmdSetStencilOpEXT before any draws are performed with a |
| pipeline state with sname:VkPipelineDepthStencilStateCreateInfo member |
| pname:stencilTestEnable set to ename:VK_TRUE |
| endif::VK_EXT_extended_dynamic_state[] |
| ifdef::VK_EXT_extended_dynamic_state2[] |
| * ename:VK_DYNAMIC_STATE_PATCH_CONTROL_POINTS_EXT specifies that the |
| pname:patchControlPoints state in |
| slink:VkPipelineTessellationStateCreateInfo will be ignored and must: be |
| set dynamically with flink:vkCmdSetPatchControlPointsEXT before any |
| drawing commands. |
| * ename:VK_DYNAMIC_STATE_RASTERIZER_DISCARD_ENABLE_EXT specifies that the |
| pname:rasterizerDiscardEnable state in |
| slink:VkPipelineRasterizationStateCreateInfo will be ignored and must: |
| be set dynamically with flink:vkCmdSetRasterizerDiscardEnableEXT before |
| any drawing commands. |
| * ename:VK_DYNAMIC_STATE_DEPTH_BIAS_ENABLE_EXT specifies that the |
| pname:depthBiasEnable state in |
| slink:VkPipelineRasterizationStateCreateInfo will be ignored and must: |
| be set dynamically with flink:vkCmdSetDepthBiasEnableEXT before any |
| drawing commands. |
| * ename:VK_DYNAMIC_STATE_LOGIC_OP_EXT specifies that the pname:logicOp |
| state in slink:VkPipelineColorBlendStateCreateInfo will be ignored and |
| must: be set dynamically with flink:vkCmdSetLogicOpEXT before any |
| drawing commands. |
| * ename:VK_DYNAMIC_STATE_PRIMITIVE_RESTART_ENABLE_EXT specifies that the |
| pname:primitiveRestartEnable state in |
| slink:VkPipelineInputAssemblyStateCreateInfo will be ignored and must: |
| be set dynamically with flink:vkCmdSetPrimitiveRestartEnableEXT before |
| any drawing commands. |
| endif::VK_EXT_extended_dynamic_state2[] |
| ifdef::VK_KHR_fragment_shading_rate[] |
| * ename:VK_DYNAMIC_STATE_FRAGMENT_SHADING_RATE_KHR specifies that state in |
| slink:VkPipelineFragmentShadingRateStateCreateInfoKHR |
| ifdef::VK_NV_fragment_shading_rate_enums[] |
| and slink:VkPipelineFragmentShadingRateEnumStateCreateInfoNV |
| endif::VK_NV_fragment_shading_rate_enums[] |
| will be ignored and must: be set dynamically with |
| flink:vkCmdSetFragmentShadingRateKHR |
| ifdef::VK_NV_fragment_shading_rate_enums[] |
| or flink:vkCmdSetFragmentShadingRateEnumNV |
| endif::VK_NV_fragment_shading_rate_enums[] |
| before any drawing commands. |
| endif::VK_KHR_fragment_shading_rate[] |
| ifdef::VK_KHR_ray_tracing_pipeline[] |
| * ename:VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR specifies |
| that the default stack size computation for the pipeline will be ignored |
| and must: be set dynamically with |
| flink:vkCmdSetRayTracingPipelineStackSizeKHR before any ray tracing |
| calls are performed. |
| endif::VK_KHR_ray_tracing_pipeline[] |
| ifdef::VK_EXT_vertex_input_dynamic_state[] |
| * ename:VK_DYNAMIC_STATE_VERTEX_INPUT_EXT specifies that the |
| pname:pVertexInputState state will be ignored and must: be set |
| dynamically with flink:vkCmdSetVertexInputEXT before any drawing |
| commands |
| endif::VK_EXT_vertex_input_dynamic_state[] |
| ifdef::VK_EXT_color_write_enable[] |
| * ename:VK_DYNAMIC_STATE_COLOR_WRITE_ENABLE_EXT specifies that the |
| pname:pColorWriteEnables state in |
| slink:VkPipelineColorWriteCreateInfoEXT will be ignored and must: be set |
| dynamically with flink:vkCmdSetColorWriteEnableEXT before any draw call. |
| endif::VK_EXT_color_write_enable[] |
| -- |
| |
| |
| === Valid Combinations of Stages for Graphics Pipelines |
| |
| ifdef::VK_NV_mesh_shader[] |
| The geometric primitive processing can either be handled on a per primitive |
| basis by the vertex, tessellation, and geometry shader stages, or on a per |
| mesh basis using task and mesh shader stages. |
| If the pipeline includes a mesh shader stage, it uses the mesh pipeline, |
| otherwise it uses the primitive pipeline. |
| |
| If a task shader is omitted, the task shading stage is skipped. |
| endif::VK_NV_mesh_shader[] |
| |
| 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, fragment color outputs have undefined: |
| values, and the fragment depth value is unmodified. |
| This can: be useful for depth-only rendering. |
| |
| Presence of a shader stage in a pipeline is indicated by including a valid |
| slink: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 |
| ifdef::VK_NV_mesh_shader[] |
| * Rendering pipeline with task and mesh shaders |
| ** Active Pipeline Shader Stages |
| *** Task Shader |
| *** Mesh Shader |
| *** Fragment Shader |
| ** Required: Fixed-Function Pipeline Stages |
| *** slink:VkPipelineViewportStateCreateInfo |
| *** slink:VkPipelineRasterizationStateCreateInfo |
| *** slink:VkPipelineMultisampleStateCreateInfo |
| *** slink:VkPipelineDepthStencilStateCreateInfo |
| *** slink:VkPipelineColorBlendStateCreateInfo |
| endif::VK_NV_mesh_shader[] |
| |
| |
| ifdef::VK_NV_device_generated_commands[] |
| [[graphics-shadergroups]] |
| === Graphics Pipeline Shader Groups |
| |
| Graphics pipelines can contain multiple shader groups that can be bound |
| individually. |
| Each shader group behaves as if it was a pipeline using the shader group's |
| state. |
| When the pipeline is bound by regular means, it behaves as if the state of |
| group `0` is active, use flink:vkCmdBindPipelineShaderGroupNV to bind an |
| invidual shader group. |
| |
| The primary purpose of shader groups is allowing the device to bind |
| different pipeline state using <<device-generated-commands>>. |
| |
| [open,refpage='VkGraphicsPipelineShaderGroupsCreateInfoNV',desc='Structure specifying parameters of a newly created multi shader group pipeline',type='structs'] |
| -- |
| The sname:VkGraphicsPipelineShaderGroupsCreateInfoNV structure is defined |
| as: |
| |
| include::{generated}/api/structs/VkGraphicsPipelineShaderGroupsCreateInfoNV.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:groupCount is the number of elements in the pname:pGroups array. |
| * pname:pGroups is a pointer to an array of |
| slink:VkGraphicsShaderGroupCreateInfoNV structures specifying which |
| state of the original slink:VkGraphicsPipelineCreateInfo each shader |
| group overrides. |
| * pname:pipelineCount is the number of elements in the pname:pPipelines |
| array. |
| * pname:pPipelines is a pointer to an array of graphics sname:VkPipeline |
| structures which are referenced within the created pipeline, including |
| all their shader groups. |
| |
| When referencing shader groups by index, groups defined in the referenced |
| pipelines are treated as if they were defined as additional entries in |
| pname:pGroups. |
| They are appended in the order they appear in the pname:pPipelines array and |
| in the pname:pGroups array when those pipelines were defined. |
| |
| The application must: maintain the lifetime of all such referenced pipelines |
| based on the pipelines that make use of them. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-groupCount-02879]] |
| pname:groupCount must: be at least `1` and as maximum |
| sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxGraphicsShaderGroupCount |
| * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-groupCount-02880]] |
| The sum of pname:groupCount including those groups added from referenced |
| pname:pPipelines must: also be as maximum |
| sname:VkPhysicalDeviceDeviceGeneratedCommandsPropertiesNV::pname:maxGraphicsShaderGroupCount |
| * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02881]] |
| The state of the first element of pname:pGroups must: match its |
| equivalent within the parent's slink:VkGraphicsPipelineCreateInfo |
| * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02882]] |
| Each element of pname:pGroups must: in combination with the rest of the |
| pipeline state yield a valid state configuration |
| ifndef::VK_NV_mesh_shader[] |
| * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02883]] |
| All elements of pname:pGroups must: use the same shader stage |
| combinations |
| endif::VK_NV_mesh_shader[] |
| ifdef::VK_NV_mesh_shader[] |
| * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02884]] |
| All elements of pname:pGroups must: use the same shader stage |
| combinations unless any mesh shader stage is used, then either |
| combination of task and mesh or just mesh shader is valid |
| * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pGroups-02885]] |
| Mesh and regular primitive shading stages cannot be mixed across |
| pname:pGroups |
| endif::VK_NV_mesh_shader[] |
| * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-pPipelines-02886]] |
| Each element of pname:pPipelines must: have been created with identical |
| state to the pipeline currently created except the state that can be |
| overridden by slink:VkGraphicsShaderGroupCreateInfoNV |
| * [[VUID-VkGraphicsPipelineShaderGroupsCreateInfoNV-deviceGeneratedCommands-02887]] |
| The <<features-deviceGeneratedCommands, |
| sname:VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV::pname:deviceGeneratedCommands>> |
| feature must: be enabled |
| **** |
| |
| include::{generated}/validity/structs/VkGraphicsPipelineShaderGroupsCreateInfoNV.txt[] |
| -- |
| |
| [open,refpage='VkGraphicsShaderGroupCreateInfoNV',desc='Structure specifying override parameters for each shader group',type='structs'] |
| -- |
| The sname:VkGraphicsShaderGroupCreateInfoNV structure provides the state |
| overrides for each shader group. |
| Each shader group behaves like a pipeline that was created from its state as |
| well as the remaining parent's state. |
| It is defined as: |
| |
| include::{generated}/api/structs/VkGraphicsShaderGroupCreateInfoNV.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:stageCount is the number of entries in the pname:pStages array. |
| * pname:pStages is a pointer to an array |
| slink:VkPipelineShaderStageCreateInfo structures specifying the set of |
| the shader stages to be included in this shader group. |
| * pname:pVertexInputState is a pointer to a |
| slink:VkPipelineVertexInputStateCreateInfo structure. |
| * pname:pTessellationState is a pointer to a |
| slink:VkPipelineTessellationStateCreateInfo structure, and is ignored if |
| the shader group does not include a tessellation control shader stage |
| and tessellation evaluation shader stage. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkGraphicsShaderGroupCreateInfoNV-stageCount-02888]] |
| For pname:stageCount, the same restrictions as in |
| slink:VkGraphicsPipelineCreateInfo::pname:stageCount apply |
| * [[VUID-VkGraphicsShaderGroupCreateInfoNV-pStages-02889]] |
| For pname:pStages, the same restrictions as in |
| slink:VkGraphicsPipelineCreateInfo::pname:pStages apply |
| * [[VUID-VkGraphicsShaderGroupCreateInfoNV-pVertexInputState-02890]] |
| For pname:pVertexInputState, the same restrictions as in |
| slink:VkGraphicsPipelineCreateInfo::pname:pVertexInputState apply |
| * [[VUID-VkGraphicsShaderGroupCreateInfoNV-pTessellationState-02891]] |
| For pname:pTessellationState, the same restrictions as in |
| slink:VkGraphicsPipelineCreateInfo::pname:pTessellationState apply |
| **** |
| |
| include::{generated}/validity/structs/VkGraphicsShaderGroupCreateInfoNV.txt[] |
| -- |
| endif::VK_NV_device_generated_commands[] |
| |
| |
| ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] |
| [[pipelines-ray-tracing]] |
| == Ray Tracing Pipelines |
| |
| Ray tracing pipelines consist of multiple shader stages, fixed-function |
| traversal stages, and a pipeline layout. |
| |
| [open,refpage='VK_SHADER_UNUSED_KHR',desc='Sentinel for an unused shader index',type='consts',alias='VK_SHADER_UNUSED_NV'] |
| -- |
| ename:VK_SHADER_UNUSED_KHR is a special shader index used to indicate that a |
| ray generation, miss, or callable shader member is not used. |
| |
| include::{generated}/api/enums/VK_SHADER_UNUSED_KHR.txt[] |
| |
| ifdef::VK_NV_ray_tracing[] |
| or the equivalent |
| |
| include::{generated}/api/enums/VK_SHADER_UNUSED_NV.txt[] |
| endif::VK_NV_ray_tracing[] |
| -- |
| |
| ifdef::VK_NV_ray_tracing[] |
| [open,refpage='vkCreateRayTracingPipelinesNV',desc='Creates a new ray tracing pipeline object',type='protos'] |
| -- |
| :refpage: vkCreateRayTracingPipelinesNV |
| |
| To create ray tracing pipelines, call: |
| |
| include::{generated}/api/protos/vkCreateRayTracingPipelinesNV.txt[] |
| |
| * pname:device is the logical device that creates the ray tracing |
| 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 a pointer to an array of |
| slink:VkRayTracingPipelineCreateInfoNV 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 ray |
| tracing pipeline objects are returned. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/create_ray_tracing_pipelines_common.txt[] |
| **** |
| |
| include::{generated}/validity/protos/vkCreateRayTracingPipelinesNV.txt[] |
| -- |
| endif::VK_NV_ray_tracing[] |
| |
| ifdef::VK_KHR_ray_tracing_pipeline[] |
| [open,refpage='vkCreateRayTracingPipelinesKHR',desc='Creates a new ray tracing pipeline object',type='protos'] |
| -- |
| :refpage: vkCreateRayTracingPipelinesKHR |
| |
| To create ray tracing pipelines, call: |
| |
| include::{generated}/api/protos/vkCreateRayTracingPipelinesKHR.txt[] |
| |
| * pname:device is the logical device that creates the ray tracing |
| pipelines. |
| * pname:deferredOperation is dlink:VK_NULL_HANDLE or the handle of a valid |
| slink:VkDeferredOperationKHR <<deferred-host-operations-requesting, |
| request deferral>> object for this command. |
| * 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 a pointer to an array of |
| slink:VkRayTracingPipelineCreateInfoKHR 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 ray |
| tracing pipeline objects are returned. |
| |
| The ename:VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS error is returned if the |
| implementation is unable to re-use the shader group handles provided in |
| slink:VkRayTracingShaderGroupCreateInfoKHR::pname:pShaderGroupCaptureReplayHandle |
| when |
| slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR::pname:rayTracingPipelineShaderGroupHandleCaptureReplay |
| is enabled. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/create_ray_tracing_pipelines_common.txt[] |
| include::{chapters}/commonvalidity/deferred_operations_common.txt[] |
| * [[VUID-vkCreateRayTracingPipelinesKHR-rayTracingPipeline-03586]] |
| The <<features-rayTracingPipeline, pname:rayTracingPipeline>> feature |
| must: be enabled |
| ifdef::VK_EXT_pipeline_creation_cache_control+VK_KHR_deferred_host_operations[] |
| * [[VUID-vkCreateRayTracingPipelinesKHR-deferredOperation-03587]] |
| If pname:deferredOperation is not dlink:VK_NULL_HANDLE, the pname:flags |
| member of elements of pname:pCreateInfos must: not include |
| ename:VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT |
| endif::VK_EXT_pipeline_creation_cache_control+VK_KHR_deferred_host_operations[] |
| **** |
| |
| include::{generated}/validity/protos/vkCreateRayTracingPipelinesKHR.txt[] |
| -- |
| endif::VK_KHR_ray_tracing_pipeline[] |
| |
| ifdef::VK_NV_ray_tracing[] |
| [open,refpage='VkRayTracingPipelineCreateInfoNV',desc='Structure specifying parameters of a newly created ray tracing pipeline',type='structs'] |
| -- |
| :refpage: VkRayTracingPipelineCreateInfoNV |
| |
| The sname:VkRayTracingPipelineCreateInfoNV structure is defined as: |
| |
| include::{generated}/api/structs/VkRayTracingPipelineCreateInfoNV.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is a bitmask of elink:VkPipelineCreateFlagBits specifying |
| how the pipeline will be generated. |
| * pname:stageCount is the number of entries in the pname:pStages array. |
| * pname:pStages is a pointer to an array of |
| slink:VkPipelineShaderStageCreateInfo structures specifying the set of |
| the shader stages to be included in the ray tracing pipeline. |
| * pname:groupCount is the number of entries in the pname:pGroups array. |
| * pname:pGroups is a pointer to an array of |
| slink:VkRayTracingShaderGroupCreateInfoNV structures describing the set |
| of the shader stages to be included in each shader group in the ray |
| tracing pipeline. |
| * pname:maxRecursionDepth is the <<ray-tracing-recursion-depth, maximum |
| recursion depth>> of shaders executed by this pipeline. |
| * 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>>. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/ray_tracing_pipeline_create_info_common.txt[] |
| * [[VUID-VkRayTracingPipelineCreateInfoNV-stage-06232]] |
| The pname:stage member of at least one element of pname:pStages must: be |
| ename:VK_SHADER_STAGE_RAYGEN_BIT_KHR |
| ifdef::VK_KHR_pipeline_library[] |
| * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03456]] |
| pname:flags must: not include ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR |
| endif::VK_KHR_pipeline_library[] |
| * [[VUID-VkRayTracingPipelineCreateInfoNV-maxRecursionDepth-03457]] |
| pname:maxRecursionDepth must: be less than or equal to |
| slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxRecursionDepth |
| ifdef::VK_KHR_ray_tracing_pipeline[] |
| * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03458]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR |
| * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03459]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR |
| * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03460]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR |
| * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03461]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR |
| * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03462]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR |
| * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03463]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR |
| * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-03588]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR |
| endif::VK_KHR_ray_tracing_pipeline[] |
| ifdef::VK_NV_ray_tracing_motion_blur[] |
| * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-04948]] |
| pname:flags must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV |
| endif::VK_NV_ray_tracing_motion_blur[] |
| ifdef::VK_EXT_pipeline_creation_cache_control[] |
| * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-02957]] |
| pname:flags must: not include both |
| ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV and |
| ename:VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT at |
| the same time |
| endif::VK_EXT_pipeline_creation_cache_control[] |
| **** |
| |
| include::{generated}/validity/structs/VkRayTracingPipelineCreateInfoNV.txt[] |
| -- |
| endif::VK_NV_ray_tracing[] |
| |
| ifdef::VK_KHR_ray_tracing_pipeline[] |
| [open,refpage='VkRayTracingPipelineCreateInfoKHR',desc='Structure specifying parameters of a newly created ray tracing pipeline',type='structs'] |
| -- |
| :refpage: VkRayTracingPipelineCreateInfoKHR |
| |
| The sname:VkRayTracingPipelineCreateInfoKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkRayTracingPipelineCreateInfoKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:flags is a bitmask of elink:VkPipelineCreateFlagBits specifying |
| how the pipeline will be generated. |
| * pname:stageCount is the number of entries in the pname:pStages array. |
| * pname:pStages is a pointer to an array of pname:stageCount |
| slink:VkPipelineShaderStageCreateInfo structures describing the set of |
| the shader stages to be included in the ray tracing pipeline. |
| * pname:groupCount is the number of entries in the pname:pGroups array. |
| * pname:pGroups is a pointer to an array of pname:groupCount |
| slink:VkRayTracingShaderGroupCreateInfoKHR structures describing the set |
| of the shader stages to be included in each shader group in the ray |
| tracing pipeline. |
| * pname:maxPipelineRayRecursionDepth is the <<ray-tracing-recursion-depth, |
| maximum recursion depth>> of shaders executed by this pipeline. |
| * pname:pLibraryInfo is a pointer to a |
| slink:VkPipelineLibraryCreateInfoKHR structure defining pipeline |
| libraries to include. |
| * pname:pLibraryInterface is a pointer to a |
| slink:VkRayTracingPipelineInterfaceCreateInfoKHR structure defining |
| additional information when using pipeline libraries. |
| * pname:pDynamicState is a pointer to a |
| slink:VkPipelineDynamicStateCreateInfo structure, 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: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>>. |
| |
| ifdef::VK_KHR_pipeline_library[] |
| When ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR is specified, this pipeline |
| defines a _pipeline library_ which cannot: be bound as a ray tracing |
| pipeline directly. |
| Instead, pipeline libraries define common shaders and shader groups which |
| can: be included in future pipeline creation. |
| |
| If pipeline libraries are included in pname:pLibraryInfo, shaders defined in |
| those libraries are treated as if they were defined as additional entries in |
| pname:pStages, appended in the order they appear in the pname:pLibraries |
| array and in the pname:pStages array when those libraries were defined. |
| |
| When referencing shader groups in order to obtain a shader group handle, |
| groups defined in those libraries are treated as if they were defined as |
| additional entries in pname:pGroups, appended in the order they appear in |
| the pname:pLibraries array and in the pname:pGroups array when those |
| libraries were defined. |
| The shaders these groups reference are set when the pipeline library is |
| created, referencing those specified in the pipeline library, not in the |
| pipeline that includes it. |
| endif::VK_KHR_pipeline_library[] |
| |
| The default stack size for a pipeline if |
| ename:VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR is not provided |
| is computed as described in <<ray-tracing-pipeline-stack, Ray Tracing |
| Pipeline Stack>>. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/ray_tracing_pipeline_create_info_common.txt[] |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-stage-03425]] |
| If pname:flags does not include |
| ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR, the pname:stage member of at |
| least one element of pname:pStages, including those implicitly added by |
| pname:pLibraryInfo, must: be ename:VK_SHADER_STAGE_RAYGEN_BIT_KHR |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-maxPipelineRayRecursionDepth-03589]] |
| pname:maxPipelineRayRecursionDepth must: be less than or equal to |
| slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR::pname:maxRayRecursionDepth |
| ifdef::VK_KHR_pipeline_library[] |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-03465]] |
| If pname:flags includes ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR, |
| pname:pLibraryInterface must: not be `NULL` |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03590]] |
| If pname:pLibraryInfo is not `NULL` and its pname:libraryCount member is |
| greater than `0`, its pname:pLibraryInterface member must: not be `NULL` |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraries-03591]] |
| Each element of pname:pLibraryInfo->pLibraries must: have been created |
| with the value of pname:maxPipelineRayRecursionDepth equal to that in |
| this pipeline |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03592]] |
| If pname:pLibraryInfo is not `NULL`, each element of its |
| pname:pLibraries member must: have been created with a pname:layout that |
| is compatible with the pname:layout in this pipeline |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03593]] |
| If pname:pLibraryInfo is not `NULL`, each element of its |
| pname:pLibraries member must: have been created with values of the |
| pname:maxPipelineRayPayloadSize and pname:maxPipelineRayHitAttributeSize |
| members of pname:pLibraryInterface equal to those in this pipeline |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-03594]] |
| If pname:flags includes |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR, |
| each element of pname:pLibraryInfo->pLibraries must: have been created |
| with the |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR |
| bit set |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-04718]] |
| If pname:flags includes |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR, each element of |
| pname:pLibraryInfo->pLibraries must: have been created with the |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR bit set |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-04719]] |
| If pname:flags includes |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR, each |
| element of pname:pLibraryInfo->pLibraries must: have been created with |
| the ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR bit set |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-04720]] |
| If pname:flags includes |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR, |
| each element of pname:pLibraryInfo->pLibraries must: have been created |
| with the |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR bit |
| set |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-04721]] |
| If pname:flags includes |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, |
| each element of pname:pLibraryInfo->pLibraries must: have been created |
| with the |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR |
| bit set |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-04722]] |
| If pname:flags includes |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR, |
| each element of pname:pLibraryInfo->pLibraries must: have been created |
| with the |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR |
| bit set |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-04723]] |
| If pname:flags includes |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR, each |
| element of pname:pLibraryInfo->pLibraries must: have been created with |
| the ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR |
| bit set |
| endif::VK_KHR_pipeline_library[] |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03595]] |
| If the `apiext:VK_KHR_pipeline_library` extension is not enabled, |
| pname:pLibraryInfo and pname:pLibraryInterface must: be `NULL` |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-03470]] |
| If pname:flags includes |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR, |
| for any element of pname:pGroups with a pname:type of |
| ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or |
| ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, the |
| pname:anyHitShader of that element must: not be |
| ename:VK_SHADER_UNUSED_KHR |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-03471]] |
| If pname:flags includes |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR, |
| for any element of pname:pGroups with a pname:type of |
| ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or |
| ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, the |
| pname:closestHitShader of that element must: not be |
| ename:VK_SHADER_UNUSED_KHR |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-rayTraversalPrimitiveCulling-03596]] |
| If the <<features-rayTraversalPrimitiveCulling, |
| pname:rayTraversalPrimitiveCulling>> feature is not enabled, pname:flags |
| must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-rayTraversalPrimitiveCulling-03597]] |
| If the <<features-rayTraversalPrimitiveCulling, |
| pname:rayTraversalPrimitiveCulling>> feature is not enabled, pname:flags |
| must: not include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-flags-03598]] |
| If pname:flags includes |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR, |
| <<features-rayTracingPipelineShaderGroupHandleCaptureReplay, |
| pname:rayTracingPipelineShaderGroupHandleCaptureReplay>> must: be |
| enabled |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-rayTracingPipelineShaderGroupHandleCaptureReplay-03599]] |
| If |
| slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR::pname:rayTracingPipelineShaderGroupHandleCaptureReplay |
| is ename:VK_TRUE and the pname:pShaderGroupCaptureReplayHandle member of |
| any element of pname:pGroups is not `NULL`, pname:flags must: include |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03600]] |
| If pname:pLibraryInfo is not `NULL` and its pname:libraryCount is `0`, |
| pname:stageCount must: not be `0` |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-pLibraryInfo-03601]] |
| If pname:pLibraryInfo is not `NULL` and its pname:libraryCount is `0`, |
| pname:groupCount must: not be `0` |
| * [[VUID-VkRayTracingPipelineCreateInfoKHR-pDynamicStates-03602]] |
| Any element of the pname:pDynamicStates member of pname:pDynamicState |
| must: be ename:VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR |
| **** |
| |
| include::{generated}/validity/structs/VkRayTracingPipelineCreateInfoKHR.txt[] |
| -- |
| endif::VK_KHR_ray_tracing_pipeline[] |
| |
| ifdef::VK_NV_ray_tracing[] |
| [open,refpage='VkRayTracingShaderGroupCreateInfoNV',desc='Structure specifying shaders in a shader group',type='structs'] |
| -- |
| :refpage: VkRayTracingShaderGroupCreateInfoNV |
| |
| The sname:VkRayTracingShaderGroupCreateInfoNV structure is defined as: |
| |
| include::{generated}/api/structs/VkRayTracingShaderGroupCreateInfoNV.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:type is the type of hit group specified in this structure. |
| * pname:generalShader is the index of the ray generation, miss, or |
| callable shader from |
| slink:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group if |
| the shader group has pname:type of |
| ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV, and |
| ename:VK_SHADER_UNUSED_NV otherwise. |
| * pname:closestHitShader is the optional index of the closest hit shader |
| from slink:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group |
| if the shader group has pname:type of |
| ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV or |
| ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV, and |
| ename:VK_SHADER_UNUSED_NV otherwise. |
| * pname:anyHitShader is the optional index of the any-hit shader from |
| slink:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group if |
| the shader group has pname:type of |
| ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV or |
| ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV, and |
| ename:VK_SHADER_UNUSED_NV otherwise. |
| * pname:intersectionShader is the index of the intersection shader from |
| slink:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group if |
| the shader group has pname:type of |
| ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV, and |
| ename:VK_SHADER_UNUSED_NV otherwise. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02413]] |
| If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV then |
| pname:generalShader must: be a valid index into |
| slink:VkRayTracingPipelineCreateInfoNV::pname:pStages referring to a |
| shader of ename:VK_SHADER_STAGE_RAYGEN_BIT_NV, |
| ename:VK_SHADER_STAGE_MISS_BIT_NV, or |
| ename:VK_SHADER_STAGE_CALLABLE_BIT_NV |
| * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02414]] |
| If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV then |
| pname:closestHitShader, pname:anyHitShader, and pname:intersectionShader |
| must: be ename:VK_SHADER_UNUSED_NV |
| * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02415]] |
| If pname:type is |
| ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV then |
| pname:intersectionShader must: be a valid index into |
| slink:VkRayTracingPipelineCreateInfoNV::pname:pStages referring to a |
| shader of ename:VK_SHADER_STAGE_INTERSECTION_BIT_NV |
| * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02416]] |
| If pname:type is |
| ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV then |
| pname:intersectionShader must: be ename:VK_SHADER_UNUSED_NV |
| * [[VUID-VkRayTracingShaderGroupCreateInfoNV-closestHitShader-02417]] |
| pname:closestHitShader must: be either ename:VK_SHADER_UNUSED_NV or a |
| valid index into slink:VkRayTracingPipelineCreateInfoNV::pname:pStages |
| referring to a shader of ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_NV |
| * [[VUID-VkRayTracingShaderGroupCreateInfoNV-anyHitShader-02418]] |
| pname:anyHitShader must: be either ename:VK_SHADER_UNUSED_NV or a valid |
| index into slink:VkRayTracingPipelineCreateInfoNV::pname:pStages |
| referring to a shader of ename:VK_SHADER_STAGE_ANY_HIT_BIT_NV |
| **** |
| |
| include::{generated}/validity/structs/VkRayTracingShaderGroupCreateInfoNV.txt[] |
| -- |
| |
| endif::VK_NV_ray_tracing[] |
| |
| ifdef::VK_KHR_ray_tracing_pipeline[] |
| [open,refpage='VkRayTracingShaderGroupCreateInfoKHR',desc='Structure specifying shaders in a shader group',type='structs'] |
| -- |
| :refpage: VkRayTracingShaderGroupCreateInfoKHR |
| |
| The sname:VkRayTracingShaderGroupCreateInfoKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkRayTracingShaderGroupCreateInfoKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:type is the type of hit group specified in this structure. |
| * pname:generalShader is the index of the ray generation, miss, or |
| callable shader from |
| slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages in the group if |
| the shader group has pname:type of |
| ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR, and |
| ename:VK_SHADER_UNUSED_KHR otherwise. |
| * pname:closestHitShader is the optional index of the closest hit shader |
| from slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages in the group |
| if the shader group has pname:type of |
| ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or |
| ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, and |
| ename:VK_SHADER_UNUSED_KHR otherwise. |
| * pname:anyHitShader is the optional index of the any-hit shader from |
| slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages in the group if |
| the shader group has pname:type of |
| ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR or |
| ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, and |
| ename:VK_SHADER_UNUSED_KHR otherwise. |
| * pname:intersectionShader is the index of the intersection shader from |
| slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages in the group if |
| the shader group has pname:type of |
| ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR, and |
| ename:VK_SHADER_UNUSED_KHR otherwise. |
| * pname:pShaderGroupCaptureReplayHandle is `NULL` or a pointer to replay |
| information for this shader group. |
| Ignored if |
| slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR::pname:rayTracingPipelineShaderGroupHandleCaptureReplay |
| is ename:VK_FALSE. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-type-03474]] |
| If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR then |
| pname:generalShader must: be a valid index into |
| slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages referring to a |
| shader of ename:VK_SHADER_STAGE_RAYGEN_BIT_KHR, |
| ename:VK_SHADER_STAGE_MISS_BIT_KHR, or |
| ename:VK_SHADER_STAGE_CALLABLE_BIT_KHR |
| * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-type-03475]] |
| If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR then |
| pname:closestHitShader, pname:anyHitShader, and pname:intersectionShader |
| must: be ename:VK_SHADER_UNUSED_KHR |
| * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-type-03476]] |
| If pname:type is |
| ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR then |
| pname:intersectionShader must: be a valid index into |
| slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages referring to a |
| shader of ename:VK_SHADER_STAGE_INTERSECTION_BIT_KHR |
| * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-type-03477]] |
| If pname:type is |
| ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR then |
| pname:intersectionShader must: be ename:VK_SHADER_UNUSED_KHR |
| * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-closestHitShader-03478]] |
| pname:closestHitShader must: be either ename:VK_SHADER_UNUSED_KHR or a |
| valid index into slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages |
| referring to a shader of ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_KHR |
| * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-anyHitShader-03479]] |
| pname:anyHitShader must: be either ename:VK_SHADER_UNUSED_KHR or a valid |
| index into slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages |
| referring to a shader of ename:VK_SHADER_STAGE_ANY_HIT_BIT_KHR |
| * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-rayTracingPipelineShaderGroupHandleCaptureReplayMixed-03603]] |
| If |
| slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR::pname:rayTracingPipelineShaderGroupHandleCaptureReplayMixed |
| is ename:VK_FALSE then pname:pShaderGroupCaptureReplayHandle must: not |
| be provided if it has not been provided on a previous call to ray |
| tracing pipeline creation |
| * [[VUID-VkRayTracingShaderGroupCreateInfoKHR-rayTracingPipelineShaderGroupHandleCaptureReplayMixed-03604]] |
| If |
| slink:VkPhysicalDeviceRayTracingPipelineFeaturesKHR::pname:rayTracingPipelineShaderGroupHandleCaptureReplayMixed |
| is ename:VK_FALSE then the caller must: guarantee that no ray tracing |
| pipeline creation commands with pname:pShaderGroupCaptureReplayHandle |
| provided execute simultaneously with ray tracing pipeline creation |
| commands without pname:pShaderGroupCaptureReplayHandle provided |
| **** |
| |
| include::{generated}/validity/structs/VkRayTracingShaderGroupCreateInfoKHR.txt[] |
| -- |
| endif::VK_KHR_ray_tracing_pipeline[] |
| |
| [open,refpage='VkRayTracingShaderGroupTypeKHR',desc='Shader group types',type='enums',alias='VkRayTracingShaderGroupTypeNV'] |
| -- |
| :refpage: VkRayTracingShaderGroupTypeKHR |
| |
| Possible values of pname:type in sname:VkRayTracingShaderGroupCreateInfoKHR |
| are: |
| |
| include::{generated}/api/enums/VkRayTracingShaderGroupTypeKHR.txt[] |
| |
| ifdef::VK_NV_ray_tracing[] |
| or the equivalent |
| |
| include::{generated}/api/enums/VkRayTracingShaderGroupTypeNV.txt[] |
| endif::VK_NV_ray_tracing[] |
| |
| * ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_KHR indicates a shader |
| group with a single ename:VK_SHADER_STAGE_RAYGEN_BIT_KHR, |
| ename:VK_SHADER_STAGE_MISS_BIT_KHR, or |
| ename:VK_SHADER_STAGE_CALLABLE_BIT_KHR shader in it. |
| * ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_KHR specifies |
| a shader group that only hits triangles and must: not contain an |
| intersection shader, only closest hit and any-hit shaders. |
| * ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_KHR |
| specifies a shader group that only intersects with custom geometry and |
| must: contain an intersection shader and may: contain closest hit and |
| any-hit shaders. |
| |
| [NOTE] |
| .Note |
| ==== |
| For current group types, the hit group type could be inferred from the |
| presence or absence of the intersection shader, but we provide the type |
| explicitly for future hit groups that do not have that property. |
| ==== |
| -- |
| |
| ifdef::VK_KHR_ray_tracing_pipeline[] |
| [open,refpage='VkRayTracingPipelineInterfaceCreateInfoKHR',desc='Structure specifying additional interface information when using libraries',type='structs'] |
| -- |
| :refpage: VkRayTracingPipelineInterfaceCreateInfoKHR |
| |
| The sname:VkRayTracingPipelineInterfaceCreateInfoKHR structure is defined |
| as: |
| |
| include::{generated}/api/structs/VkRayTracingPipelineInterfaceCreateInfoKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:maxPipelineRayPayloadSize is the maximum payload size in bytes |
| used by any shader in the pipeline. |
| * pname:maxPipelineRayHitAttributeSize is the maximum attribute structure |
| size in bytes used by any shader in the pipeline. |
| |
| pname:maxPipelineRayPayloadSize is calculated as the maximum number of bytes |
| used by any block declared in the code:RayPayloadKHR or |
| code:IncomingRayPayloadKHR storage classes. |
| pname:maxPipelineRayHitAttributeSize is calculated as the maximum number of |
| bytes used by any block declared in the code:HitAttributeKHR storage class. |
| As variables in these storage classes do not have explicit offsets, the size |
| should be calculated as if each variable has a |
| <<interfaces-alignment-requirements, scalar alignment>> equal to the largest |
| scalar alignment of any of the block's members. |
| |
| [NOTE] |
| .Note |
| ==== |
| There is no explicit upper limit for pname:maxPipelineRayPayloadSize, but in |
| practice it should be kept as small as possible. |
| Similar to invocation local memory, it must be allocated for each shader |
| invocation and for devices which support many simultaneous invocations, this |
| storage can rapidly be exhausted, resulting in failure. |
| ==== |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkRayTracingPipelineInterfaceCreateInfoKHR-maxPipelineRayHitAttributeSize-03605]] |
| pname:maxPipelineRayHitAttributeSize must: be less than or equal to |
| slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR::pname:maxRayHitAttributeSize |
| **** |
| |
| include::{generated}/validity/structs/VkRayTracingPipelineInterfaceCreateInfoKHR.txt[] |
| -- |
| endif::VK_KHR_ray_tracing_pipeline[] |
| |
| [open,refpage='vkGetRayTracingShaderGroupHandlesKHR',desc='Query ray tracing pipeline shader group handles',type='protos',alias='vkGetRayTracingShaderGroupHandlesNV'] |
| -- |
| :refpage: vkGetRayTracingShaderGroupHandlesKHR |
| |
| To query the opaque handles of shaders in the ray tracing pipeline, call: |
| |
| ifdef::VK_KHR_ray_tracing_pipeline[] |
| include::{generated}/api/protos/vkGetRayTracingShaderGroupHandlesKHR.txt[] |
| endif::VK_KHR_ray_tracing_pipeline[] |
| |
| ifdef::VK_KHR_ray_tracing_pipeline+VK_NV_ray_tracing[or the equivalent command] |
| |
| ifdef::VK_NV_ray_tracing[] |
| include::{generated}/api/protos/vkGetRayTracingShaderGroupHandlesNV.txt[] |
| endif::VK_NV_ray_tracing[] |
| |
| * pname:device is the logical device containing the ray tracing pipeline. |
| * pname:pipeline is the ray tracing pipeline object containing the |
| shaders. |
| * pname:firstGroup is the index of the first group to retrieve a handle |
| for from the |
| ifdef::VK_KHR_ray_tracing_pipeline[] |
| slink:VkRayTracingPipelineCreateInfoKHR::pname:pGroups |
| endif::VK_KHR_ray_tracing_pipeline[] |
| ifdef::VK_KHR_ray_tracing_pipeline+VK_NV_ray_tracing[or] |
| ifdef::VK_NV_ray_tracing[] |
| slink:VkRayTracingPipelineCreateInfoNV::pname:pGroups |
| endif::VK_NV_ray_tracing[] |
| array. |
| * pname:groupCount is the number of shader handles to retrieve. |
| * pname:dataSize is the size in bytes of the buffer pointed to by |
| pname:pData. |
| * pname:pData is a pointer to a user-allocated buffer where the results |
| will be written. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkGetRayTracingShaderGroupHandlesKHR-pipeline-04619]] |
| pname:pipeline must: be a ray tracing pipeline |
| * [[VUID-vkGetRayTracingShaderGroupHandlesKHR-firstGroup-04050]] |
| pname:firstGroup must: be less than the number of shader groups in |
| pname:pipeline |
| * [[VUID-vkGetRayTracingShaderGroupHandlesKHR-firstGroup-02419]] |
| The sum of pname:firstGroup and pname:groupCount must: be less than or |
| equal to the number of shader groups in pname:pipeline |
| * [[VUID-vkGetRayTracingShaderGroupHandlesKHR-dataSize-02420]] |
| pname:dataSize must: be at least |
| [eq]#slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR::pname:shaderGroupHandleSize |
| {times} pname:groupCount# |
| ifdef::VK_KHR_pipeline_library[] |
| * [[VUID-vkGetRayTracingShaderGroupHandlesKHR-pipeline-03482]] |
| pname:pipeline must: have not been created with |
| ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR |
| endif::VK_KHR_pipeline_library[] |
| **** |
| |
| include::{generated}/validity/protos/vkGetRayTracingShaderGroupHandlesKHR.txt[] |
| -- |
| |
| ifdef::VK_KHR_ray_tracing_pipeline[] |
| [open,refpage='vkGetRayTracingCaptureReplayShaderGroupHandlesKHR',desc='Query ray tracing capture replay pipeline shader group handles',type='protos'] |
| -- |
| :refpage: vkGetRayTracingCaptureReplayShaderGroupHandlesKHR |
| |
| To query the optional capture handle information of shaders in the ray |
| tracing pipeline, call: |
| |
| include::{generated}/api/protos/vkGetRayTracingCaptureReplayShaderGroupHandlesKHR.txt[] |
| |
| * pname:device is the logical device containing the ray tracing pipeline. |
| * pname:pipeline is the ray tracing pipeline object containing the |
| shaders. |
| * pname:firstGroup is the index of the first group to retrieve a handle |
| for from the slink:VkRayTracingPipelineCreateInfoKHR::pname:pGroups |
| array. |
| * pname:groupCount is the number of shader handles to retrieve. |
| * pname:dataSize is the size in bytes of the buffer pointed to by |
| pname:pData. |
| * pname:pData is a pointer to a user-allocated buffer where the results |
| will be written. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pipeline-04620]] |
| pname:pipeline must: be a ray tracing pipeline |
| * [[VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-firstGroup-04051]] |
| pname:firstGroup must: be less than the number of shader groups in |
| pname:pipeline |
| * [[VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-firstGroup-03483]] |
| The sum of pname:firstGroup and pname:groupCount must: be less than or |
| equal to the number of shader groups in pname:pipeline |
| * [[VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-dataSize-03484]] |
| pname:dataSize must: be at least |
| [eq]#slink:VkPhysicalDeviceRayTracingPipelinePropertiesKHR::pname:shaderGroupHandleCaptureReplaySize |
| {times} pname:groupCount# |
| * [[VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-rayTracingPipelineShaderGroupHandleCaptureReplay-03606]] |
| sname:VkPhysicalDeviceRayTracingPipelineFeaturesKHR::pname:rayTracingPipelineShaderGroupHandleCaptureReplay |
| must: be enabled to call this function |
| * [[VUID-vkGetRayTracingCaptureReplayShaderGroupHandlesKHR-pipeline-03607]] |
| pname:pipeline must: have been created with a pname:flags that included |
| ename:VK_PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR |
| **** |
| |
| include::{generated}/validity/protos/vkGetRayTracingCaptureReplayShaderGroupHandlesKHR.txt[] |
| -- |
| endif::VK_KHR_ray_tracing_pipeline[] |
| |
| ifdef::VK_NV_ray_tracing[] |
| Ray tracing pipelines can: contain more shaders than a graphics or compute |
| pipeline, so to allow parallel compilation of shaders within a pipeline, an |
| application can: choose to defer compilation until a later point in time. |
| |
| [open,refpage='vkCompileDeferredNV',desc='Deferred compilation of shaders',type='protos'] |
| -- |
| :refpage: vkCompileDeferredNV |
| |
| To compile a deferred shader in a pipeline call: |
| |
| include::{generated}/api/protos/vkCompileDeferredNV.txt[] |
| |
| * pname:device is the logical device containing the ray tracing pipeline. |
| * pname:pipeline is the ray tracing pipeline object containing the |
| shaders. |
| * pname:shader is the index of the shader to compile. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCompileDeferredNV-pipeline-04621]] |
| pname:pipeline must: be a ray tracing pipeline |
| * [[VUID-vkCompileDeferredNV-pipeline-02237]] |
| pname:pipeline must: have been created with |
| ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV |
| * [[VUID-vkCompileDeferredNV-shader-02238]] |
| pname:shader must: not have been called as a deferred compile before |
| **** |
| |
| include::{generated}/validity/protos/vkCompileDeferredNV.txt[] |
| -- |
| endif::VK_NV_ray_tracing[] |
| |
| ifdef::VK_KHR_ray_tracing_pipeline[] |
| [open,refpage='vkGetRayTracingShaderGroupStackSizeKHR',desc='Query ray tracing pipeline shader group shader stack size',type='protos'] |
| -- |
| To query the pipeline stack size of shaders in a shader group in the ray |
| tracing pipeline, call: |
| |
| include::{generated}/api/protos/vkGetRayTracingShaderGroupStackSizeKHR.txt[] |
| |
| * pname:device is the logical device containing the ray tracing pipeline. |
| * pname:pipeline is the ray tracing pipeline object containing the shaders |
| groups. |
| * pname:group is the index of the shader group to query. |
| * pname:groupShader is the type of shader from the group to query. |
| |
| The return value is the ray tracing pipeline stack size in bytes for the |
| specified shader as called from the specified shader group. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkGetRayTracingShaderGroupStackSizeKHR-pipeline-04622]] |
| pname:pipeline must: be a ray tracing pipeline |
| * [[VUID-vkGetRayTracingShaderGroupStackSizeKHR-group-03608]] |
| The value of pname:group must be less than the number of shader groups |
| in pname:pipeline |
| * [[VUID-vkGetRayTracingShaderGroupStackSizeKHR-groupShader-03609]] |
| The shader identified by pname:groupShader in pname:group must: not be |
| ename:VK_SHADER_UNUSED_KHR |
| **** |
| |
| include::{generated}/validity/protos/vkGetRayTracingShaderGroupStackSizeKHR.txt[] |
| -- |
| |
| [open,refpage='VkShaderGroupShaderKHR',desc='Shader group shaders',type='enums'] |
| -- |
| Possible values of pname:groupShader in |
| flink:vkGetRayTracingShaderGroupStackSizeKHR are: |
| |
| include::{generated}/api/enums/VkShaderGroupShaderKHR.txt[] |
| |
| * ename:VK_SHADER_GROUP_SHADER_GENERAL_KHR uses the shader specified in |
| the group with |
| slink:VkRayTracingShaderGroupCreateInfoKHR::pname:generalShader |
| * ename:VK_SHADER_GROUP_SHADER_CLOSEST_HIT_KHR uses the shader specified |
| in the group with |
| slink:VkRayTracingShaderGroupCreateInfoKHR::pname:closestHitShader |
| * ename:VK_SHADER_GROUP_SHADER_ANY_HIT_KHR uses the shader specified in |
| the group with |
| slink:VkRayTracingShaderGroupCreateInfoKHR::pname:anyHitShader |
| * ename:VK_SHADER_GROUP_SHADER_INTERSECTION_KHR uses the shader specified |
| in the group with |
| slink:VkRayTracingShaderGroupCreateInfoKHR::pname:intersectionShader |
| -- |
| |
| |
| [open,refpage='vkCmdSetRayTracingPipelineStackSizeKHR',desc='Set the stack size dynamically for a ray tracing pipeline',type='protos'] |
| -- |
| :refpage: vkCmdSetRayTracingPipelineStackSizeKHR |
| |
| To <<pipelines-dynamic-state, dynamically set>> the stack size for a ray |
| tracing pipeline, call: |
| |
| include::{generated}/api/protos/vkCmdSetRayTracingPipelineStackSizeKHR.txt[] |
| |
| * pname:commandBuffer is the command buffer into which the command will be |
| recorded. |
| * pname:pipelineStackSize is the stack size to use for subsequent ray |
| tracing trace commands. |
| |
| This command sets the stack size for subsequent ray tracing commands when |
| the ray tracing pipeline is created with |
| ename:VK_DYNAMIC_STATE_RAY_TRACING_PIPELINE_STACK_SIZE_KHR set in |
| slink:VkPipelineDynamicStateCreateInfo::pname:pDynamicStates. |
| Otherwise, the stack size is computed as described in |
| <<ray-tracing-pipeline-stack, Ray Tracing Pipeline Stack>>. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCmdSetRayTracingPipelineStackSizeKHR-pipelineStackSize-03610]] |
| pname:pipelineStackSize must: be large enough for any dynamic execution |
| through the shaders in the ray tracing pipeline used by a subsequent |
| trace call |
| **** |
| include::{generated}/validity/protos/vkCmdSetRayTracingPipelineStackSizeKHR.txt[] |
| -- |
| endif::VK_KHR_ray_tracing_pipeline[] |
| endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] |
| |
| |
| [[pipelines-destruction]] |
| == Pipeline Destruction |
| |
| [open,refpage='vkDestroyPipeline',desc='Destroy a pipeline object',type='protos'] |
| -- |
| To destroy a pipeline, call: |
| |
| include::{generated}/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::{generated}/validity/protos/vkDestroyPipeline.txt[] |
| -- |
| |
| |
| [[pipelines-multiple]] |
| == Multiple Pipeline Creation |
| |
| Multiple pipelines can: be created simultaneously by passing an array of |
| slink:VkGraphicsPipelineCreateInfo, |
| ifdef::VK_KHR_ray_tracing_pipeline[slink:VkRayTracingPipelineCreateInfoKHR,] |
| ifdef::VK_NV_ray_tracing[slink:VkRayTracingPipelineCreateInfoNV,] |
| or slink:VkComputePipelineCreateInfo structures into the |
| flink:vkCreateGraphicsPipelines, |
| ifdef::VK_KHR_ray_tracing_pipeline[flink:vkCreateRayTracingPipelinesKHR,] |
| ifdef::VK_NV_ray_tracing[flink:vkCreateRayTracingPipelinesNV,] |
| 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 despite valid arguments (for example, due to |
| out of memory errors), the elink:VkResult code returned by |
| ftext:vkCreate*Pipelines will indicate why. |
| The implementation will attempt to create all pipelines, and only return |
| dlink:VK_NULL_HANDLE values for those that actually failed. |
| |
| ifdef::VK_EXT_pipeline_creation_cache_control[] |
| If creation fails for a pipeline that had |
| ename:VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT set, pipelines at |
| an index in the pname:pPipelines array greater than or equal to that of the |
| failing pipeline must: be set to dlink:VK_NULL_HANDLE. |
| endif::VK_EXT_pipeline_creation_cache_control[] |
| |
| [[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 specifies 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::{generated}/api/handles/VkPipelineCache.txt[] |
| -- |
| |
| [[pipelines-cache-create]] |
| === Creating a Pipeline Cache |
| |
| [open,refpage='vkCreatePipelineCache',desc='Creates a new pipeline cache',type='protos'] |
| -- |
| To create pipeline cache objects, call: |
| |
| include::{generated}/api/protos/vkCreatePipelineCache.txt[] |
| |
| * pname:device is the logical device that creates the pipeline cache |
| object. |
| * pname:pCreateInfo is a pointer to a slink:VkPipelineCacheCreateInfo |
| structure containing 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 slink: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 |
| flink:vkCreateGraphicsPipelines |
| ifdef::VK_KHR_ray_tracing_pipeline[flink:vkCreateRayTracingPipelinesKHR,] |
| ifdef::VK_NV_ray_tracing[flink:vkCreateRayTracingPipelinesNV,] |
| and flink: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. |
| |
| ifdef::VK_EXT_pipeline_creation_cache_control[] |
| If pname:flags of pname:pCreateInfo includes |
| ename:VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT, all commands |
| that modify the returned pipeline cache object must: be |
| <<fundamentals-threadingbehavior,externally synchronized>>. |
| endif::VK_EXT_pipeline_creation_cache_control[] |
| |
| [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 ftext:vkCreate*Pipelines commands. |
| ==== |
| |
| include::{generated}/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::{generated}/api/structs/VkPipelineCacheCreateInfo.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| ifdef::VK_EXT_pipeline_creation_cache_control[] |
| * pname:flags is a bitmask of elink:VkPipelineCacheCreateFlagBits |
| specifying the behavior of the pipeline cache. |
| endif::VK_EXT_pipeline_creation_cache_control[] |
| ifndef::VK_EXT_pipeline_creation_cache_control[] |
| * pname:flags is reserved for future use. |
| endif::VK_EXT_pipeline_creation_cache_control[] |
| * 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 |
| ifdef::VK_EXT_pipeline_creation_cache_control[] |
| * [[VUID-VkPipelineCacheCreateInfo-pipelineCreationCacheControl-02892]] |
| If the <<features-pipelineCreationCacheControl, |
| pname:pipelineCreationCacheControl>> feature is not enabled, pname:flags |
| must: not include |
| ename:VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT |
| endif::VK_EXT_pipeline_creation_cache_control[] |
| **** |
| |
| include::{generated}/validity/structs/VkPipelineCacheCreateInfo.txt[] |
| -- |
| |
| [open,refpage='VkPipelineCacheCreateFlags', desc='Bitmask of VkPipelineCreateFlagBits', type='flags'] |
| -- |
| include::{generated}/api/flags/VkPipelineCacheCreateFlags.txt[] |
| |
| ifdef::VK_EXT_pipeline_creation_cache_control[] |
| tname:VkPipelineCacheCreateFlags is a bitmask type for setting a mask of |
| zero or more elink:VkPipelineCacheCreateFlagBits. |
| endif::VK_EXT_pipeline_creation_cache_control[] |
| ifndef::VK_EXT_pipeline_creation_cache_control[] |
| tname:VkPipelineCacheCreateFlags is a bitmask type for setting a mask, but |
| is currently reserved for future use. |
| endif::VK_EXT_pipeline_creation_cache_control[] |
| -- |
| |
| ifdef::VK_EXT_pipeline_creation_cache_control[] |
| [open,refpage='VkPipelineCacheCreateFlagBits',desc='Bitmask specifying the behavior of the pipeline cache',type='enums'] |
| -- |
| Possible values of the pname:flags member of |
| slink:VkPipelineCacheCreateInfo, specifying the behavior of the pipeline |
| cache, are: |
| |
| include::{generated}/api/enums/VkPipelineCacheCreateFlagBits.txt[] |
| |
| * ename:VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT specifies |
| that all commands that modify the created slink:VkPipelineCache will be |
| <<fundamentals-threadingbehavior,externally synchronized>>. |
| When set, the implementation may: skip any unnecessary processing needed |
| to support simultaneous modification from multiple threads where |
| allowed. |
| -- |
| endif::VK_EXT_pipeline_creation_cache_control[] |
| |
| |
| [[pipelines-cache-merge]] |
| === Merging Pipeline Caches |
| |
| [open,refpage='vkMergePipelineCaches',desc='Combine the data stores of pipeline caches',type='protos'] |
| -- |
| Pipeline cache objects can: be merged using the command: |
| |
| include::{generated}/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 a pointer to 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::{generated}/validity/protos/vkMergePipelineCaches.txt[] |
| -- |
| |
| [[pipelines-cache-retrieval]] |
| === Retrieving Pipeline Cache Data |
| |
| [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::{generated}/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 code:size_t 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 ename:VK_INCOMPLETE will be returned instead of |
| ename:VK_SUCCESS, to indicate that not all of the pipeline cache was |
| returned. |
| |
| Any data written to pname:pData is valid and can: be provided as the |
| pname:pInitialData member of the slink: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. |
| |
| The initial bytes written to pname:pData must: be a header as described in |
| the <<pipelines-cache-header, Pipeline Cache Header>> section. |
| |
| 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::{generated}/validity/protos/vkGetPipelineCacheData.txt[] |
| -- |
| |
| [[pipelines-cache-header]] |
| === Pipeline 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 pipeline cache data must: begin with a |
| valid pipeline cache header. |
| |
| [open,refpage='VkPipelineCacheHeaderVersionOne',desc='Structure describing the layout of the pipeline cache header',type='structs'] |
| -- |
| Version one of the pipeline cache header is defined as: |
| |
| include::{generated}/api/structs/VkPipelineCacheHeaderVersionOne.txt[] |
| |
| * pname:headerSize is the length in bytes of the pipeline cache header. |
| * pname:headerVersion is a elink:VkPipelineCacheHeaderVersion enum value |
| specifying the version of the header. |
| A consumer of the pipeline cache should: use the cache version to |
| interpret the remainder of the cache header. |
| * pname:vendorID is the sname:VkPhysicalDeviceProperties::pname:vendorID |
| of the implementation. |
| * pname:deviceID is the sname:VkPhysicalDeviceProperties::pname:deviceID |
| of the implementation. |
| * pname:pipelineCacheUUID is the |
| sname:VkPhysicalDeviceProperties::pname:pipelineCacheUUID of the |
| implementation. |
| |
| Unlike most structures declared by the Vulkan API, all fields of this |
| structure are written with the least significant byte first, regardless of |
| host byte-order. |
| |
| The C language specification does not define the packing of structure |
| members. |
| This layout assumes tight structure member packing, with members laid out in |
| the order listed in the structure, and the intended size of the structure is |
| 32 bytes. |
| If a compiler produces code that diverges from that pattern, applications |
| must: employ another method to set values at the correct offsets. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkPipelineCacheHeaderVersionOne-headerSize-04967]] |
| pname:headerSize must: be 32 |
| * [[VUID-VkPipelineCacheHeaderVersionOne-headerVersion-04968]] |
| pname:headerVersion must: be ename:VK_PIPELINE_CACHE_HEADER_VERSION_ONE |
| **** |
| |
| include::{generated}/validity/structs/VkPipelineCacheHeaderVersionOne.txt[] |
| -- |
| |
| |
| [open,refpage='VkPipelineCacheHeaderVersion',desc='Encode pipeline cache version',type='enums',xrefs='vkCreatePipelineCache vkGetPipelineCacheData'] |
| -- |
| Possible values of the pname:headerVersion value of the pipeline cache |
| header are: |
| |
| include::{generated}/api/enums/VkPipelineCacheHeaderVersion.txt[] |
| |
| * ename:VK_PIPELINE_CACHE_HEADER_VERSION_ONE specifies version one of the |
| pipeline cache. |
| -- |
| |
| [[pipelines-cache-destroy]] |
| === Destroying a Pipeline Cache |
| |
| [open,refpage='vkDestroyPipelineCache',desc='Destroy a pipeline cache object',type='protos'] |
| -- |
| To destroy a pipeline cache, call: |
| |
| include::{generated}/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::{generated}/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 slink:VkPipelineShaderStageCreateInfo structure contains a |
| pname:pSpecializationInfo member, which can: be `NULL` to indicate no |
| specialization constants, or point to a sname:VkSpecializationInfo |
| structure. |
| |
| [open,refpage='VkSpecializationInfo',desc='Structure specifying specialization information',type='structs'] |
| -- |
| The sname:VkSpecializationInfo structure is defined as: |
| |
| include::{generated}/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 structures which map 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. |
| |
| .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-constantID-04911]] |
| The pname:constantID value of each element of pname:pMapEntries must: be |
| unique within pname:pMapEntries |
| **** |
| |
| include::{generated}/validity/structs/VkSpecializationInfo.txt[] |
| -- |
| |
| [open,refpage='VkSpecializationMapEntry',desc='Structure specifying a specialization map entry',type='structs'] |
| -- |
| The sname:VkSpecializationMapEntry structure is defined as: |
| |
| include::{generated}/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::{generated}/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 value. |
| |
| 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 information 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. |
| |
| |
| ifdef::VK_KHR_pipeline_library[] |
| [[pipeline-library]] |
| == Pipeline Libraries |
| |
| A pipeline library is a special pipeline that was created using the |
| ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR and cannot be bound, instead it |
| defines a set of pipeline state which can be linked into other pipelines. |
| ifdef::VK_KHR_ray_tracing_pipeline[] |
| For ray tracing pipelines this includes shaders and shader groups. |
| endif::VK_KHR_ray_tracing_pipeline[] |
| The application must: maintain the lifetime of a pipeline library based on |
| the pipelines that link with it. |
| A pipeline library is considered in-use, as long as one of the linking |
| pipelines is in-use. |
| |
| This linkage is achieved by using the following structure within the |
| appropriate creation mechanisms: |
| |
| [open,refpage='VkPipelineLibraryCreateInfoKHR',desc='Structure specifying pipeline libraries to use when creating a pipeline',type='structs'] |
| -- |
| The sname:VkPipelineLibraryCreateInfoKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkPipelineLibraryCreateInfoKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:libraryCount is the number of pipeline libraries in |
| pname:pLibraries. |
| * pname:pLibraries is a pointer to an array of slink:VkPipeline structures |
| specifying pipeline libraries to use when creating a pipeline. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkPipelineLibraryCreateInfoKHR-pLibraries-03381]] |
| Each element of pname:pLibraries must: have been created with |
| ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR |
| **** |
| |
| include::{generated}/validity/structs/VkPipelineLibraryCreateInfoKHR.txt[] |
| -- |
| endif::VK_KHR_pipeline_library[] |
| |
| |
| [[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::{generated}/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 |
| to which bind point the pipeline is bound. |
| Binding one does not disturb the others. |
| * pname:pipeline is the pipeline to be bound. |
| |
| [[pipeline-bindpoint-commands]] |
| Once bound, a pipeline binding affects subsequent commands that interact |
| with the given pipeline type in the command buffer until a different |
| pipeline of the same type is bound to the bind point. |
| Commands that do not interact with the given pipeline type must: not be |
| affected by the pipeline state. |
| |
| * The pipeline bound to ename:VK_PIPELINE_BIND_POINT_COMPUTE controls the |
| behavior of all <<dispatch, dispatching commands>>. |
| * The pipeline bound to ename:VK_PIPELINE_BIND_POINT_GRAPHICS controls the |
| behavior of all <<drawing, drawing commands>>. |
| ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] |
| * The pipeline bound to ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR |
| controls the behavior of flink:vkCmdTraceRaysKHR and |
| flink:vkCmdTraceRaysIndirectKHR. |
| endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] |
| ifdef::VK_HUAWEI_subpass_shading[] |
| * The pipeline bound to |
| ename:VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI controls the |
| behavior of flink:vkCmdSubpassShadingHUAWEI. |
| endif::VK_HUAWEI_subpass_shading[] |
| |
| .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-variableMultisampleRate,variable multisample rate>> |
| feature is not supported, pname:pipeline is a graphics pipeline, the |
| current subpass <<renderpass-noattachments, uses 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[] |
| ifdef::VK_EXT_transform_feedback[] |
| * [[VUID-vkCmdBindPipeline-None-02323]] |
| This command must: not be recorded when transform feedback is active |
| endif::VK_EXT_transform_feedback[] |
| ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] |
| * [[VUID-vkCmdBindPipeline-pipelineBindPoint-02391]] |
| If pname:pipelineBindPoint is |
| ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR, the sname:VkCommandPool |
| that pname:commandBuffer was allocated from must: support compute |
| operations |
| * [[VUID-vkCmdBindPipeline-pipelineBindPoint-02392]] |
| If pname:pipelineBindPoint is |
| ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR, pname:pipeline must: be a |
| ray tracing pipeline |
| endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] |
| ifdef::VK_KHR_pipeline_library[] |
| * [[VUID-vkCmdBindPipeline-pipeline-03382]] |
| pname:pipeline must: not have been created with |
| ename:VK_PIPELINE_CREATE_LIBRARY_BIT_KHR set |
| endif::VK_KHR_pipeline_library[] |
| ifdef::VK_NV_inherited_viewport_scissor[] |
| * [[VUID-vkCmdBindPipeline-commandBuffer-04808]] |
| If pname:commandBuffer is a secondary command buffer with |
| slink:VkCommandBufferInheritanceViewportScissorInfoNV::pname:viewportScissor2D |
| enabled and pname:pipelineBindPoint is |
| ename:VK_PIPELINE_BIND_POINT_GRAPHICS, then the pname:pipeline must: |
| have been created with ename:VK_DYNAMIC_STATE_VIEWPORT_WITH_COUNT_EXT or |
| ename:VK_DYNAMIC_STATE_VIEWPORT, and |
| ename:VK_DYNAMIC_STATE_SCISSOR_WITH_COUNT_EXT or |
| ename:VK_DYNAMIC_STATE_SCISSOR enabled |
| endif::VK_NV_inherited_viewport_scissor[] |
| ifdef::VK_NV_inherited_viewport_scissor,VK_EXT_discard_rectangles[] |
| * [[VUID-vkCmdBindPipeline-commandBuffer-04809]] |
| If pname:commandBuffer is a secondary command buffer with |
| slink:VkCommandBufferInheritanceViewportScissorInfoNV::pname:viewportScissor2D |
| enabled and pname:pipelineBindPoint is |
| ename:VK_PIPELINE_BIND_POINT_GRAPHICS and pname:pipeline was created |
| with slink:VkPipelineDiscardRectangleStateCreateInfoEXT structure and |
| its pname:discardRectangleCount member is not `0`, then the pipeline |
| must: have been created with |
| ename:VK_DYNAMIC_STATE_DISCARD_RECTANGLE_EXT enabled |
| endif::VK_NV_inherited_viewport_scissor,VK_EXT_discard_rectangles[] |
| ifdef::VK_EXT_provoking_vertex[] |
| * [[VUID-vkCmdBindPipeline-pipelineBindPoint-04881]] |
| If pname:pipelineBindPoint is ename:VK_PIPELINE_BIND_POINT_GRAPHICS and |
| the |
| <<limits-provokingVertexModePerPipeline,provokingVertexModePerPipeline>> |
| limit is ename:VK_FALSE, then pipeline's |
| slink:VkPipelineRasterizationProvokingVertexStateCreateInfoEXT::pname:provokingVertexMode |
| must: be the same as that of any other pipelines previously bound to |
| this bind point within the current render pass instance, including any |
| pipeline already bound when beginning the render pass instance |
| endif::VK_EXT_provoking_vertex[] |
| ifdef::VK_HUAWEI_subpass_shading[] |
| * [[VUID-vkCmdBindPipeline-pipelineBindPoint-04949]] |
| If pname:pipelineBindPoint is |
| ename:VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI, the |
| sname:VkCommandPool that pname:commandBuffer was allocated from must: |
| support compute operations |
| * [[VUID-vkCmdBindPipeline-pipelineBindPoint-04950]] |
| If pname:pipelineBindPoint is |
| ename:VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI, pname:pipeline |
| must: be a subpass shading pipeline |
| endif::VK_HUAWEI_subpass_shading[] |
| ifdef::VK_KHR_dynamic_rendering[] |
| * [[VUID-vkCmdBindPipeline-pipeline-06195]] |
| If pname:pipeline is a graphics pipeline, this command has been called |
| inside a render pass instance started with flink:vkCmdBeginRenderingKHR, |
| and commands using the previously bound graphics pipeline have been |
| recorded within the render pass instance, then the value of |
| slink:VkPipelineRenderingCreateInfoKHR::pname:colorAttachmentCount |
| specified by this pipeline must: match that set in the previous pipeline |
| * [[VUID-vkCmdBindPipeline-pipeline-06196]] |
| If pname:pipeline is a graphics pipeline, this command has been called |
| inside a render pass instance started with flink:vkCmdBeginRenderingKHR, |
| and commands using the previously bound graphics pipeline have been |
| recorded within the render pass instance, then the elements of |
| slink:VkPipelineRenderingCreateInfoKHR::pname:pColorAttachmentFormats |
| specified by this pipeline must: match that set in the previous pipeline |
| * [[VUID-vkCmdBindPipeline-pipeline-06197]] |
| If pname:pipeline is a graphics pipeline, this command has been called |
| inside a render pass instance started with flink:vkCmdBeginRenderingKHR, |
| and commands using the previously bound graphics pipeline have been |
| recorded within the render pass instance, then the value of |
| slink:VkPipelineRenderingCreateInfoKHR::pname:depthAttachmentFormat |
| specified by this pipeline must: match that set in the previous pipeline |
| * [[VUID-vkCmdBindPipeline-pipeline-06194]] |
| If pname:pipeline is a graphics pipeline, this command has been called |
| inside a render pass instance started with flink:vkCmdBeginRenderingKHR, |
| and commands using the previously bound graphics pipeline have been |
| recorded within the render pass instance, then the value of |
| slink:VkPipelineRenderingCreateInfoKHR::pname:stencilAttachmentFormat |
| specified by this pipeline must: match that set in the previous pipeline |
| endif::VK_KHR_dynamic_rendering[] |
| **** |
| |
| include::{generated}/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::{generated}/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_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] |
| * ename:VK_PIPELINE_BIND_POINT_RAY_TRACING_KHR specifies binding as a ray |
| tracing pipeline. |
| endif::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[] |
| ifdef::VK_HUAWEI_subpass_shading[] |
| * ename:VK_PIPELINE_BIND_POINT_SUBPASS_SHADING_HUAWEI specifies binding as |
| a subpass shading pipeline. |
| endif::VK_HUAWEI_subpass_shading[] |
| -- |
| |
| ifdef::VK_NV_device_generated_commands[] |
| [open,refpage='vkCmdBindPipelineShaderGroupNV',desc='Bind a pipeline object's shader group to a command buffer',type='protos'] |
| -- |
| For pipelines that were created with the support of multiple shader groups |
| (see <<graphics-shadergroups,Graphics Pipeline Shader Groups>>), the regular |
| fname:vkCmdBindPipeline command will bind Shader Group `0`. |
| To explicitly bind a shader group use: |
| |
| include::{generated}/api/protos/vkCmdBindPipelineShaderGroupNV.txt[] |
| |
| * pname:commandBuffer is the command buffer that the pipeline will be |
| bound to. |
| * pname:pipelineBindPoint is a elink:VkPipelineBindPoint value specifying |
| the bind point to which the pipeline will be bound. |
| * pname:pipeline is the pipeline to be bound. |
| * pname:groupIndex is the shader group to be bound. |
| |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkCmdBindPipelineShaderGroupNV-groupIndex-02893]] |
| pname:groupIndex must: be `0` or less than the effective |
| slink:VkGraphicsPipelineShaderGroupsCreateInfoNV::pname:groupCount |
| including the referenced pipelines |
| * [[VUID-vkCmdBindPipelineShaderGroupNV-pipelineBindPoint-02894]] |
| The pname:pipelineBindPoint must: be |
| ename:VK_PIPELINE_BIND_POINT_GRAPHICS |
| * [[VUID-vkCmdBindPipelineShaderGroupNV-groupIndex-02895]] |
| The same restrictions as flink:vkCmdBindPipeline apply as if the bound |
| pipeline was created only with the Shader Group from the |
| pname:groupIndex information |
| * [[VUID-vkCmdBindPipelineShaderGroupNV-deviceGeneratedCommands-02896]] |
| The <<features-deviceGeneratedCommands, |
| sname:VkPhysicalDeviceDeviceGeneratedCommandsFeaturesNV::pname:deviceGeneratedCommands>> |
| feature must: be enabled |
| **** |
| |
| include::{generated}/validity/protos/vkCmdBindPipelineShaderGroupNV.txt[] |
| -- |
| endif::VK_NV_device_generated_commands[] |
| |
| |
| [[pipelines-dynamic-state]] |
| == Dynamic State |
| |
| When a pipeline object is bound, any pipeline object state that is not |
| specified as dynamic is applied to the command buffer state. |
| Pipeline object state that is specified as dynamic is not applied to the |
| command buffer state at this time. |
| Instead, dynamic state can: be modified at any time and persists for the |
| lifetime of the command buffer, or until modified by another dynamic state |
| setting command or another pipeline bind. |
| |
| When a pipeline object is bound, the following applies to each state |
| parameter: |
| |
| * If the state is not specified as dynamic in the new pipeline object, |
| then that command buffer state is overwritten by the state in the new |
| pipeline object. |
| Before any draw or dispatch call with this pipeline there must: not have |
| been any calls to any of the corresponding dynamic state setting |
| commands after this pipeline was bound |
| * If the state is specified as dynamic in the new pipeline object, then |
| that command buffer state is not disturbed. |
| Before any draw or dispatch call with this pipeline there must: have |
| been at least one call to each of the corresponding dynamic state |
| setting commands since the command buffer recording was begun, or the |
| last bound pipeline object with that state specified as static, |
| whichever was the latter |
| |
| Dynamic state that does not affect the result of operations can: be left |
| undefined:. |
| |
| [NOTE] |
| .Note |
| ==== |
| For example, if blending is disabled by the pipeline object state then the |
| dynamic color blend constants do not need to be specified in the command |
| buffer, even if this state is specified as dynamic in the pipeline object. |
| ==== |
| |
| ifdef::VK_AMD_shader_info,VK_KHR_pipeline_executable_properties[] |
| [[pipelines-shader-information]] |
| == Pipeline Shader Information |
| endif::VK_AMD_shader_info,VK_KHR_pipeline_executable_properties[] |
| |
| ifdef::VK_KHR_pipeline_executable_properties[] |
| include::VK_KHR_pipeline_executable_properties/pipelines.txt[] |
| endif::VK_KHR_pipeline_executable_properties[] |
| |
| ifdef::VK_AMD_shader_info[] |
| include::VK_AMD_shader_info.txt[] |
| endif::VK_AMD_shader_info[] |
| |
| // These includes have their own section headers |
| |
| ifdef::VK_AMD_pipeline_compiler_control[] |
| include::VK_AMD_pipeline_compiler_control.txt[] |
| endif::VK_AMD_pipeline_compiler_control[] |
| |
| ifdef::VK_EXT_pipeline_creation_feedback[] |
| include::VK_EXT_pipeline_creation_feedback/pipelines.txt[] |
| endif::VK_EXT_pipeline_creation_feedback[] |
