vkCreateComputePipelines - Creates a new compute pipeline object

Description

Pipelines are created and returned as described for Multiple Pipeline Creation.

Valid Usage

• device must support at least one queue family with the QUEUE_COMPUTE_BIT capability

• If the flags member of any element of pCreateInfos contains the PIPELINE_CREATE_DERIVATIVE_BIT flag, and the basePipelineIndex member of that same element is not -1, basePipelineIndex must be less than the index into pCreateInfos that corresponds to that element
• If the flags member of any element of pCreateInfos contains the PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline must have been created with the PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set
• If pipelineCache was created with PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT, host access to pipelineCache must be externally synchronized
• If PipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, pipelineCache must be NULL_HANDLE
• If a PipelineCreateFlags2CreateInfoKHR structure with the PIPELINE_CREATE_2_CAPTURE_DATA_BIT_KHR flag set is included in the pNext chain of any element of pCreateInfos, pipelineCache must be NULL_HANDLE
• If PipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT must not be set in the flags of that element
• If PipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT must not be set in the flags of that element
• If PipelineBinaryInfoKHR::binaryCount is not 0 for any element of pCreateInfos, PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT must not be set in the flags of that element
• If any element of pCreateInfos sets PIPELINE_CREATE_2_DESCRIPTOR_HEAP_BIT_EXT and includes embedded sampler mappings, there must be less than (maxSamplerAllocationCount
• (minSamplerHeapReservedRangeWithEmbedded / samplerDescriptorSize)) Sampler objects currently created on the device
• If any element of pCreateInfos sets PIPELINE_CREATE_2_DESCRIPTOR_HEAP_BIT_EXT and includes embedded sampler mappings, this command must not cause the total number of unique embedded samplers in pipelines and shaders on this device to exceed maxDescriptorHeapEmbeddedSamplers

Valid Usage (Implicit)

• device must be a valid Device handle

• If pipelineCache is not NULL_HANDLE, pipelineCache must be a valid PipelineCache handle
• pCreateInfos must be a valid pointer to an array of createInfoCount valid ComputePipelineCreateInfo structures
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• pPipelines must be a valid pointer to an array of createInfoCount Pipeline handles
• createInfoCount must be greater than 0
• If pipelineCache is a valid handle, it must have been created, allocated, or retrieved from device

Return Codes

Success

• PIPELINE_COMPILE_REQUIRED_EXT
• SUCCESS

Failure

• ERROR_INVALID_SHADER_NV
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_OUT_OF_HOST_MEMORY
• ERROR_UNKNOWN
• ERROR_VALIDATION_FAILED

See Also

VK_VERSION_1_0, AllocationCallbacks, ComputePipelineCreateInfo, Device, Pipeline, PipelineCache

A convenience wrapper to make a compatible pair of calls to createComputePipelines and destroyPipeline

To ensure that destroyPipeline is always called: pass bracket (or the allocate function from your favourite resource management library) as the last argument. To just extract the pair pass (,) as the last argument.

vkDestroyPipeline - Destroy a pipeline object

Valid Usage

• All submitted commands that refer to pipeline must have completed execution

• If AllocationCallbacks were provided when pipeline was created, a compatible set of callbacks must be provided here
• If no AllocationCallbacks were provided when pipeline was created, pAllocator must be NULL

Valid Usage (Implicit)

• device must be a valid Device handle

• If pipeline is not NULL_HANDLE, pipeline must be a valid Pipeline handle
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure
• If pipeline is a valid handle, it must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to pipeline must be externally synchronized

See Also

VK_VERSION_1_0, AllocationCallbacks, Device, Pipeline

VkSpecializationMapEntry - Structure specifying a specialization map entry

Description

If a 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

• For a constantID specialization constant declared in a shader, size must match the byte size of the constantID. If the specialization constant is of type boolean, size must be the byte size of Bool32

See Also

VK_VERSION_1_0, SpecializationInfo

VkSpecializationInfo - Structure specifying specialization information

Valid Usage

• The offset member of each element of pMapEntries must be less than dataSize

• The size member of each element of pMapEntries must be less than or equal to dataSize minus offset
• The constantID value of each element of pMapEntries must be unique within pMapEntries

Valid Usage (Implicit)

• If mapEntryCount is not 0, pMapEntries must be a valid pointer to an array of mapEntryCount valid SpecializationMapEntry structures

