VKCREATERENDERPASS(3)

NAME
vkCreateRenderPass - Create a new render pass object.

C SPECIFICATION

    VkResult vkCreateRenderPass(
        VkDevice                                    device,
        const VkRenderPassCreateInfo*               pCreateInfo,
        const VkAllocationCallbacks*                pAllocator,
        VkRenderPass*                               pRenderPass);

PARAMETERS

device
    The device with which to create the render pass object.

pCreateInfo
    A pointer to a structure containing information to be placed in the object.

pRenderPass
    A pointer to a variable which will receive the handle to the new object.

DESCRIPTION

vkCreateRenderPass creates a new render pass object using the information contained in pCreateInfo and the device specified in device. Upon success, a handle to the new render pass object is deposited in the variable pointed to by pRenderPass, pCreateInfo should point to an instance of the VkRenderPassCreateInfo structure, the definition of which is:

    typedef struct VkRenderPassCreateInfo {
        VkStructureType                   sType;
        const void*                       pNext;
        VkRenderPassCreateFlags           flags;
        uint32_t                          attachmentCount;
        const VkAttachmentDescription*    pAttachments;
        uint32_t                          subpassCount;
        const VkSubpassDescription*       pSubpasses;
        uint32_t                          dependencyCount;
        const VkSubpassDependency*        pDependencies;
    } VkRenderPassCreateInfo;

A render pass is a sequence of subpasses, each of which reads from some framebuffer attachments and writes to others as color and depth/stencil. The subpasses all render to the same dimensions, and fragments for pixel (x,y,layer) in one subpass only read framebuffer contents written by earlier subpasses at that same (x,y,layer) location. It is quite common for a render pass to only contain a single subpass.

Dependencies between subpasses describe ordering restrictions between them. Without dependencies, implementations may reorder or overlap execution of two subpasses.

  Attachments

The attachments used in the render pass are described by a VkAttachmentDescription structure, defined as:

    typedef struct VkAttachmentDescription {
        VkAttachmentDescriptionFlags    flags;
        VkFormat                        format;
        VkSampleCountFlagBits           samples;
        VkAttachmentLoadOp              loadOp;
        VkAttachmentStoreOp             storeOp;
        VkAttachmentLoadOp              stencilLoadOp;
        VkAttachmentStoreOp             stencilStoreOp;
        VkImageLayout                   initialLayout;
        VkImageLayout                   finalLayout;
    } VkAttachmentDescription;

The format and samples members are respectively the format and the number of samples of the image that will be used for the attachment.

The loadOp defines how the contents of the attachment within the render area will be treated at the beginning of the render pass. A load op of VK_ATTACHMENT_LOAD_OP_LOAD means the contents within the render area will be preserved; VK_ATTACHMENT_LOAD_OP_CLEAR means the contents within the render area will be cleared to a uniform value; VK_ATTACHMENT_LOAD_OP_DONT_CARE means the application intends to overwrite all samples in the render area without reading the initial contents, so their initial contents are unimportant. If the attachment format has both depth and stencil components, loadOp applies only to the depth data, while stencilLoadOp defines how the stencil data is handled. stencilLoadOp is ignored for other formats.

The storeOp defines whether data rendered to the attachment is committed to memory at the end of the render pass. VK_ATTACHMENT_STORE_OP_STORE means the data is committed to memory and will be available for reading after the render pass completes. VK_ATTACHMENT_STORE_OP_DONT_CARE means the data is not needed after rendering, and may be discarded; the contents of the attachment will be undefined inside the render area. If the attachment format has both depth and stencil components, storeOp applies only to the depth data, while stencilStoreOp defines how the stencil data is handled. stencilStoreOp is ignored for other formats.

initialLayout is the layout the attachment image will be in when the render pass begins.

finalLayout is the layout the attachment image will be transitioned to when the render pass ends.

  Subpasses

