vkCreateShadersEXT(3)

# vkCreateShadersEXT(3) Manual Page

## Name

vkCreateShadersEXT - Create one or more new shaders

Loading… please wait.

## 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`

On failure, this command returns

  - `VK_ERROR_OUT_OF_HOST_MEMORY`

  - `VK_ERROR_OUT_OF_DEVICE_MEMORY`

  - `VK_ERROR_INITIALIZATION_FAILED`

  - `VK_ERROR_INCOMPATIBLE_SHADER_BINARY_EXT`

## See Also

VK_EXT_shader_object, VkAllocationCallbacks, VkDevice, VkShaderCreateInfoEXT, VkShaderEXT

## 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

Copyright 2014-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0