• If dataSize is not 0, pData must be a valid pointer to an array of dataSize bytes

See Also

VK_VERSION_1_0, DataGraphPipelineShaderModuleCreateInfoARM, PipelineShaderStageCreateInfo, ShaderCreateInfoEXT, SpecializationMapEntry

VkPipelineShaderStageCreateInfo - Structure specifying parameters of a newly created pipeline shader stage

Description

If module is not NULL_HANDLE, the shader code used by the pipeline is defined by module. If module is NULL_HANDLE, the shader code is defined by the chained ShaderModuleCreateInfo if present.

If the shaderModuleIdentifier feature is enabled, applications can omit shader code for stage and instead provide a module identifier. This is done by including a PipelineShaderStageModuleIdentifierCreateInfoEXT structure with identifierSize not equal to 0 in the pNext chain. A shader stage created in this way is equivalent to one created using a shader module with the same identifier. The identifier allows an implementation to look up a pipeline without consuming a valid SPIR-V module. If a pipeline is not found, pipeline compilation is not possible and the implementation must fail as specified by PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT.

When an identifier is used in lieu of a shader module, implementations may fail pipeline compilation with PIPELINE_COMPILE_REQUIRED for any reason.

The rationale for the relaxed requirement on implementations to return a pipeline with PipelineShaderStageModuleIdentifierCreateInfoEXT is that layers or tools may intercept pipeline creation calls and require the full SPIR-V context to operate correctly. ICDs are not expected to fail pipeline compilation if the pipeline exists in a cache somewhere.

Applications can use identifiers when creating pipelines with PIPELINE_CREATE_LIBRARY_BIT_KHR. When creating such pipelines, SUCCESS may be returned, but subsequently fail when referencing the pipeline in a PipelineLibraryCreateInfoKHR struct. Applications must allow pipeline compilation to fail during link steps with PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT as it may not be possible to determine if a pipeline can be created from identifiers until the link step.

Valid Usage

• If the descriptorHeap feature is not enabled, ShaderDescriptorSetAndBindingMappingInfoEXT::mappingCount must be 0

• If the pNext chain specifies a descriptor mapping using DESCRIPTOR_MAPPING_SOURCE_PUSH_DATA_EXT, DESCRIPTOR_MAPPING_SOURCE_SHADER_RECORD_DATA_EXT, or DESCRIPTOR_MAPPING_SOURCE_RESOURCE_HEAP_DATA_EXT, the mapped resource in the shader must be a variable with a structure type decorated with Block in the Uniform Storage Class
• If the pNext chain specifies a descriptor mapping using DESCRIPTOR_MAPPING_SOURCE_PUSH_DATA_EXT, the mapped structure must not be larger than the sum of pushDataOffset used in the mapping and maxPushDataSize
• If the pNext chain specifies a descriptor mapping using DESCRIPTOR_MAPPING_SOURCE_SHADER_RECORD_DATA_EXT, the sum of mapped structure size and shaderRecordDataOffset used in the mapping must not be larger than maxShaderGroupStride

• If the pNext chain specifies a descriptor mapping using DESCRIPTOR_MAPPING_SOURCE_SHADER_RECORD_ADDRESS_EXT or DESCRIPTOR_MAPPING_SOURCE_PUSH_ADDRESS_EXT, the mapped resource in the shader must be one of:

  • A variable with a structure type decorated with Block in the Uniform Storage Class
  • A variable with a structure type decorated with BufferBlock in the Uniform Storage Class
  • A variable with a structure type decorated with Block in the StorageBuffer Storage Class
  • A OpTypeAccelerationStructureKHR variable
  • A OpTypeAccelerationStructureNV variable
