Module pass

This module mainly exposes the PassBuilder struct, used for correctly defining passes in a PassGraph.

For documentation on how to use the pass graph, refer to the graph module level documentation. There are a few different types of passes. Each pass must declare its inputs and outputs, and can optionally specify a closure to be executed when the pass is recorded to a command buffer. Additionally, a color can be given to each pass which will show up in debuggers like RenderDoc if the debug-markers feature is enabled.

Example

In this example we will define two passes: One that writes to an offscreen texture, and one that samples from this texture to render it to the screen. This is a very simple dependency, but a very common pattern. The task graph system will ensure access is properly synchronized, and the offscreen image is properly transitioned from its initial layout before execution, to VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, and then to VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL before the final pass.

First, we define some virtual resources.

use phobos::image;
use phobos::prelude::*;

let offscreen = image!("offscreen");
let swapchain = image!("swapchain");

Now we create the offscreen pass. Note that we use PassBuilder::render() to create a render pass. This is a pass that outputs to at least one color or depth attachment by using the graphics pipeline. A pass that was not created through this method cannot define any attachments, this is useful for e.g. compute-only passes.

use phobos::prelude::*;

let offscreen_pass = PassBuilder::render("offscreen")
    // All this does is make the pass show up red in graphics debuggers, if
    // the debug-markers feature is enabled.
    .color([1.0, 0.0, 0.0, 1.0])
    // Add a single color attachment that will be cleared to red.
    .clear_color_attachment(&offscreen, ClearColor::Float([1.0, 0.0, 0.0, 0.0]))?
    .build();

Next we can create the pass that will sample from this pass. To do this, we have to declare that we will sample the virtual resource using PassBuilder::sample_image. Note that this is only necessary for images that are used elsewhere in the frame. Regular textures for rendering do not need to be declared like this.

use phobos::prelude::*;

// This is important. The virtual resource that encodes the output of the offscreen pass is not the same as the one
// we gave it in `color_attachment()`. We have to look up the correct version using `Pass::output()`.
let input_resource = offscreen_pass.output(&offscreen).unwrap();

let sample_pass = PassBuilder::render("sample")
    // Let's color this pass green
    .color([0.0, 1.0, 0.0, 1.0])
    // Clear the swapchain to black.
    .clear_color_attachment(&swapchain, ClearColor::Float([0.0, 0.0, 0.0, 0.0]))?
    // We sample the input resource in the fragment shader.
    .sample_image(&input_resource, PipelineStage::FRAGMENT_SHADER)
    .execute_fn(|mut cmd, local_pool, bindings, _| {
        // Draw a fullscreen quad using our sample pipeline and a descriptor set pointing to the input resource.
        // This assumes we created a pipeline before and a sampler before, and that we bind the proper resources
        // before recording the graph.
        cmd = cmd.bind_graphics_pipeline("fullscreen_sample")?
                 .resolve_and_bind_sampled_image(0, 0, &input_resource, &sampler, &bindings)?
                 .draw(6, 1, 0, 0)?;
        Ok(cmd)
    })
    .build();

Binding physical resources and recording is covered under the graph module documentation.

Structs

ClearDepthStencil

Represents a clear value for Depth/Stencil attachmemts.

EmptyPassExecutor

An empty pass executor that does nothing

Pass

Represents one pass in a GPU task graph. You can obtain one using a PassBuilder.

PassBuilder

Used to create Pass objects correctly.

Enums

ClearColor

Represents a clear color for an attachment. The variant used should match the type of the attachment.

Traits

PassExecutor

Defines a pass executor that can be called when the pass is recorded.

Type Aliases

PassFnResult

The returned value from a pass callback function.