VkFramebufferCreateInfo(3)

# VkFramebufferCreateInfo(3) Manual Page

## Name

VkFramebufferCreateInfo - Structure specifying parameters of a newly created framebuffer

Loading… please wait.

## C Specification

The `VkFramebufferCreateInfo` structure is defined as:

    // Provided by VK_VERSION_1_0
    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 a structure extending this 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`, 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, either because it has no attachment references or because all of them are `VK_ATTACHMENT_UNUSED`. This kind of subpass can 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 the 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`, 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`, 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`, 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`, 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`, 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`, 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`, 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`, 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`, an element of `pAttachments` that is referenced by `fragmentDensityMapAttachment` must have a width at least as large as ⌈max F r a g ment D ensit y T exe l S i z e w idth​w idth​⌉

- If `flags` does not include `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, an element of `pAttachments` that is referenced by `fragmentDensityMapAttachment` must have a height at least as large as ⌈max F r a g ment D ensit y T exe l S i z e hei g ht​hei g ht​⌉

- If `flags` does not include `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, each element of `pAttachments` must only specify a single mip level

- If `flags` does not include `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, 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`, 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 the imageless framebuffer feature is not enabled, `flags` must not include `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`

- If `flags` includes `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, the `pNext` chain must include a VkFramebufferAttachmentsCreateInfo structure

- If `flags` includes `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, the `attachmentImageInfoCount` member of a VkFramebufferAttachmentsCreateInfo structure included in the `pNext` chain must be equal to either zero or `attachmentCount`

- If `flags` includes `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, the `width` member of any element of the `pAttachmentImageInfos` member of a VkFramebufferAttachmentsCreateInfo structure included 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`, the `height` member of any element of the `pAttachmentImageInfos` member of a VkFramebufferAttachmentsCreateInfo structure included 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`, the `width` member of any element of the `pAttachmentImageInfos` member of a VkFramebufferAttachmentsCreateInfo structure included in the `pNext` chain that is referenced by VkRenderPassFragmentDensityMapCreateInfoEXT::`fragmentDensityMapAttachment` in `renderPass` must be greater than or equal to ⌈max F r a g ment D ensit y T exe l S i z e w idth​w idth​⌉

- If `flags` includes `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, the `height` member of any element of the `pAttachmentImageInfos` member of a VkFramebufferAttachmentsCreateInfo structure included in the `pNext` chain that is referenced by VkRenderPassFragmentDensityMapCreateInfoEXT::`fragmentDensityMapAttachment` in `renderPass` must be greater than or equal to ⌈max F r a g ment D ensit y T exe l S i z e hei g ht​hei g ht​⌉

- If multiview is enabled for `renderPass`, and `flags` includes `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, the `layerCount` member of any element of the `pAttachmentImageInfos` member of a VkFramebufferAttachmentsCreateInfo structure included 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`, the `layerCount` member of any element of the `pAttachmentImageInfos` member of a VkFramebufferAttachmentsCreateInfo structure included in the `pNext` chain must be greater than or equal to `layers`

- If `flags` includes `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, the `usage` member of any element of the `pAttachmentImageInfos` member of a VkFramebufferAttachmentsCreateInfo structure included 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`, the `usage` member of any element of the `pAttachmentImageInfos` member of a VkFramebufferAttachmentsCreateInfo structure included 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`, the `usage` member of any element of the `pAttachmentImageInfos` member of a VkFramebufferAttachmentsCreateInfo structure included 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`, the `usage` member of any element of the `pAttachmentImageInfos` member of a VkFramebufferAttachmentsCreateInfo structure included 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`, at least one element of the `pViewFormats` member of any element of the `pAttachmentImageInfos` member of a VkFramebufferAttachmentsCreateInfo structure included in the `pNext` chain must be equal to the corresponding value of VkAttachmentDescription::`format` used to create `renderPass`

- If `flags` does not include `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, each element of `pAttachments` must have been created with VkImageViewCreateInfo::`viewType` not equal to `VK_IMAGE_VIEW_TYPE_3D`

Valid Usage (Implicit)

- `sType` must be `VK_STRUCTURE_TYPE_FRAMEBUFFER_CREATE_INFO`

- `pNext` must be `NULL` or a pointer to a valid instance of VkFramebufferAttachmentsCreateInfo

- The `sType` value of each struct in the `pNext` chain must be unique

- `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

VkFramebufferCreateFlags, VkImageView, VkRenderPass, VkStructureType, vkCreateFramebuffer

## 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-2020 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0