Module vulkano::framebuffer [] [src]

Targets on which your draw commands are executed.

Render passes and framebuffers

There are two concepts in Vulkan:

  • A render pass describes the target which you are going to render to. It is a collection of descriptions of one or more attachments (ie. image that are rendered to), and of one or multiples subpasses. The render pass contains the format and number of samples of each attachment, and the attachments that are attached to each subpass. They are represented in vulkano with the RenderPass object.
  • A framebuffer contains the list of actual images that are attached. It is created from a render pass and has to match its characteristics. They are represented in vulkano with the Framebuffer object.

Render passes are typically created at initialization only (for example during a loading screen) because they can be costly, while framebuffers can be created and destroyed either at initialization or during the frame.

Consequently you can create graphics pipelines from a render pass object alone. A Framebuffer object is only needed when you actually add draw commands to a command buffer.

Render passes

In vulkano a render pass is represented by the RenderPass struct. This struct has a template parameter that contains the description of the render pass. The RenderPassAbstract trait is implemented on all instances of RenderPass<_> and makes it easier to store render passes without having to explicitely write its type.

The template parameter of the RenderPass struct must implement the RenderPassDesc trait. In order to create a render pass, you can create an object that implements this trait, then call the build_render_pass method on it.

use vulkano::framebuffer::EmptySinglePassRenderPassDesc;
use vulkano::framebuffer::RenderPassDesc;

let desc = EmptySinglePassRenderPassDesc;
let render_pass = desc.build_render_pass(device.clone()).unwrap();
// The type of `render_pass` is `RenderPass<EmptySinglePassRenderPassDesc>`.

This example creates a render pass with no attachment and one single subpass that doesn't draw on anything. While it's sometimes useful, most of the time it's not what you want.

The easiest way to create a "real" render pass is to use the single_pass_renderpass! macro.

use vulkano::format::Format;

let render_pass = single_pass_renderpass!(device.clone(),
    attachments: {
        // `foo` is a custom name we give to the first and only attachment.
        foo: {
            load: Clear,
            store: Store,
            format: Format::R8G8B8A8Unorm,
            samples: 1,
        }
    },
    pass: {
        color: [foo],       // Repeat the attachment name here.
        depth_stencil: {}
    }
).unwrap();

See the documentation of the macro for more details. TODO: put link here

Once a RenderPass<_> struct is created, it implements the same render-pass-related traits as its template parameter.

Framebuffers

See the documentation of the Framebuffer struct for information about how to create a framebuffer.

Structs

EmptySinglePassRenderPassDesc

Description of an empty render pass.

Framebuffer

Contains a render pass and the image views that are attached to it.

FramebufferBuilder

Prototype of a framebuffer.

FramebufferSys

Opaque object that represents the internals of a framebuffer.

LayoutAttachmentDescription

Describes an attachment that will be used in a render pass.

LayoutPassDependencyDescription

Describes a dependency between two passes of a render pass.

LayoutPassDescription

Describes one of the passes of a render pass.

RenderPass

Defines the layout of multiple subpasses.

RenderPassDescAttachments

Iterator to the attachments of a RenderPassDesc.

RenderPassDescDependencies

Iterator to the subpass dependencies of a RenderPassDesc.

RenderPassDescSubpasses

Iterator to the subpasses of a RenderPassDesc.

RenderPassSys

Opaque object that represents the render pass' internals.

Subpass

Represents a subpass within a RenderPassAbstract object.

Enums

FramebufferCreationError

Error that can happen when creating a framebuffer object.

IncompatibleRenderPassAttachmentError

Error that can happen when an image is not compatible with a render pass attachment slot.

LoadOp

Describes what the implementation should do with an attachment at the start of the subpass.

RenderPassCreationError

Error that can happen when creating a compute pipeline.

StoreOp

Describes what the implementation should do with an attachment after all the subpasses have completed.

Traits

AttachmentsList

A list of attachments.

FramebufferAbstract

Trait for objects that contain a Vulkan framebuffer object.

RenderPassAbstract

Trait for objects that contain a Vulkan render pass object.

RenderPassCompatible

Trait implemented on render pass objects to check whether they are compatible with another render pass.

RenderPassDesc

Trait for objects that contain the description of a render pass.

RenderPassDescClearValues

Extension trait for RenderPassDesc. Defines which types are allowed as a list of clear values.

RenderPassSubpassInterface

Extension trait for RenderPassDesc that checks whether a subpass of this render pass accepts the output of a fragment shader.

Functions

ensure_image_view_compatible

Checks whether the given image view is allowed to be the nth attachment of the given render pass.