VkRenderPassBeginInfo(3)

# VkRenderPassBeginInfo(3) Manual Page

## Name

VkRenderPassBeginInfo - Structure specifying render pass begin info

## C Specification

The `VkRenderPassBeginInfo` structure is defined as:

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

## Members

- `sType` is the type of this structure.

- `pNext` is `NULL` or a pointer to an extension-specific structure.

- `renderPass` is the render pass to begin an instance of.

- `framebuffer` is the framebuffer containing the attachments that are used with the render pass.

- `renderArea` is the render area that is affected by the render pass instance, and is described in more detail below.

- `clearValueCount` is the number of elements in `pClearValues`.

- `pClearValues` is a pointer to an array of `clearValueCount` VkClearValue structures that contains clear values for each attachment, if the attachment uses a `loadOp` value of `VK_ATTACHMENT_LOAD_OP_CLEAR` or if the attachment has a depth/stencil format and uses a `stencilLoadOp` value of `VK_ATTACHMENT_LOAD_OP_CLEAR`. The array is indexed by attachment number. Only elements corresponding to cleared attachments are used. Other elements of `pClearValues` are ignored.

## Description

`renderArea` is the render area that is affected by the render pass instance. The effects of attachment load, store and multisample resolve operations are restricted to the pixels whose x and y coordinates fall within the render area on all attachments. The render area extends to all layers of `framebuffer`. The application must ensure (using scissor if necessary) that all rendering is contained within the render area. The render area must be contained within the framebuffer dimensions.

When multiview is enabled, the resolve operation at the end of a subpass applies to all views in the view mask.

| Note There may be a performance cost for using a render area smaller than the framebuffer, unless it matches the render area granularity for the render pass.

Valid Usage

- `clearValueCount` must be greater than the largest attachment index in `renderPass` that specifies a `loadOp` (or `stencilLoadOp`, if the attachment has a depth/stencil format) of `VK_ATTACHMENT_LOAD_OP_CLEAR`

- `renderPass` must be compatible with the `renderPass` member of the `VkFramebufferCreateInfo` structure specified when creating `framebuffer`.

- If `framebuffer` was created with a VkFramebufferCreateInfo::`flags` value that did not include `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR`, and the `pNext` chain includes an instance of VkRenderPassAttachmentBeginInfoKHR, its `attachmentCount` must be zero

- If `framebuffer` was created with a VkFramebufferCreateInfo::`flags` value that included `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR`, the `attachmentCount` of an instance of VkRenderPassAttachmentBeginInfoKHR included in the `pNext` chain must be equal to the value of VkFramebufferAttachmentsCreateInfoKHR::`attachmentImageInfoCount` used to create `framebuffer`

- If `framebuffer` was created with a VkFramebufferCreateInfo::`flags` value that included `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR`, each element of the `pAttachments` member of an instance of VkRenderPassAttachmentBeginInfoKHR included in the `pNext` chain must have been created on the same VkDevice as `framebuffer` and `renderPass`

- If `framebuffer` was created with a VkFramebufferCreateInfo::`flags` value that included `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR`, each element of the `pAttachments` member of an instance of VkRenderPassAttachmentBeginInfoKHR included in the `pNext` chain must be a VkImageView of an image created with a value of VkImageCreateInfo::`flags` equal to the `flags` member of the corresponding element of VkFramebufferAttachmentsCreateInfoKHR::`pAttachments` used to create `framebuffer`

- If `framebuffer` was created with a VkFramebufferCreateInfo::`flags` value that included `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR`, each element of the `pAttachments` member of an instance of VkRenderPassAttachmentBeginInfoKHR included in the `pNext` chain must be a VkImageView of an image created with a value of VkImageCreateInfo::`usage` equal to the `usage` member of the corresponding element of VkFramebufferAttachmentsCreateInfoKHR::`pAttachments` used to create `framebuffer`

