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 a VkStructureType value identifying 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

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`. In all such cases, `rasterizationSamples` must be a bit value that is set in VkPhysicalDeviceLimits::`framebufferNoAttachmentsSampleCounts`.

Valid Usage

- VUID-VkFramebufferCreateInfo-attachmentCount-00876
  `attachmentCount` must be equal to the attachment count specified in `renderPass`

- VUID-VkFramebufferCreateInfo-flags-02778
  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

- VUID-VkFramebufferCreateInfo-pAttachments-00877
  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`

- VUID-VkFramebufferCreateInfo-pAttachments-02633
  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`

- VUID-VkFramebufferCreateInfo-pAttachments-02634
  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`

- VUID-VkFramebufferCreateInfo-pAttachments-00879
  If `renderpass` is not VK_NULL_HANDLE, `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`

- VUID-VkFramebufferCreateInfo-pAttachments-02552
  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`

- VUID-VkFramebufferCreateInfo-renderPass-02553
  If `renderPass` has a fragment density map attachment and the `fragmentDensityMapNonSubsampledImages` 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

- VUID-VkFramebufferCreateInfo-renderPass-06502
  If `renderPass` was created with fragment density map offsets other than (0,0), each element of `pAttachments` must have been created with a `flags` value including `VK_IMAGE_CREATE_FRAGMENT_DENSITY_MAP_OFFSET_BIT_QCOM`

- VUID-VkFramebufferCreateInfo-pAttachments-00880
  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`

- VUID-VkFramebufferCreateInfo-pAttachments-00881
  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`

- VUID-VkFramebufferCreateInfo-flags-04533
  If `flags` does not include `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, each element of `pAttachments` that is used as an input, color, resolve, or depth/stencil attachment by `renderPass` must have been created with a VkImageCreateInfo::`extent.width` greater than or equal to `width`

- VUID-VkFramebufferCreateInfo-flags-04534
  If `flags` does not include `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, each element of `pAttachments` that is used as an input, color, resolve, or depth/stencil attachment by `renderPass` must have been created with a VkImageCreateInfo::`extent.height` greater than or equal to `height`

- VUID-VkFramebufferCreateInfo-flags-04535
  If `flags` does not include `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, each element of `pAttachments` that is used as an input, color, resolve, or depth/stencil attachment by `renderPass` must have been created with a VkImageViewCreateInfo::`subresourceRange.layerCount` greater than or equal to `layers`

- VUID-VkFramebufferCreateInfo-renderPass-04536
  If `renderPass` was specified with non-zero view masks, each element of `pAttachments` that is used as an input, color, resolve, or depth/stencil attachment by `renderPass` must have a `layerCount` greater than the index of the most significant bit set in any of those view masks

- VUID-VkFramebufferCreateInfo-renderPass-02746
  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

- VUID-VkFramebufferCreateInfo-renderPass-02747
  If `renderPass` was specified with all view masks equal to zero, each element of `pAttachments` that is referenced by `fragmentDensityMapAttachment` must have a `layerCount` equal to `1`

- VUID-VkFramebufferCreateInfo-pAttachments-02555
  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​⌉

- VUID-VkFramebufferCreateInfo-pAttachments-02556
  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​⌉

- VUID-VkFramebufferCreateInfo-flags-04537
  If `flags` does not include `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, and `renderPass` was specified with non-zero view masks, each element of `pAttachments` that is used as a fragment shading rate attachment by `renderPass` must have a `layerCount` that is either `1`, or greater than the index of the most significant bit set in any of those view masks

- VUID-VkFramebufferCreateInfo-flags-04538
  If `flags` does not include `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, and `renderPass` was not specified with non-zero view masks, each element of `pAttachments` that is used as a fragment shading rate attachment by `renderPass` must have a `layerCount` that is either `1`, or greater than `layers`