• If the pNext chain specifies a descriptor mapping using DESCRIPTOR_MAPPING_SOURCE_PUSH_ADDRESS_EXT, DESCRIPTOR_MAPPING_SOURCE_SHADER_RECORD_ADDRESS_EXT, or DESCRIPTOR_MAPPING_SOURCE_INDIRECT_ADDRESS_EXT, the OpArrayLength or OpUntypedArrayLengthKHR instruction must not be used on that resource
• If the pNext chain specifies a descriptor mapping using DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_CONSTANT_OFFSET_EXT, DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_PUSH_INDEX_EXT, DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_SHADER_RECORD_INDEX_EXT, DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_EXT, or DESCRIPTOR_MAPPING_SOURCE_HEAP_WITH_INDIRECT_INDEX_ARRAY_EXT, and the mapped resource declaration is an array, the pEmbeddedSampler member of the corresponding mapping structure must be NULL
• If the geometryShader feature is not enabled, stage must not be SHADER_STAGE_GEOMETRY_BIT
• If the tessellationShader feature is not enabled, stage must not be SHADER_STAGE_TESSELLATION_CONTROL_BIT or SHADER_STAGE_TESSELLATION_EVALUATION_BIT
• If the meshShaders feature is not enabled, stage must not be SHADER_STAGE_MESH_BIT_EXT
• If the taskShaders feature is not enabled, stage must not be SHADER_STAGE_TASK_BIT_EXT
• If the clustercullingShader feature is not enabled, stage must not be SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI
• stage must not be SHADER_STAGE_ALL_GRAPHICS, or SHADER_STAGE_ALL
• pName must be the name of an OpEntryPoint in module with an execution model that matches stage
• If the identified entry point includes any variable in its interface that is declared with the ClipDistance BuiltIn decoration, that variable must not have an array size greater than PhysicalDeviceLimits::maxClipDistances
• If the identified entry point includes any variable in its interface that is declared with the CullDistance BuiltIn decoration, that variable must not have an array size greater than PhysicalDeviceLimits::maxCullDistances
• If the identified entry point includes variables in its interface that are declared with the ClipDistance BuiltIn decoration and variables in its interface that are declared with the CullDistance BuiltIn decoration, those variables must not have array sizes which sum to more than PhysicalDeviceLimits::maxCombinedClipAndCullDistances
• If the identified entry point includes any variable in its interface that is declared with the SampleMask BuiltIn decoration, that variable must not have an array size greater than PhysicalDeviceLimits::maxSampleMaskWords
• If stage is SHADER_STAGE_TESSELLATION_CONTROL_BIT or SHADER_STAGE_TESSELLATION_EVALUATION_BIT, and the identified entry point has an OpExecutionMode instruction specifying a patch size with OutputVertices, the patch size must be greater than 0 and less than or equal to PhysicalDeviceLimits::maxTessellationPatchSize
• If stage is SHADER_STAGE_GEOMETRY_BIT, the identified entry point must have an OpExecutionMode instruction specifying a maximum output vertex count that is greater than 0 and less than or equal to PhysicalDeviceLimits::maxGeometryOutputVertices
• If stage is SHADER_STAGE_GEOMETRY_BIT, the identified entry point must have an OpExecutionMode instruction specifying an invocation count that is greater than 0 and less than or equal to PhysicalDeviceLimits::maxGeometryShaderInvocations
• If stage is either SHADER_STAGE_VERTEX_BIT, SHADER_STAGE_TESSELLATION_CONTROL_BIT, SHADER_STAGE_TESSELLATION_EVALUATION_BIT, or SHADER_STAGE_GEOMETRY_BIT, and the identified entry point writes to Layer for any primitive, it must write the same value to Layer for all vertices of a given primitive
• If stage is either SHADER_STAGE_VERTEX_BIT, SHADER_STAGE_TESSELLATION_CONTROL_BIT, SHADER_STAGE_TESSELLATION_EVALUATION_BIT, or SHADER_STAGE_GEOMETRY_BIT, and the identified entry point writes to ViewportIndex for any primitive, it must write the same value to ViewportIndex for all vertices of a given primitive
• If stage is SHADER_STAGE_FRAGMENT_BIT, and the identified entry point writes to FragDepth in any execution path, all execution paths that are not exclusive to helper invocations must either discard the fragment, or write or initialize the value of FragDepth
• If stage is SHADER_STAGE_FRAGMENT_BIT, and the identified entry point writes to FragStencilRefEXT in any execution path, all execution paths that are not exclusive to helper invocations must either discard the fragment, or write or initialize the value of FragStencilRefEXT
• If flags has the PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT flag set, the subgroupSizeControl feature must be enabled
• If flags has the PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT flag set, the computeFullSubgroups feature must be enabled
• If flags includes PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT, stage must be one of SHADER_STAGE_MESH_BIT_EXT, SHADER_STAGE_TASK_BIT_EXT, or SHADER_STAGE_COMPUTE_BIT
• If a PipelineShaderStageRequiredSubgroupSizeCreateInfo structure is included in the pNext chain, flags must not have the PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT flag set
• If a PipelineShaderStageRequiredSubgroupSizeCreateInfo structure is included in the pNext chain, the subgroupSizeControl feature must be enabled, and stage must be a valid bit specified in requiredSubgroupSizeStages
• If a PipelineShaderStageRequiredSubgroupSizeCreateInfo structure is included in the pNext chain and stage is SHADER_STAGE_COMPUTE_BIT, SHADER_STAGE_MESH_BIT_EXT, or SHADER_STAGE_TASK_BIT_EXT, the local workgroup size of the shader must be less than or equal to the product of PipelineShaderStageRequiredSubgroupSizeCreateInfo::requiredSubgroupSize and maxComputeWorkgroupSubgroups
• If a PipelineShaderStageRequiredSubgroupSizeCreateInfo structure is included in the pNext chain, and flags has the PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT flag set, the local workgroup size in the X dimension of the pipeline must be a multiple of PipelineShaderStageRequiredSubgroupSizeCreateInfo::requiredSubgroupSize
• If flags has both the PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT and PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT flags set, the local workgroup size in the X dimension of the pipeline must be a multiple of maxSubgroupSize
• If flags has the PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT flag set and flags does not have the PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT flag set and no PipelineShaderStageRequiredSubgroupSizeCreateInfo structure is included in the pNext chain, the local workgroup size in the X dimension of the pipeline must be a multiple of subgroupSize
• If module uses the OpTypeCooperativeMatrixKHR instruction with a Scope equal to Subgroup, then the local workgroup size in the X dimension of the pipeline must be a multiple of the effective subgroup size
• If module uses the OpTypeCooperativeMatrixKHR instruction with a Scope equal to Workgroup, then the local workgroup size in the X dimension of the pipeline must be a multiple of the effective subgroup size and the total local workgroup size must be a power of two multiple of the effective subgroup size and must be less than or equal to cooperativeMatrixWorkgroupScopeMaxWorkgroupSize

