Structure specifying render pass begin information.

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, after any transform specified by VkRenderPassTransformBeginInfoQCOM::transform is applied, must be contained within the framebuffer dimensions.

If render pass transform is enabled, then renderArea must equal the framebuffer pre-transformed dimensions. After renderArea has been transformed by VkRenderPassTransformBeginInfoQCOM::transform, the resulting render area must be equal to the framebuffer dimensions.

If multiview is enabled in renderPass, and multiviewPerViewRenderAreas feature is enabled, and there is an instance of VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM included in the pNext chain with perViewRenderAreaCount not equal to 0, then the elements of VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM::pPerViewRenderAreas override renderArea and define a render area for each view. In this case, renderArea must be set to an area at least as large as the union of all the per-view render areas.

If the subpassShading feature is enabled, then renderArea must equal the framebuffer dimensions.

Valid Usage

• clearValueCount must be greater than the largest attachment index in renderPass specifying a loadOp (or stencilLoadOp, if the attachment has a depth/stencil format) of ATTACHMENT_LOAD_OP_CLEAR
• If clearValueCount is not 0, pClearValues must be a valid pointer to an array of clearValueCount VkClearValue unions
• renderPass must be compatible with the renderPass member of the VkFramebufferCreateInfo structure specified when creating framebuffer
• If VkDeviceGroupRenderPassBeginInfo::deviceRenderAreaCount is 0, renderArea.extent.width must be greater than 0
• If VkDeviceGroupRenderPassBeginInfo::deviceRenderAreaCount is 0, renderArea.extent.height must be greater than 0
• If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0, renderArea.offset.x must be greater than or equal to 0
• If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0, renderArea.offset.y must be greater than or equal to 0
• If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0, renderArea.offset.x + renderArea.extent.width must be less than or equal to VkFramebufferCreateInfo::width the framebuffer was created with
• If the pNext chain does not contain VkDeviceGroupRenderPassBeginInfo or its deviceRenderAreaCount member is equal to 0, renderArea.offset.y + renderArea.extent.height must be less than or equal to VkFramebufferCreateInfo::height the framebuffer was created with
• If the pNext chain contains VkDeviceGroupRenderPassBeginInfo, offset.x + extent.width of each element of pDeviceRenderAreas must be less than or equal to VkFramebufferCreateInfo::width the framebuffer was created with
• If the pNext chain contains VkDeviceGroupRenderPassBeginInfo, offset.y + extent.height of each element of pDeviceRenderAreas must be less than or equal to VkFramebufferCreateInfo::height the framebuffer was created with
• If framebuffer was created with a VkFramebufferCreateInfo::flags value that did not include FRAMEBUFFER_CREATE_IMAGELESS_BIT, and the pNext chain includes a VkRenderPassAttachmentBeginInfo structure, its attachmentCount must be zero
• If framebuffer was created with a VkFramebufferCreateInfo::flags value that included FRAMEBUFFER_CREATE_IMAGELESS_BIT, the attachmentCount of a VkRenderPassAttachmentBeginInfo structure included in the pNext chain must be equal to the value of VkFramebufferAttachmentsCreateInfo::attachmentImageInfoCount used to create framebuffer
• If framebuffer was created with a VkFramebufferCreateInfo::flags value that included FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pAttachments member of a VkRenderPassAttachmentBeginInfo structure 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 FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pAttachments member of a VkRenderPassAttachmentBeginInfo structure 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 VkFramebufferAttachmentsCreateInfo::pAttachmentImageInfos used to create framebuffer
• If framebuffer was created with a VkFramebufferCreateInfo::flags value that included FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pAttachments member of a VkRenderPassAttachmentBeginInfo structure included in the pNext chain must be a VkImageView with an inherited usage equal to the usage member of the corresponding element of VkFramebufferAttachmentsCreateInfo::pAttachmentImageInfos used to create framebuffer
• If framebuffer was created with a VkFramebufferCreateInfo::flags value that included FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pAttachments member of a VkRenderPassAttachmentBeginInfo structure included in the pNext chain must be a VkImageView with a width equal to the width member of the corresponding element of VkFramebufferAttachmentsCreateInfo::pAttachmentImageInfos used to create framebuffer
• If framebuffer was created with a VkFramebufferCreateInfo::flags value that included FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pAttachments member of a VkRenderPassAttachmentBeginInfo structure included in the pNext chain must be a VkImageView with a height equal to the height member of the corresponding element of VkFramebufferAttachmentsCreateInfo::pAttachmentImageInfos used to create framebuffer
• If framebuffer was created with a VkFramebufferCreateInfo::flags value that included FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pAttachments member of a VkRenderPassAttachmentBeginInfo structure included in the pNext chain must be a VkImageView of an image created with a value of VkImageViewCreateInfo::subresourceRange.layerCount equal to the layerCount member of the corresponding element of VkFramebufferAttachmentsCreateInfo::pAttachmentImageInfos used to create framebuffer
• If framebuffer was created with a VkFramebufferCreateInfo::flags value that included FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pAttachments member of a VkRenderPassAttachmentBeginInfo structure included in the pNext chain must be a VkImageView of an image created with a value of VkImageFormatListCreateInfo::viewFormatCount equal to the viewFormatCount member of the corresponding element of VkFramebufferAttachmentsCreateInfo::pAttachmentImageInfos used to create framebuffer
• If framebuffer was created with a VkFramebufferCreateInfo::flags value that included FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pAttachments member of a VkRenderPassAttachmentBeginInfo structure included in the pNext chain must be a VkImageView of an image created with a set of elements in VkImageFormatListCreateInfo::pViewFormats equal to the set of elements in the pViewFormats member of the corresponding element of VkFramebufferAttachmentsCreateInfo::pAttachmentImageInfos used to create framebuffer
• If framebuffer was created with a VkFramebufferCreateInfo::flags value that included FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pAttachments member of a VkRenderPassAttachmentBeginInfo structure 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 FRAMEBUFFER_CREATE_IMAGELESS_BIT, each element of the pAttachments member of a VkRenderPassAttachmentBeginInfo structure 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 , or SAMPLE_COUNT_1_BIT if renderPass was created with VkMultisampledRenderToSingleSampledInfoEXT structure in the pNext chain with multisampledRenderToSingleSampledEnable equal to TRUE
• If the pNext chain includes VkRenderPassTransformBeginInfoQCOM, renderArea.offset must equal (0,0)
• If the pNext chain includes VkRenderPassTransformBeginInfoQCOM, renderArea.extent transformed by VkRenderPassTransformBeginInfoQCOM::transform must equal the framebuffer dimensions
• If the perViewRenderAreaCount member of a VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM structure included in the pNext chain is not 0, then the multiviewPerViewRenderAreas feature must be enabled.
• If the perViewRenderAreaCount member of a VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM structure included in the pNext chain is not 0, then renderArea must specify a render area that includes the union of all per view render areas.

Valid Usage (Implicit)

• sType must be 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, VkMultiviewPerViewRenderAreasRenderPassBeginInfoQCOM, VkRenderPassAttachmentBeginInfo, VkRenderPassSampleLocationsBeginInfoEXT, or VkRenderPassTransformBeginInfoQCOM
• The sType value of each struct in the pNext chain must be unique
• renderPass must be a valid VkRenderPass handle
• framebuffer must be a valid VkFramebuffer handle
• Both of framebuffer, and renderPass must have been created, allocated, or retrieved from the same VkDevice

See Also

VkClearValue, VkRect2D, CmdBeginRenderPass, CmdBeginRenderPass2, CmdBeginRenderPass2KHR

Layout

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