- VUID-VkFramebufferCreateInfo-renderPass-08921
  If `renderPass` was specified with non-zero view masks, each element of `pAttachments` that is used as a fragment shading rate attachment must have a `layerCount` equal to `1` or greater than the index of the most significant bit set in any of those view masks

- VUID-VkFramebufferCreateInfo-flags-04539
  If `flags` does not include `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, an element of `pAttachments` that is used as a fragment shading rate attachment must have a width at least as large as ⌈`width` / `texelWidth`⌉, where `texelWidth` is the largest value of `shadingRateAttachmentTexelSize.width` in a VkFragmentShadingRateAttachmentInfoKHR which references that attachment

- VUID-VkFramebufferCreateInfo-flags-04540
  If `flags` does not include `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, an element of `pAttachments` that is used as a fragment shading rate attachment must have a height at least as large as ⌈`height` / `texelHeight`⌉, where `texelHeight` is the largest value of `shadingRateAttachmentTexelSize.height` in a VkFragmentShadingRateAttachmentInfoKHR which references that attachment

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

- VUID-VkFramebufferCreateInfo-pAttachments-00884
  If `flags` does not include `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, each element of `pAttachments` must have been created with the identity swizzle

- VUID-VkFramebufferCreateInfo-width-00885
  `width` must be greater than `0`

- VUID-VkFramebufferCreateInfo-width-00886
  `width` must be less than or equal to `maxFramebufferWidth`

- VUID-VkFramebufferCreateInfo-height-00887
  `height` must be greater than `0`

- VUID-VkFramebufferCreateInfo-height-00888
  `height` must be less than or equal to `maxFramebufferHeight`

- VUID-VkFramebufferCreateInfo-layers-00889
  `layers` must be greater than `0`

- VUID-VkFramebufferCreateInfo-layers-00890
  `layers` must be less than or equal to `maxFramebufferLayers`

- VUID-VkFramebufferCreateInfo-renderPass-02531
  If `renderPass` was specified with non-zero view masks, `layers` must be `1`

- VUID-VkFramebufferCreateInfo-pAttachments-00891
  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

- VUID-VkFramebufferCreateInfo-flags-03189
  If the `imagelessFramebuffer` feature is not enabled, `flags` must not include `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`

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

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

- VUID-VkFramebufferCreateInfo-flags-04541
  If `flags` includes `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, the `width` member of any element of the `pAttachmentImageInfos` member of a VkFramebufferAttachmentsCreateInfo structure in the `pNext` chain that is used as an input, color, resolve or depth/stencil attachment in `renderPass` must be greater than or equal to `width`

- VUID-VkFramebufferCreateInfo-flags-04542
  If `flags` includes `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, the `height` member of any element of the `pAttachmentImageInfos` member of a VkFramebufferAttachmentsCreateInfo structure in the `pNext` chain that is used as an input, color, resolve or depth/stencil attachment in `renderPass` must be greater than or equal to `height`

- VUID-VkFramebufferCreateInfo-flags-03196
  If `flags` includes `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, the `width` member of any element of the `pAttachmentImageInfos` member of a VkFramebufferAttachmentsCreateInfo structure 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​⌉

- VUID-VkFramebufferCreateInfo-flags-03197
  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​⌉

- VUID-VkFramebufferCreateInfo-flags-04543
  If `flags` includes `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, the `width` member of any element of the `pAttachmentImageInfos` member of a VkFramebufferAttachmentsCreateInfo structure in the `pNext` chain that is used as a fragment shading rate attachment must be greater than or equal to ⌈`width` / `texelWidth`⌉, where `texelWidth` is the largest value of `shadingRateAttachmentTexelSize.width` in a VkFragmentShadingRateAttachmentInfoKHR which references that attachment

- VUID-VkFramebufferCreateInfo-flags-04544
  If `flags` includes `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, the `height` member of any element of the `pAttachmentImageInfos` member of a VkFramebufferAttachmentsCreateInfo structure in the `pNext` chain that is used as a fragment shading rate attachment must be greater than or equal to ⌈`height` / `texelHeight`⌉, where `texelHeight` is the largest value of `shadingRateAttachmentTexelSize.height` in a VkFragmentShadingRateAttachmentInfoKHR which references that attachment