Subpasses of a render pass are described by a VkSubpassDescription structure, defined as:

    typedef struct VkSubpassDescription {
        VkSubpassDescriptionFlags       flags;
        VkPipelineBindPoint             pipelineBindPoint;
        uint32_t                        inputAttachmentCount;
        const VkAttachmentReference*    pInputAttachments;
        uint32_t                        colorAttachmentCount;
        const VkAttachmentReference*    pColorAttachments;
        const VkAttachmentReference*    pResolveAttachments;
        const VkAttachmentReference*    pDepthStencilAttachment;
        uint32_t                        preserveAttachmentCount;
        const uint32_t*                 pPreserveAttachments;
    } VkSubpassDescription;

The pipelineBindPoint indicates whether this is a compute or graphics subpass. Only graphics subpasses are currently allowed.

The flags member is currently unused and must be zero.

pInputAttachments lists which of the render pass’s attachments will be read in the shader in the subpass, and what layout the attachment images should be transitioned to before the subpass. inputAttachmentCount indicates the number of input attachments. Input attachments must also be bound to the pipeline with a descriptor set.

pColorAttachments lists which of the render pass’s attachments will be used as color attachments in the subpass, and what layout the attachment images should be transitioned to before the subpass. colorAttachmentCount indicates the number of color attachments.

Each entry in pResolveAttachments corresponds to an entry in pColorAttachments; either pResolveAttachments must be NULL or it must have colorAttachmentCount entries. If pResolveAttachments is not NULL, each of its elements corresponds to a color attachment (the element in pColorAttachments at the same index). At the end of each subpass, the subpass’s color attachments will be resolved to the corresponding resolve attachments, unless the resolve attachment index is VK_ATTACHMENT_UNUSED.

The depthStencilAttachment indicates which attachment will be used for depth/stencil data and the layout it should be transitioned to before the subpass. If no depth/stencil attachment is used in the subpass, the attachment index must be VK_ATTACHMENT_UNUSED.

The pPreserveAttachments are the attachments that aren’t used by a subpass, but whose contents must be preserved throughout the subpass. If the contents of an attachment are produced in one subpass and consumed in a later subpass, the attachment must be preserved in any subpasses on dependency chains from the producer to consumer. preserveAttachmentCount indicates the number of preserved attachments.

If a subpass uses an attachment as both an input attachment and either a color attachment or a depth/stencil attachment, all pipelines used in the subpass must disable writes to any components of the attachment format that are used as input.

  Dependencies

Dependencies describe a pipeline barrier that must occur between two subpasses, usually because the destination subpass reads attachment contents written by the source subpass. Dependencies are described by VkSubpassDependency structures, defined as:

    typedef struct VkSubpassDependency {
        uint32_t                srcSubpass;
        uint32_t                dstSubpass;
        VkPipelineStageFlags    srcStageMask;
        VkPipelineStageFlags    dstStageMask;
        VkAccessFlags           srcAccessMask;
        VkAccessFlags           dstAccessMask;
        VkDependencyFlags       dependencyFlags;
    } VkSubpassDependency;

The srcSubpass and dstSubpass are producer and consumer subpasses, respectively. srcSubpass must be less than or equal to dstSubpass, so that the order of subpass descriptions is always a valid execution ordering, and so the dependency graph cannot have cycles.

The srcStageMask, dstStageMask, outputMask, inputMask, and byRegion describe the barrier, and have the same meaning as the VkCmdPipelineBarrier parameters and VkMemoryBarrier members with the same names.

If byRegion is VK_TRUE, it describes a per-region (x,y,layer) dependency, that is for each region, the srcStageMask stages must have finished in srcSubpass before any dstStageMask stage starts in dstSubpass for the same region. If byRegion is VK_FALSE, it describes a global dependency, that is the srcStageMask stages must have finished for all regions in srcSubpass before any dstStageMask stage starts in dstSubpass for any region.

VALID USAGE

    • device must be a valid VkDevice handle

    • pCreateInfo must be a pointer to a valid VkRenderPassCreateInfo structure

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

    • pRenderPass must be a pointer to a VkRenderPass handle

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

vkCmdBeginRenderPass, vkCmdEndRenderPass

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.