• If a shader module identifier is not specified for this stage, module must be a valid ShaderModule , or the pNext chain of the parent Vk*CreateInfo structure must set PipelineBinaryInfoKHR::binaryCount to a value greater than 0, if none of the following features are enabled:

  • graphicsPipelineLibrary
  • maintenance5
• If a shader module identifier is not specified for this stage, module must be a valid ShaderModule, or there must be a valid ShaderModuleCreateInfo structure in the pNext chain , or the pNext chain of the parent Vk*CreateInfo structure must set PipelineBinaryInfoKHR::binaryCount to a value greater than 0,
• If a shader module identifier is specified for this stage, the pNext chain must not include a ShaderModuleCreateInfo structure
• If a shader module identifier is specified for this stage, module must be NULL_HANDLE
• If a shader module identifier is not specified, the shader code used by the pipeline must be valid as described by the Khronos SPIR-V Specification after applying the specializations provided in pSpecializationInfo, if any, and then converting all specialization constants into fixed constants

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_CREATE_INFO

• Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of DebugUtilsObjectNameInfoEXT, Promoted_From_VK_EXT_pipeline_robustnessAdditionalFunctionality.PipelineRobustnessCreateInfo', PipelineShaderStageModuleIdentifierCreateInfoEXT, PipelineShaderStageNodeCreateInfoAMDX, PipelineShaderStageRequiredSubgroupSizeCreateInfo, ShaderDescriptorSetAndBindingMappingInfoEXT, ShaderModuleCreateInfo, or ShaderModuleValidationCacheCreateInfoEXT
• The sType value of each structure in the pNext chain must be unique
• flags must be a valid combination of PipelineShaderStageCreateFlagBits values
• stage must be a valid ShaderStageFlagBits value
• If module is not NULL_HANDLE, module must be a valid ShaderModule handle
• pName must be a null-terminated UTF-8 string
• If pSpecializationInfo is not NULL, pSpecializationInfo must be a valid pointer to a valid SpecializationInfo structure

See Also

VK_VERSION_1_0, ComputePipelineCreateInfo, ExecutionGraphPipelineCreateInfoAMDX, GraphicsPipelineCreateInfo, GraphicsShaderGroupCreateInfoNV, PipelineShaderStageCreateFlags, RayTracingPipelineCreateInfoKHR, RayTracingPipelineCreateInfoNV, ShaderModule, ShaderStageFlagBits, SpecializationInfo, StructureType

