C Specification

The VkFramebufferCreateInfo structure is defined as:

typedef struct VkFramebufferCreateInfo {
    VkStructureType             sType;
    const void*                 pNext;
    VkFramebufferCreateFlags    flags;
    VkRenderPass                renderPass;
    uint32_t                    attachmentCount;
    const VkImageView*          pAttachments;
    uint32_t                    width;
    uint32_t                    height;
    uint32_t                    layers;
} VkFramebufferCreateInfo;

Members

  • sType is the type of this structure.

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

  • flags is a bitmask of VkFramebufferCreateFlagBits

  • renderPass is a render pass defining what render passes the framebuffer will be compatible with. See Render Pass Compatibility for details.

  • attachmentCount is the number of attachments.

  • pAttachments is a pointer to an array of VkImageView handles, each of which will be used as the corresponding attachment in a render pass instance. If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, this parameter is ignored.

  • width, height and layers define the dimensions of the framebuffer. If the render pass uses multiview, then layers must be one and each attachment requires a number of layers that is greater than the maximum bit index set in the view mask in the subpasses in which it is used.

Description

Applications must ensure that all accesses to memory that backs image subresources used as attachments in a given renderpass instance either happen-before the load operations for those attachments, or happen-after the store operations for those attachments.

For depth/stencil attachments, each aspect can be used separately as attachments and non-attachments as long as the non-attachment accesses are also via an image subresource in either the VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL layout or the VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL layout, and the attachment resource uses whichever of those two layouts the image accesses do not. Use of non-attachment aspects in this case is only well defined if the attachment is used in the subpass where the non-attachment access is being made, or the layout of the image subresource is constant throughout the entire render pass instance, including the initialLayout and finalLayout.

Note

These restrictions mean that the render pass has full knowledge of all uses of all of the attachments, so that the implementation is able to make correct decisions about when and how to perform layout transitions, when to overlap execution of subpasses, etc.

It is legal for a subpass to use no color or depth/stencil attachments, and rather use shader side effects such as image stores and atomics to produce an output. In this case, the subpass continues to use the width, height, and layers of the framebuffer to define the dimensions of the rendering area, and the rasterizationSamples from each pipeline’s VkPipelineMultisampleStateCreateInfo to define the number of samples used in rasterization; however, if VkPhysicalDeviceFeatures::variableMultisampleRate is VK_FALSE, then all pipelines to be bound with a given zero-attachment subpass must have the same value for VkPipelineMultisampleStateCreateInfo::rasterizationSamples.

