VKCMDBEGINRENDERPASS(3)

NAME
vkCmdBeginRenderPass - Begin a new render pass.

C SPECIFICATION

    void vkCmdBeginRenderPass(
        VkCommandBuffer                             commandBuffer,
        const VkRenderPassBeginInfo*                pRenderPassBegin,
        VkSubpassContents                           contents);

PARAMETERS

commandBuffer
    The command buffer in which to begin the render pass.

pRenderPassBegin
    A pointer to a structure describing how to begin the render pass.

contents
    A description of how the commands for the first subpass of the render pass will be issued.

DESCRIPTION

vkCmdBeginRenderPass begins the first subpass of a new render pass in the command buffer specified by commandBuffer. Information about how to begin the render pass is given in an instance of the VkRenderPassBeginInfo structure, a pointer to which is specified in pRenderPassBegin. The definition of VkRenderPassBeginInfo is:

    typedef struct VkRenderPassBeginInfo {
        VkStructureType        sType;
        const void*            pNext;
        VkRenderPass           renderPass;
        VkFramebuffer          framebuffer;
        VkRect2D               renderArea;
        uint32_t               clearValueCount;
        const VkClearValue*    pClearValues;
    } VkRenderPassBeginInfo;

The contents parameter describes how the commands in the first subpass will be provided. If it is VK_SUBPASS_CONTENTS_INLINE, the contents of the subpass will be recorded inline in the primary command buffer, and calling a secondary command buffer within the subpass is an error. If contents is VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS, the contents are recorded in secondary command buffers that will be called from the primary command buffer, and vkCmdExecuteCommands is the only valid command on the command buffer until vkCmdNextSubpass or vkCmdEndRenderPass.

vkCmdBeginRenderPass is only allowed in primary command buffers. A render pass must end in the same command buffer in which it was begun.

VALID USAGE

    • commandBuffer must be a valid VkCommandBuffer handle

    • pRenderPassBegin must be a pointer to a valid VkRenderPassBeginInfo structure

    • contents must be a valid VkSubpassContents value

    • commandBuffer must be in the recording state

    • The VkCommandPool that commandBuffer was allocated from must support graphics operations

    • This command must only be called outside of a render pass instance

    • commandBuffer must be a primary VkCommandBuffer

    • If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL then the corresponding attachment image of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT set

    • If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL or VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL then the corresponding attachment image of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT set

    • If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL then the corresponding attachment image of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with VK_IMAGE_USAGE_SAMPLED_BIT or VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT set

    • If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_TRANSFER_SRC_BIT then the corresponding attachment image of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with VK_IMAGE_USAGE_TRANSFER_SRC_BIT set

    • If any of the initialLayout or finalLayout member of the VkAttachmentDescription structures or the layout member of the VkAttachmentReference structures specified when creating the render pass specified in the renderPass member of pRenderPassBegin is VK_IMAGE_LAYOUT_TRANSFER_DST_BIT then the corresponding attachment image of the framebuffer specified in the framebuffer member of pRenderPassBegin must have been created with VK_IMAGE_USAGE_TRANSFER_DST_BIT set

HOST SYNCHRONIZATION

    • Host access to commandBuffer must be externally synchronized

COMMAND PROPERTIES
Command Buffer Levels | Render Pass Scope | Supported Queue Types
Primary | Outside | GRAPHICS

NOTES

Although vkCmdBeginRenderPass does not generate errors or return a value, enabled validation layers may detect possible error conditions or potentially undefined behavior and report this via some other means.

SEE ALSO

vkCmdEndRenderPass, vkCreateRenderPass, vkDestroyRenderPass, vkCmdNextSubpass, 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.