VkComputePipelineCreateInfo - Structure specifying parameters of a newly created compute pipeline

Description

The parameters basePipelineHandle and basePipelineIndex are described in more detail in Pipeline Derivatives.

If the pNext chain includes a PipelineCreateFlags2CreateInfo structure, PipelineCreateFlags2CreateInfo::flags from that structure is used instead of flags from this structure.

Valid Usage

• If the pNext chain does not include a PipelineCreateFlags2CreateInfo structure, flags must be a valid combination of PipelineCreateFlagBits values

• If flags contains the PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineIndex is -1, basePipelineHandle must be a valid compute Pipeline handle
• If flags contains the PIPELINE_CREATE_DERIVATIVE_BIT flag, and basePipelineHandle is NULL_HANDLE, basePipelineIndex must be a valid index into the calling command’s pCreateInfos parameter
• If flags contains the PIPELINE_CREATE_DERIVATIVE_BIT flag, basePipelineIndex must be -1 or basePipelineHandle must be NULL_HANDLE
• If a push constant block is declared in a shader and layout is not NULL_HANDLE, a push constant range in layout must match the shader stage
• If a push constant block is declared in a shader and layout is not NULL_HANDLE, the block must be contained inside the push constant range in layout that matches the stage
• If a resource variable is declared in a shader and layout is not NULL_HANDLE, the corresponding descriptor set in layout must match the shader stage
• If a resource variable is declared in a shader, layout is not NULL_HANDLE, and the descriptor type is not DESCRIPTOR_TYPE_MUTABLE_EXT, the corresponding descriptor set in layout must match the descriptor type
• If a resource variable is declared in a shader as an array and layout is not NULL_HANDLE, the corresponding descriptor binding used to create layout must have a descriptorCount that is greater than or equal to the length of the array
• If a resource variables is declared in a shader as an array of descriptors, then the descriptor type of that variable must not be DESCRIPTOR_TYPE_INLINE_UNIFORM_BLOCK
• If shader64BitIndexing feature is not enabled, flags must not contain PIPELINE_CREATE_2_64_BIT_INDEXING_BIT_EXT
• If the pipelineCreationCacheControl feature is not enabled, flags must not include PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT nor PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT
• If the pipelineProtectedAccess feature is not enabled, flags must not include PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT nor PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT
• flags must not include both PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT and PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT
• If PipelineCreateFlags2CreateInfoKHR::flags includes PIPELINE_CREATE_2_DESCRIPTOR_HEAP_BIT_EXT, layout must be NULL_HANDLE
• If PipelineCreateFlags2CreateInfoKHR::flags includes PIPELINE_CREATE_2_DESCRIPTOR_HEAP_BIT_EXT, all shader variables in the shader resource interface with a DescriptorSet and Binding decoration must have a mapping declared in ShaderDescriptorSetAndBindingMappingInfoEXT::pMappings
• flags must not include PIPELINE_CREATE_RAY_TRACING_NO_NULL_ANY_HIT_SHADERS_BIT_KHR
• flags must not include PIPELINE_CREATE_RAY_TRACING_NO_NULL_CLOSEST_HIT_SHADERS_BIT_KHR
• flags must not include PIPELINE_CREATE_RAY_TRACING_NO_NULL_MISS_SHADERS_BIT_KHR
• flags must not include PIPELINE_CREATE_RAY_TRACING_NO_NULL_INTERSECTION_SHADERS_BIT_KHR
• flags must not include PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR
• flags must not include PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR
• flags must not include PIPELINE_CREATE_RAY_TRACING_SHADER_GROUP_HANDLE_CAPTURE_REPLAY_BIT_KHR
• flags must not include PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV
• If the ::deviceGeneratedComputePipelines feature is not enabled, flags must not include PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV
• If flags includes PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV, then the pNext chain must include a pointer to a valid instance of ComputePipelineIndirectBufferInfoNV specifying the address where the pipeline’s metadata will be saved
• If flags includes PIPELINE_CREATE_2_INDIRECT_BINDABLE_BIT_EXT, then the ::deviceGeneratedCommands feature must be enabled
• The stage member of stage must be SHADER_STAGE_COMPUTE_BIT
• The shader code for the entry point identified by stage and the rest of the state identified by this structure must adhere to the pipeline linking rules described in the Shader Interfaces chapter
• If layout is not NULL_HANDLE, the number of resources in layout accessible to the compute shader stage must be less than or equal to PhysicalDeviceLimits::maxPerStageResources
• If the shaderEnqueue feature is not enabled, flags must not include PIPELINE_CREATE_LIBRARY_BIT_KHR
• If flags does not include PIPELINE_CREATE_LIBRARY_BIT_KHR, the shader specified by stage must not declare the ShaderEnqueueAMDX capability
• If PipelineCreationFeedbackCreateInfo::pipelineStageCreationFeedbackCount is not 0, it must be 1
• flags must not include PIPELINE_CREATE_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT
• flags must not include PIPELINE_CREATE_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV
• If PipelineCreateFlags2CreateInfoKHR::flags does not include PIPELINE_CREATE_2_DESCRIPTOR_HEAP_BIT_EXT, layout must not be NULL_HANDLE

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_COMPUTE_PIPELINE_CREATE_INFO

• Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of ComputePipelineIndirectBufferInfoNV, PipelineBinaryInfoKHR, PipelineCompilerControlCreateInfoAMD, PipelineCreateFlags2CreateInfo, PipelineCreationFeedbackCreateInfo, Promoted_From_VK_EXT_pipeline_robustnessAdditionalFunctionality.PipelineRobustnessCreateInfo', or SubpassShadingPipelineCreateInfoHUAWEI
• The sType value of each structure in the pNext chain must be unique
• stage must be a valid PipelineShaderStageCreateInfo structure
• If layout is not NULL_HANDLE, layout must be a valid PipelineLayout handle
• Both of basePipelineHandle, and layout that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same Device

See Also

VK_VERSION_1_0, Pipeline, PipelineCreateFlags, PipelineLayout, PipelineShaderStageCreateInfo, StructureType, createComputePipelines, getPipelineIndirectMemoryRequirementsNV

VkPipeline - Opaque handle to a pipeline object

See Also

VK_DEFINE_NON_DISPATCHABLE_HANDLE, VK_VERSION_1_0, ComputePipelineCreateInfo, DataGraphPipelineInfoARM, DataGraphPipelineSessionCreateInfoARM, ExecutionGraphPipelineCreateInfoAMDX, GeneratedCommandsInfoNV, GeneratedCommandsMemoryRequirementsInfoNV, GeneratedCommandsPipelineInfoEXT, GraphicsPipelineCreateInfo, GraphicsPipelineShaderGroupsCreateInfoNV, IndirectExecutionSetPipelineInfoEXT, PipelineBinaryCreateInfoKHR, PipelineExecutableInfoKHR, PipelineIndirectDeviceAddressInfoNV, PipelineInfoKHR, PipelineLibraryCreateInfoKHR, RayTracingPipelineCreateInfoKHR, RayTracingPipelineCreateInfoNV, ReleaseCapturedPipelineDataInfoKHR, WriteIndirectExecutionSetPipelineEXT, cmdBindPipeline, cmdBindPipelineShaderGroupNV, cmdInitializeGraphScratchMemoryAMDX, cmdUpdatePipelineIndirectBufferNV, compileDeferredNV, createComputePipelines, createDataGraphPipelinesARM, createExecutionGraphPipelinesAMDX, createGraphicsPipelines, createRayTracingPipelinesKHR, createRayTracingPipelinesNV, destroyPipeline, getExecutionGraphPipelineNodeIndexAMDX, getExecutionGraphPipelineScratchSizeAMDX, getRayTracingCaptureReplayShaderGroupHandlesKHR, getRayTracingShaderGroupHandlesKHR, getRayTracingShaderGroupHandlesKHR, getRayTracingShaderGroupStackSizeKHR, getShaderInfoAMD

VkShaderStageFlagBits - Bitmask specifying a pipeline stage

Description

• SHADER_STAGE_VERTEX_BIT specifies the vertex stage.