Valid Usage
  • attachmentCount must be equal to the attachment count specified in renderPass

  • If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, and attachmentCount is not 0, pAttachments must be a valid pointer to an array of attachmentCount valid VkImageView handles

  • If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of pAttachments that is used as a color attachment or resolve attachment by renderPass must have been created with a usage value including VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT

  • If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of pAttachments that is used as a depth/stencil attachment by renderPass must have been created with a usage value including VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of pAttachments that is used as a depth/stencil resolve attachment by renderPass must have been created with a usage value including VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of pAttachments that is used as an input attachment by renderPass must have been created with a usage value including VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

  • Each element of pAttachments that is used as a fragment density map attachment by renderPass must not have been created with a flags value including VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT.

  • If renderPass has a fragment density map attachment and non-subsample image feature is not enabled, each element of pAttachments must have been created with a flags value including VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT unless that element is the fragment density map attachment.

  • If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of pAttachments must have been created with a VkFormat value that matches the VkFormat specified by the corresponding VkAttachmentDescription in renderPass

  • If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of pAttachments must have been created with a samples value that matches the samples value specified by the corresponding VkAttachmentDescription in renderPass

  • If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of pAttachments must have dimensions at least as large as the corresponding framebuffer dimension except for any element that is referenced by fragmentDensityMapAttachment

  • If renderPass was specified with non-zero view masks, each element of pAttachments that is not referenced by fragmentDensityMapAttachment must have a layerCount greater than the index of the most significant bit set in any of those view masks

  • If renderPass was specified with non-zero view masks, each element of pAttachments that is referenced by fragmentDensityMapAttachment must have a layerCount equal to 1 or greater than the index of the most significant bit set in any of those view masks

  • If renderPass was not specified with non-zero view masks, each element of pAttachments that is referenced by fragmentDensityMapAttachment must have a layerCount equal to 1

  • If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, an element of pAttachments that is referenced by fragmentDensityMapAttachment must have a width at least as large as \(\lceil{\frac{width}{maxFragmentDensityTexelSize_{width}}}\rceil\)

  • If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, an element of pAttachments that is referenced by fragmentDensityMapAttachment must have a height at least as large as \(\lceil{\frac{height}{maxFragmentDensityTexelSize_{height}}}\rceil\)

  • If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of pAttachments must only specify a single mip level

  • If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of pAttachments must have been created with the identity swizzle

  • width must be greater than 0.

  • width must be less than or equal to VkPhysicalDeviceLimits::maxFramebufferWidth

  • height must be greater than 0.

  • height must be less than or equal to VkPhysicalDeviceLimits::maxFramebufferHeight

  • layers must be greater than 0.

  • layers must be less than or equal to VkPhysicalDeviceLimits::maxFramebufferLayers

  • If renderPass was specified with non-zero view masks, layers must be 1

  • If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, each element of pAttachments that is a 2D or 2D array image view taken from a 3D image must not be a depth/stencil format

  • If flags does not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, and attachmentCount is not 0, pAttachments must be a valid pointer to an array of attachmentCount valid VkImageView handles

  • If the imageless framebuffer feature is not enabled, flags must not include VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR

  • If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, the pNext chain must include an instance of VkFramebufferAttachmentsCreateInfoKHR

  • If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, the attachmentImageInfoCount member of an instance of VkFramebufferAttachmentsCreateInfoKHR in the pNext chain must be equal to either zero or attachmentCount

  • If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, the width member of any element of the pAttachmentImageInfos member of an instance of VkFramebufferAttachmentsCreateInfoKHR in the pNext chain must be greater than or equal to width, except for any element that is referenced by VkRenderPassFragmentDensityMapCreateInfoEXT::fragmentDensityMapAttachment in renderPass

  • If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, the height member of any element of the pAttachmentImageInfos member of an instance of VkFramebufferAttachmentsCreateInfoKHR in the pNext chain must be greater than or equal to height, except for any element that is referenced by VkRenderPassFragmentDensityMapCreateInfoEXT::fragmentDensityMapAttachment in renderPass

  • If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, the width member of any element of the pAttachmentImageInfos member of an instance of VkFramebufferAttachmentsCreateInfoKHR in the pNext chain that is referenced by VkRenderPassFragmentDensityMapCreateInfoEXT::fragmentDensityMapAttachment in renderPass must be greater than or equal to \(\lceil{\frac{width}{maxFragmentDensityTexelSize_{width}}}\rceil\)

  • If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, the height member of any element of the pAttachmentImageInfos member of an instance of VkFramebufferAttachmentsCreateInfoKHR in the pNext chain that is referenced by VkRenderPassFragmentDensityMapCreateInfoEXT::fragmentDensityMapAttachment in renderPass must be greater than or equal to \(\lceil{\frac{height}{maxFragmentDensityTexelSize_{height}}}\rceil\)

  • If multiview is enabled for renderPass, and flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, the layerCount member of any element of the pAttachmentImageInfos member of an instance of VkFramebufferAttachmentsCreateInfoKHR in the pNext chain must be greater than the maximum bit index set in the view mask in the subpasses in which it is used in renderPass

  • If multiview is not enabled for renderPass, and flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, the layerCount member of any element of the pAttachmentImageInfos member of an instance of VkFramebufferAttachmentsCreateInfoKHR in the pNext chain must be greater than or equal to layers

  • If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, the usage member of any element of the pAttachmentImageInfos member of an instance of VkFramebufferAttachmentsCreateInfoKHR in the pNext chain that refers to an attachment used as a color attachment or resolve attachment by renderPass must include VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT

  • If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, the usage member of any element of the pAttachmentImageInfos member of an instance of VkFramebufferAttachmentsCreateInfoKHR in the pNext chain that refers to an attachment used as a depth/stencil attachment by renderPass must include VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, the usage member of any element of the pAttachmentImageInfos member of an instance of VkFramebufferAttachmentsCreateInfoKHR in the pNext chain that refers to an attachment used as a depth/stencil resolve attachment by renderPass must include VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT

  • If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, the usage member of any element of the pAttachmentImageInfos member of an instance of VkFramebufferAttachmentsCreateInfoKHR in the pNext chain that refers to an attachment used as an input attachment by renderPass must include VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT

  • If flags includes VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT_KHR, at least one element of the pViewFormats member of any element of the pAttachmentImageInfos member of an instance of VkFramebufferAttachmentsCreateInfoKHR in the pNext chain must be equal to the corresponding value of VkAttachmentDescription::format used to create renderPass

Valid Usage (Implicit)
  • sType must be VK_STRUCTURE_TYPE_FRAMEBUFFER_CREATE_INFO

  • pNext must be NULL or a pointer to a valid instance of VkFramebufferAttachmentsCreateInfoKHR

  • flags must be a valid combination of VkFramebufferCreateFlagBits values

  • renderPass must be a valid VkRenderPass handle

  • Both of renderPass, and the elements of pAttachments that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same VkDevice

See Also

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