Magnum::Vk::RenderPass class new in Git master

#include <Magnum/Vk/RenderPass.h>

Render pass creation

A RenderPassCreateInfo consists of:

• a set of attachments, described by AttachmentDescription instances,
• subpasses operating on those attachments, described by a SubpassDescription using AttachmentReference instances,
• and subpass dependencies, described by SubpassDependency.

A render pass has to have at least one subpass. It's common to have just one subpass, but while the subpass isn't required to operate on any attachments, such case is rather rare. Following is a simple setup for one subpass operating on a color and a combined depth/stencil attachment. Each AttachmentDescription describes a concrete attachment and particular SubpassDescription::setColorAttachments() / setColorAttachments() then reference it by an index.

In addition to a format, each AttachmentDescription has to specify an AttachmentLoadOperation that happens at the render pass begin — whether we want to preserve the contents, clear them or discard — and similarly an AttachmentStoreOperation at the end. Then, the ImageLayout parameters specify what implicit layout transitions (if any) need to happen between start of the render pass and the first subpass, between subpasses and between last subpass and end of the render pass.

The following snippet shows attachment and subpass setup for a single-pass color/depth render. Commonly the image is used in some way after the render pass, in this case it'll get transferred to the host, as indicated by ImageLayout::TransferSource. That will also need an explicit subpass dependency, as explained below.

#include <Magnum/Vk/RenderPassCreateInfo.h>

…

Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{}
    .setAttachments({
        Vk::AttachmentDescription{Vk::PixelFormat::RGBA8Srgb,
            Vk::AttachmentLoadOperation::Clear,
            Vk::AttachmentStoreOperation::Store,
            Vk::ImageLayout::Undefined,
            Vk::ImageLayout::TransferSource},
        Vk::AttachmentDescription{Vk::PixelFormat::Depth24UnormStencil8UI,
            Vk::AttachmentLoadOperation::Clear,
            Vk::AttachmentStoreOperation::DontCare,
            Vk::ImageLayout::Undefined,
            Vk::ImageLayout::DepthStencilAttachment}
    })
    .addSubpass(Vk::SubpassDescription{}
        .setColorAttachments({
            Vk::AttachmentReference{0, Vk::ImageLayout::ColorAttachment}
        })
        .setDepthStencilAttachment(
            Vk::AttachmentReference{1, Vk::ImageLayout::DepthStencilAttachment}
        )
    )

    .setDependencies({
        Vk::SubpassDependency{
            /* An operation external to the render pass depends on the first
               subpass */
            0, Vk::SubpassDependency::External,
            /* where transfer gets executed only after color output is done */
            Vk::PipelineStage::ColorAttachmentOutput,
            Vk::PipelineStage::Transfer,
            /* and color data written are available for the transfer to read */
            Vk::Access::ColorAttachmentWrite,
            Vk::Access::TransferRead}
    })
};

Render pass recording

A render pass recording inside a CommandBuffer is begun with CommandBuffer::beginRenderPass(), to which point Vulkan schedules all implicit layout transitions. Together with a render pass you need to supply a compatible Framebuffer containing actual image views for each attachment and a clear value for each attachment that had AttachmentLoadOperation::Clear specified. After that you can execute CommandBuffer commands that are allowed inside a render pass:

Vk::CommandBuffer cmd = …;
cmd.begin()
   …
   .beginRenderPass(Vk::RenderPassBeginInfo{renderPass, framebuffer}
        .clearColor(0, 0x1f1f1f_srgbf)
        .clearDepthStencil(1, 1.0f, 0))

Advancing to the next subpass (if any) can be done with nextSubpass(), and finally endRenderPass() ends the render pass. As with render pass begin, these make Vulkan schedule implicit layout transitions between subpasses and at render pass end.

   .endRenderPass()
   …
   .end();

Public static functions

static auto wrap(Device& device, VkRenderPass handle, HandleFlags flags = {}) -> RenderPass

Wrap existing Vulkan handle.

Constructors, destructors, conversion operators

RenderPass(Device& device, const RenderPassCreateInfo& info) explicit

Constructor.

RenderPass(NoCreateT) explicit

Construct without creating the render pass.

RenderPass(const RenderPass&) deleted

Copying is not allowed.

RenderPass(RenderPass&& other) noexcept

Move constructor.

~RenderPass()

Destructor.

operator VkRenderPass()

Public functions

auto operator=(const RenderPass&) -> RenderPass& deleted

Copying is not allowed.

auto operator=(RenderPass&& other) -> RenderPass& noexcept

Move assignment.

auto handle() -> VkRenderPass

Underlying VkRenderPass handle.

auto handleFlags() const -> HandleFlags

Handle flags.

auto release() -> VkRenderPass

Release the underlying Vulkan render pass.

Function documentation