• SHADER_STAGE_TESSELLATION_CONTROL_BIT specifies the tessellation control stage.
• SHADER_STAGE_TESSELLATION_EVALUATION_BIT specifies the tessellation evaluation stage.
• SHADER_STAGE_GEOMETRY_BIT specifies the geometry stage.
• SHADER_STAGE_FRAGMENT_BIT specifies the fragment stage.
• SHADER_STAGE_COMPUTE_BIT specifies the compute stage.
• SHADER_STAGE_ALL_GRAPHICS is a combination of bits used as shorthand to specify all graphics stages defined above (excluding the compute stage).
• 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.
• SHADER_STAGE_TASK_BIT_EXT specifies the task stage.
• SHADER_STAGE_MESH_BIT_EXT specifies the mesh stage.
• SHADER_STAGE_CLUSTER_CULLING_BIT_HUAWEI specifies the cluster culling stage.
• SHADER_STAGE_RAYGEN_BIT_KHR specifies the ray generation stage.
• SHADER_STAGE_ANY_HIT_BIT_KHR specifies the any-hit stage.
• SHADER_STAGE_CLOSEST_HIT_BIT_KHR specifies the closest hit stage.
• SHADER_STAGE_MISS_BIT_KHR specifies the miss stage.
• SHADER_STAGE_INTERSECTION_BIT_KHR specifies the intersection stage.
• SHADER_STAGE_CALLABLE_BIT_KHR specifies the callable stage.

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.

See Also

VK_VERSION_1_0, PipelineShaderStageCreateInfo, ShaderCreateInfoEXT, ShaderStageFlags, cmdBindShadersEXT, getShaderInfoAMD

VkPipelineCreateFlagBits - Bitmask controlling how a pipeline is created

Description

• 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.

• 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.
• PIPELINE_CREATE_DERIVATIVE_BIT specifies that the pipeline to be created will be a child of a previously created parent pipeline.
• PIPELINE_CREATE_VIEW_INDEX_FROM_DEVICE_INDEX_BIT specifies that any shader input variables decorated as ViewIndex will be assigned values as if they were decorated as DeviceIndex.
• PIPELINE_CREATE_DISPATCH_BASE_BIT specifies that a compute pipeline can be used with cmdDispatchBase with a non-zero base workgroup.
• 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 compileDeferredNV exactly once on each shader in the pipeline before using the pipeline.
• 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 getPipelineExecutableStatisticsKHR. Enabling this flag must not affect the final compiled pipeline but may disable pipeline caching or otherwise affect pipeline creation time.
• 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 getPipelineExecutableInternalRepresentationsKHR. Enabling this flag must not affect the final compiled pipeline but may disable pipeline caching or otherwise affect pipeline creation time. When capturing IR from pipelines created with pipeline libraries, there is no guarantee that IR from libraries can be retrieved from the linked pipeline. Applications should retrieve IR from each library, and any linked pipelines, separately.
• 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 PipelineLibraryCreateInfoKHR structure. This is available in ray tracing and graphics pipelines.
• 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 SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros.
• 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 SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros.
• 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 SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros.
• 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 SHADER_UNUSED_KHR, such as from a shader group consisting entirely of zeros.
• PIPELINE_CREATE_RAY_TRACING_SKIP_TRIANGLES_BIT_KHR specifies that sphere, LSS and triangle primitives will be skipped during traversal using pipeline trace ray instructions.
• PIPELINE_CREATE_RAY_TRACING_SKIP_AABBS_BIT_KHR specifies that AABB primitives will be skipped during traversal using pipeline trace ray instructions.
• 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).
• PIPELINE_CREATE_INDIRECT_BINDABLE_BIT_NV specifies that the pipeline can be used in combination with https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#device-generated-commands.
• PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT specifies that pipeline creation will fail if a compile is required for creation of a valid Pipeline object; PIPELINE_COMPILE_REQUIRED will be returned by pipeline creation, and the Pipeline will be NULL_HANDLE.
• When creating multiple pipelines, PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT specifies that control will be returned to the application if any individual pipeline returns a result which is not SUCCESS rather than continuing to create additional pipelines.
• PIPELINE_CREATE_RAY_TRACING_ALLOW_MOTION_BIT_NV specifies that the pipeline is allowed to use OpTraceRayMotionNV.
• PIPELINE_CREATE_RENDERING_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR specifies that the pipeline will be used with a fragment shading rate attachment and dynamic rendering.
• PIPELINE_CREATE_RENDERING_FRAGMENT_DENSITY_MAP_ATTACHMENT_BIT_EXT specifies that the pipeline will be used with a fragment density map attachment and dynamic rendering.
• PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT specifies that pipeline libraries being linked into this library should have link time optimizations applied. If this bit is omitted, implementations should instead perform linking as rapidly as possible.
• PIPELINE_CREATE_RETAIN_LINK_TIME_OPTIMIZATION_INFO_BIT_EXT specifies that pipeline libraries should retain any information necessary to later perform an optimal link with PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT.
• PIPELINE_CREATE_DESCRIPTOR_BUFFER_BIT_EXT specifies that a pipeline will be used with descriptor buffers, rather than descriptor sets.
• PIPELINE_CREATE_COLOR_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT specifies that the pipeline may be used with an attachment feedback loop including color attachments. It is ignored if DYNAMIC_STATE_ATTACHMENT_FEEDBACK_LOOP_ENABLE_EXT is set in pDynamicStates.
• PIPELINE_CREATE_DEPTH_STENCIL_ATTACHMENT_FEEDBACK_LOOP_BIT_EXT specifies that the pipeline may be used with an attachment feedback loop including depth-stencil attachments. It is ignored if DYNAMIC_STATE_ATTACHMENT_FEEDBACK_LOOP_ENABLE_EXT is set in pDynamicStates.
• PIPELINE_CREATE_RAY_TRACING_OPACITY_MICROMAP_BIT_EXT specifies that the ray tracing pipeline can be used with acceleration structures which reference an opacity micromap array.
• PIPELINE_CREATE_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV specifies that the ray tracing pipeline can be used with acceleration structures which reference a displacement micromap array.
• PIPELINE_CREATE_NO_PROTECTED_ACCESS_BIT specifies that the pipeline must not be bound to a protected command buffer.
• PIPELINE_CREATE_PROTECTED_ACCESS_ONLY_BIT specifies that the pipeline must not be bound to an unprotected command buffer.