- If `framebuffer` was created with a VkFramebufferCreateInfo::`flags` value that included `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR`, each element of the `pAttachments` member of an instance of VkRenderPassAttachmentBeginInfoKHR included in the `pNext` chain must be a VkImageView with a width equal to the `width` member of the corresponding element of VkFramebufferAttachmentsCreateInfoKHR::`pAttachments` used to create `framebuffer`

- If `framebuffer` was created with a VkFramebufferCreateInfo::`flags` value that included `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR`, each element of the `pAttachments` member of an instance of VkRenderPassAttachmentBeginInfoKHR included in the `pNext` chain must be a VkImageView with a height equal to the `height` member of the corresponding element of VkFramebufferAttachmentsCreateInfoKHR::`pAttachments` used to create `framebuffer`

- If `framebuffer` was created with a VkFramebufferCreateInfo::`flags` value that included `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR`, each element of the `pAttachments` member of an instance of VkRenderPassAttachmentBeginInfoKHR included in the `pNext` chain must be a VkImageView of an image created with a value of VkImageViewCreateInfo::`subresourceRange.pname`:layerCount equal to the `layerCount` member of the corresponding element of VkFramebufferAttachmentsCreateInfoKHR::`pAttachments` used to create `framebuffer`

- If `framebuffer` was created with a VkFramebufferCreateInfo::`flags` value that included `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR`, each element of the `pAttachments` member of an instance of VkRenderPassAttachmentBeginInfoKHR included in the `pNext` chain must be a VkImageView of an image created with a value of VkImageFormatListCreateInfoKHR::`viewFormatCount` equal to the `viewFormatCount` member of the corresponding element of VkFramebufferAttachmentsCreateInfoKHR::`pAttachments` used to create `framebuffer`

- If `framebuffer` was created with a VkFramebufferCreateInfo::`flags` value that included `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR`, each element of the `pAttachments` member of an instance of VkRenderPassAttachmentBeginInfoKHR included in the `pNext` chain must be a VkImageView of an image created with a set of elements in VkImageFormatListCreateInfoKHR::`pViewFormats` equal to the set of elements in the `pViewFormats` member of the corresponding element of VkFramebufferAttachmentsCreateInfoKHR::`pAttachments` used to create `framebuffer`

- If `framebuffer` was created with a VkFramebufferCreateInfo::`flags` value that included `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR`, each element of the `pAttachments` member of an instance of VkRenderPassAttachmentBeginInfoKHR included in the `pNext` chain must be a VkImageView of an image created with a value of VkImageViewCreateInfo::`format` equal to the corresponding value of VkAttachmentDescription::`format` in `renderPass`

- If `framebuffer` was created with a VkFramebufferCreateInfo::`flags` value that included `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR`, each element of the `pAttachments` member of an instance of VkRenderPassAttachmentBeginInfoKHR included in the `pNext` chain must be a VkImageView of an image created with a value of VkImageCreateInfo::`samples` equal to the corresponding value of VkAttachmentDescription::`samples` in `renderPass`

Valid Usage (Implicit)

- `sType` must be `VK_STRUCTURE_TYPE_RENDER_PASS_BEGIN_INFO`

- Each `pNext` member of any structure (including this one) in the `pNext` chain must be either `NULL` or a pointer to a valid instance of VkDeviceGroupRenderPassBeginInfo, VkRenderPassAttachmentBeginInfoKHR, or VkRenderPassSampleLocationsBeginInfoEXT

- Each `sType` member in the `pNext` chain must be unique

- `renderPass` must be a valid `VkRenderPass` handle

- `framebuffer` must be a valid `VkFramebuffer` handle

- If `clearValueCount` is not `0`, `pClearValues` must be a valid pointer to an array of `clearValueCount` `VkClearValue` unions

- Both of `framebuffer`, and `renderPass` must have been created, allocated, or retrieved from the same `VkDevice`

## See Also

VkClearValue, VkFramebuffer, VkRect2D, VkRenderPass, VkStructureType, vkCmdBeginRenderPass, vkCmdBeginRenderPass2KHR

## 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 (c) 2014-2019 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.