[−][src]Module vulkano::framebuffer

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

AttachmentDescription	Describes an attachment that will be used in a render pass.
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.
PassDependencyDescription	Describes a dependency between two passes of a render pass.
PassDescription	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.
SubpassContents	Describes what a subpass in a command buffer will contain.

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.