It is valid to set both PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT and PIPELINE_CREATE_DERIVATIVE_BIT. This allows a pipeline to be both a parent and possibly a child in a pipeline hierarchy. See Pipeline Derivatives for more information.

When an implementation is looking up a pipeline in a pipeline cache, if that pipeline is being created using linked libraries, implementations should always return an equivalent pipeline created with PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT if available, whether or not that bit was specified.

Using PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT (or not) when linking pipeline libraries is intended as a performance tradeoff between host and device. If the bit is omitted, linking should be faster and produce a pipeline more rapidly, but performance of the pipeline on the target device may be reduced. If the bit is included, linking may be slower but should produce a pipeline with device performance comparable to a monolithically created pipeline. Using both options can allow latency-sensitive applications to generate a suboptimal but usable pipeline quickly, and then perform an optimal link in the background, substituting the result for the suboptimally linked pipeline as soon as it is available.

See Also

VK_VERSION_1_0, PipelineCreateFlags

VkPipelineShaderStageCreateFlagBits - Bitmask controlling how a pipeline shader stage is created

Description

• PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT specifies that the SubgroupSize may vary in the shader stage.

• PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT specifies that the subgroup sizes must be launched with all invocations active in the task, mesh, or compute stage.

If PIPELINE_SHADER_STAGE_CREATE_ALLOW_VARYING_SUBGROUP_SIZE_BIT_EXT and PIPELINE_SHADER_STAGE_CREATE_REQUIRE_FULL_SUBGROUPS_BIT_EXT are specified and minSubgroupSize does not equal maxSubgroupSize and no required subgroup size is specified, then the only way to guarantee that the 'X' dimension of the local workgroup size is a multiple of SubgroupSize is to make it a multiple of maxSubgroupSize. Under these conditions, you are guaranteed full subgroups but not any particular subgroup size.

See Also

VK_VERSION_1_0, PipelineShaderStageCreateFlags

VkPipelineLayoutCreateFlagBits - Pipeline layout creation flag bits

Description

• PIPELINE_LAYOUT_CREATE_INDEPENDENT_SETS_BIT_EXT specifies that implementations must ensure that the properties and/or absence of a particular descriptor set do not influence any other properties of the pipeline layout. This allows pipelines libraries linked without PIPELINE_CREATE_LINK_TIME_OPTIMIZATION_BIT_EXT to be created with a subset of the total descriptor sets.

See Also

VK_EXT_graphics_pipeline_library, PipelineLayoutCreateFlags