- VUID-VkFramebufferCreateInfo-flags-04545
  If `flags` includes `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, the `layerCount` member of any element of the `pAttachmentImageInfos` member of a VkFramebufferAttachmentsCreateInfo structure in the `pNext` chain that is used as a fragment shading rate attachment must be either `1`, or greater than or equal to `layers`

- VUID-VkFramebufferCreateInfo-flags-04587
  If `flags` includes `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT` and `renderPass` was specified with non-zero view masks, each element of `pAttachments` that is used as a fragment shading rate attachment by `renderPass` must have a `layerCount` that is either `1`, or greater than the index of the most significant bit set in any of those view masks

- VUID-VkFramebufferCreateInfo-renderPass-03198
  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 used as an input, color, resolve, or depth/stencil attachment in `renderPass` must be greater than the maximum bit index set in the view mask in the subpasses in which it is used in `renderPass`

- VUID-VkFramebufferCreateInfo-renderPass-04546
  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 used as an input, color, resolve, or depth/stencil attachment in `renderPass` must be greater than or equal to `layers`

- VUID-VkFramebufferCreateInfo-flags-03201
  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`

- VUID-VkFramebufferCreateInfo-flags-03202
  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`

- VUID-VkFramebufferCreateInfo-flags-03203
  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`

- VUID-VkFramebufferCreateInfo-flags-03204
  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`

- VUID-VkFramebufferCreateInfo-flags-03205
  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`

- VUID-VkFramebufferCreateInfo-flags-04113
  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`

- VUID-VkFramebufferCreateInfo-flags-04548
  If `flags` does not include `VK_FRAMEBUFFER_CREATE_IMAGELESS_BIT`, each element of `pAttachments` that is used as a fragment shading rate attachment by `renderPass` must have been created with a `usage` value including `VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR`

- VUID-VkFramebufferCreateInfo-flags-04549
  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 fragment shading rate attachment by `renderPass` must include `VK_IMAGE_USAGE_FRAGMENT_SHADING_RATE_ATTACHMENT_BIT_KHR`

- VUID-VkFramebufferCreateInfo-samples-06881
  If multisampled-render-to-single-sampled is enabled for any subpass, all color, depth/stencil and input attachments used in that subpass which have `VkAttachmentDescription`::`samples` or `VkAttachmentDescription2`::`samples` equal to `VK_SAMPLE_COUNT_1_BIT` must have been created with `VK_IMAGE_CREATE_MULTISAMPLED_RENDER_TO_SINGLE_SAMPLED_BIT_EXT` in their VkImageCreateInfo::`flags`

- VUID-VkFramebufferCreateInfo-samples-07009
  If multisampled-render-to-single-sampled is enabled for any subpass, all color, depth/stencil and input attachments used in that subpass which have `VkAttachmentDescription`::`samples` or `VkAttachmentDescription2`::`samples` equal to `VK_SAMPLE_COUNT_1_BIT` must have a format that supports the sample count specified in VkMultisampledRenderToSingleSampledInfoEXT::`rasterizationSamples`

Valid Usage (Implicit)

- VUID-VkFramebufferCreateInfo-sType-sType
  `sType` must be `VK_STRUCTURE_TYPE_FRAMEBUFFER_CREATE_INFO`

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

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

- VUID-VkFramebufferCreateInfo-flags-parameter
  `flags` must be a valid combination of VkFramebufferCreateFlagBits values

- VUID-VkFramebufferCreateInfo-renderPass-parameter
  `renderPass` must be a valid VkRenderPass handle

- VUID-VkFramebufferCreateInfo-commonparent
  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

VK_VERSION_1_0, 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 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0