VKCREATEGRAPHICSPIPE(3)

NAME
vkCreateGraphicsPipelines - Create graphics pipelines.

C SPECIFICATION

    VkResult vkCreateGraphicsPipelines(
        VkDevice                                    device,
        VkPipelineCache                             pipelineCache,
        uint32_t                                    createInfoCount,
        const VkGraphicsPipelineCreateInfo*         pCreateInfos,
        const VkAllocationCallbacks*                pAllocator,
        VkPipeline*                                 pPipelines);

PARAMETERS

device
    A handle to the device to use to create the new graphics pipeline(s).

pipelineCache
    A handle to a pipeline cache from which the result of previous compiles may be retrieved, and to which the result of this compile may be stored.

createInfoCount
    The number of pipelines to create.

pCreateInfos
    Pointer to an array of createInfoCount VkGraphicsPipelineCreateInfo structures defining the contents of the new pipelines.

pPipelines
    A pointer to an array to receive the handle(s) to the new graphics pipeline object(s).

DESCRIPTION

vkCreateGraphicsPipelines creates new graphics pipeline objects using the device specified in device and the creation information specified in the structures pointed to by pCreateInfos and deposits the resulting handles in the array pointed to by pPipelines. The definition of VkGraphicsPipelineCreateInfo is:

    typedef struct VkGraphicsPipelineCreateInfo {
        VkStructureType                                  sType;
        const void*                                      pNext;
        VkPipelineCreateFlags                            flags;
        uint32_t                                         stageCount;
        const VkPipelineShaderStageCreateInfo*           pStages;
        const VkPipelineVertexInputStateCreateInfo*      pVertexInputState;
        const VkPipelineInputAssemblyStateCreateInfo*    pInputAssemblyState;
        const VkPipelineTessellationStateCreateInfo*     pTessellationState;
        const VkPipelineViewportStateCreateInfo*         pViewportState;
        const VkPipelineRasterizationStateCreateInfo*    pRasterizationState;
        const VkPipelineMultisampleStateCreateInfo*      pMultisampleState;
        const VkPipelineDepthStencilStateCreateInfo*     pDepthStencilState;
        const VkPipelineColorBlendStateCreateInfo*       pColorBlendState;
        const VkPipelineDynamicStateCreateInfo*          pDynamicState;
        VkPipelineLayout                                 layout;
        VkRenderPass                                     renderPass;
        uint32_t                                         subpass;
        VkPipeline                                       basePipelineHandle;
        int32_t                                          basePipelineIndex;
    } VkGraphicsPipelineCreateInfo;

Create Info Details

    • pStages points to an array of stageCount VkPipelineShaderStageCreateInfo objects describing the stages comprising the pipeline. At minimum, the vertex shader stage must be defined.

    • pVertexInputState points to a VkPipelineVertexInputStateCreateInfo object describing the layout of the vertex buffers as well as the attributes within the buffers for the pipeline.

    • pInputAssemblyState points to a VkPipelineInputAssemblyStateCreateInfo object describing the input assembly state for the pipeline, including the primitive type and topology.

    • pTessellationState points to a VkPipelineTessellationStateCreateInfo object describing the patch control state for the tesselation stage of the pipeline, or is set to NULL if no tesselation stage is defined.

    • pViewportState points to a VkPipelineViewportStateCreateInfo object describing the viewport state for the pipeline.

    • pRasterizationState points to a VkPipelineRasterizationStateCreateInfo object describing the rasterizer state for the pipeline, including fill mode, clip mode, and face orientation.

    • pMultisampleState points to a VkPipelineMultisampleStateCreateInfo object describing the multisample state for the pipeline.

    • pDepthStencilState points to a VkPipelineDepthStencilStateCreateInfo object describing the depth and stencil state for the pipeline.

    • pColorBlendState points to a VkPipelineColorBlendStateCreateInfo object describing the color buffer state for the pipeline, including state for each of the attachments that will be bound to the framebuffer.

    • flags is an instance of VkPipelineCreateFlags, indicating additional usage hint (e.g., if this pipeline will be used to create derivative pipelines).

    • layout is a handle to a VkPipelineLayout object created with vkCreatePipelineLayout.

    • renderPass is a handle to a VkRenderPass object describing a renderpass the pipeline will be compatible with.

    • subpass is the index of the subpass in the renderPass the pipeline will be compatible with.

The created pipeline may only be used in a subpass compatible with the provided renderPass and subpass. Two subpasses are compatible if they have the same index in their render passes, and if the render pass descriptions are identical except for attachment load and store ops and image layouts. For a render pass with only one subpass, the subpasses are compatible if they have the same number and kind of attachments, and if corresponding attachments have the same format and sample count.

VALID USAGE

    • device must be a valid VkDevice handle

    • If pipelineCache is not VK_NULL_HANDLE, pipelineCache must be a valid VkPipelineCache handle

    • pCreateInfos must be a pointer to an array of createInfoCount valid VkGraphicsPipelineCreateInfo structures

    • If pAllocator is not NULL, pAllocator must be a pointer to a valid VkAllocationCallbacks structure

    • pPipelines must be a pointer to an array of createInfoCount VkPipeline handles

    • createInfoCount must be greater than 0

    • If pipelineCache is a valid handle, it must have been created, allocated or retrieved from device

    • Each of device and pipelineCache that are valid handles must have been created, allocated or retrieved from the same VkPhysicalDevice

    • If the flags member of any given element of pCreateInfos contains the VK_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

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

SEE ALSO

vkCreateComputePipelines, vkCmdBindPipeline, vkDestroyPipeline

COPYRIGHT

Copyright © 2014-2016 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.

AUTHOR

Khronos Group
    Author.