C Specification

To create one or more shader objects, call:

// Provided by VK_EXT_shader_object
VkResult vkCreateShadersEXT(
    VkDevice                                    device,
    uint32_t                                    createInfoCount,
    const VkShaderCreateInfoEXT*                pCreateInfos,
    const VkAllocationCallbacks*                pAllocator,
    VkShaderEXT*                                pShaders);

Parameters

  • device is the logical device that creates the shader objects.

  • createInfoCount is the length of the pCreateInfos and pShaders arrays.

  • pCreateInfos is a pointer to an array of VkShaderCreateInfoEXT structures.

  • pAllocator controls host memory allocation as described in the Memory Allocation chapter.

  • pShaders is a pointer to an array of VkShaderEXT handles in which the resulting shader objects are returned.

Description

When this function returns, whether or not it succeeds, it is guaranteed that every element of pShaders will have been overwritten by either VK_NULL_HANDLE or a valid VkShaderEXT handle.

This means that whenever shader creation fails, the application can determine which shader the returned error pertains to by locating the first VK_NULL_HANDLE element in pShaders. It also means that an application can reliably clean up from a failed call by iterating over the pShaders array and destroying every element that is not VK_NULL_HANDLE.

Valid Usage
  • VUID-vkCreateShadersEXT-None-08400
    The shaderObject feature must be enabled

  • VUID-vkCreateShadersEXT-pCreateInfos-08402
    If the flags member of any element of pCreateInfos includes VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, the flags member of all other elements of pCreateInfos whose stage is VK_SHADER_STAGE_VERTEX_BIT, VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT, VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, VK_SHADER_STAGE_GEOMETRY_BIT, or VK_SHADER_STAGE_FRAGMENT_BIT must also include VK_SHADER_CREATE_LINK_STAGE_BIT_EXT

  • VUID-vkCreateShadersEXT-pCreateInfos-08403
    If the flags member of any element of pCreateInfos includes VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, the flags member of all other elements of pCreateInfos whose stage is VK_SHADER_STAGE_TASK_BIT_EXT or VK_SHADER_STAGE_MESH_BIT_EXT must also include VK_SHADER_CREATE_LINK_STAGE_BIT_EXT

  • VUID-vkCreateShadersEXT-pCreateInfos-08404
    If the flags member of any element of pCreateInfos whose stage is VK_SHADER_STAGE_TASK_BIT_EXT or VK_SHADER_STAGE_MESH_BIT_EXT includes VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, there must be no member of pCreateInfos whose stage is VK_SHADER_STAGE_VERTEX_BIT and whose flags member includes VK_SHADER_CREATE_LINK_STAGE_BIT_EXT

  • VUID-vkCreateShadersEXT-pCreateInfos-08405
    If there is any element of pCreateInfos whose stage is VK_SHADER_STAGE_MESH_BIT_EXT and whose flags member includes both VK_SHADER_CREATE_LINK_STAGE_BIT_EXT and VK_SHADER_CREATE_NO_TASK_SHADER_BIT_EXT, there must be no element of pCreateInfos whose stage is VK_SHADER_STAGE_TASK_BIT_EXT and whose flags member includes VK_SHADER_CREATE_LINK_STAGE_BIT_EXT

  • VUID-vkCreateShadersEXT-pCreateInfos-08409
    For each element of pCreateInfos whose flags member includes VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, if there is any other element of pCreateInfos whose stage is logically later than the stage of the former and whose flags member also includes VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, the nextStage of the former must be equal to the stage of the element with the logically earliest stage following the stage of the former whose flags member also includes VK_SHADER_CREATE_LINK_STAGE_BIT_EXT

  • VUID-vkCreateShadersEXT-pCreateInfos-08410
    The stage member of each element of pCreateInfos whose flags member includes VK_SHADER_CREATE_LINK_STAGE_BIT_EXT must be unique

  • VUID-vkCreateShadersEXT-pCreateInfos-08411
    The codeType member of all elements of pCreateInfos whose flags member includes VK_SHADER_CREATE_LINK_STAGE_BIT_EXT must be the same

  • VUID-vkCreateShadersEXT-pCreateInfos-08867
    If pCreateInfos contains elements with both VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT and VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, both elements' flags include VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, both elements' codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and the VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT stage’s pCode contains an OpExecutionMode instruction specifying the type of subdivision, it must match the subdivision type specified in the VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT stage

  • VUID-vkCreateShadersEXT-pCreateInfos-08868
    If pCreateInfos contains elements with both VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT and VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, both elements' flags include VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, both elements' codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and the VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT stage’s pCode contains an OpExecutionMode instruction specifying the orientation of triangles, it must match the triangle orientation specified in the VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT stage

  • VUID-vkCreateShadersEXT-pCreateInfos-08869
    If pCreateInfos contains elements with both VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT and VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, both elements' flags include VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, both elements' codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and the VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT stage’s pCode contains an OpExecutionMode instruction specifying PointMode, the VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT stage must also contain an OpExecutionMode instruction specifying PointMode

  • VUID-vkCreateShadersEXT-pCreateInfos-08870
    If pCreateInfos contains elements with both VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT and VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, both elements' flags include VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, both elements' codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and the VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT stage’s pCode contains an OpExecutionMode instruction specifying the spacing of segments on the edges of tessellated primitives, it must match the segment spacing specified in the VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT stage

  • VUID-vkCreateShadersEXT-pCreateInfos-08871
    If pCreateInfos contains elements with both VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT and VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT, both elements' flags include VK_SHADER_CREATE_LINK_STAGE_BIT_EXT, both elements' codeType is VK_SHADER_CODE_TYPE_SPIRV_EXT, and the VK_SHADER_STAGE_TESSELLATION_CONTROL_BIT stage’s pCode contains an OpExecutionMode instruction specifying the output patch size, it must match the output patch size specified in the VK_SHADER_STAGE_TESSELLATION_EVALUATION_BIT stage

Valid Usage (Implicit)
  • VUID-vkCreateShadersEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkCreateShadersEXT-pCreateInfos-parameter
    pCreateInfos must be a valid pointer to an array of createInfoCount valid VkShaderCreateInfoEXT structures

  • VUID-vkCreateShadersEXT-pAllocator-parameter
    If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • VUID-vkCreateShadersEXT-pShaders-parameter
    pShaders must be a valid pointer to an array of createInfoCount VkShaderEXT handles

  • VUID-vkCreateShadersEXT-createInfoCount-arraylength
    createInfoCount must be greater than 0

Return Codes
On success, this command returns
  • VK_SUCCESS

  • VK_INCOMPATIBLE_SHADER_BINARY_EXT

On failure, this command returns
  • VK_ERROR_OUT_OF_HOST_MEMORY

  • VK_ERROR_OUT_OF_DEVICE_MEMORY

  • VK_ERROR_INITIALIZATION_FAILED

See Also

Document Notes

For more information, see the Vulkan Specification

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

Copyright 2014-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0