Rendergraph

struct Resource
struct RenderGraph : public std::enable_shared_from_this<RenderGraph>

Public Functions

void add_pass(Pass pass, source_location location = source_location::current())

Add a pass to the rendergraph.

Parameters:

pass – the Pass to add to the RenderGraph

void add_alias(Name new_name, Name old_name)

Add an alias for a resource.

Parameters:

  • new_name – Additional name to refer to the resource

  • old_name – Old name used to refere to the resource

void diverge_image(Name whole_name, Subrange::Image subrange, Name subrange_name)

Diverge image. subrange is available as subrange_name afterwards.

void converge_image_explicit(std::span<Name> pre_diverge, Name post_diverge)

Reconverge image from named parts. Prevents diverged use moving before pre_diverge or after post_diverge.

void resolve_resource_into(Name resolved_name_src, Name resolved_name_dst, Name ms_name)

Add a resolve operation from the image resource ms_name that consumes resolved_name_src and produces resolved_name_dst This is only supported for color images.

Parameters:

  • resolved_name_src – Image resource name consumed (single-sampled)

  • resolved_name_dst – Image resource name created (single-sampled)

  • ms_name – Image resource to resolve from (multisampled)

void clear_image(Name image_name_in, Name image_name_out, Clear clear_value)

Clear image attachment.

Parameters:

  • image_name_in – Name of the image resource to clear

  • image_name_out – Name of the cleared image resource

  • clear_value – Value used for the clear

  • subrange – Range of image cleared

void attach_swapchain(Name name, SwapchainRef swp)

Attach a swapchain to the given name.

Parameters:

name – Name of the resource to attach to

void attach_buffer(Name name, Buffer buffer, Access initial = eNone)

Attach a buffer to the given name.

Parameters:

  • name – Name of the resource to attach to

  • buffer – Buffer to attach

  • initial – Access to the resource prior to this rendergraph

void attach_buffer_from_allocator(Name name, Buffer buffer, Allocator allocator, Access initial = eNone)

Attach a buffer to be allocated from the specified allocator.

Parameters:

  • name – Name of the resource to attach to

  • buffer – Buffer to attach

  • allocator – Allocator the Buffer will be allocated from

  • initial – Access to the resource prior to this rendergraph

void attach_image(Name name, ImageAttachment image_attachment, Access initial = eNone)

Attach an image to the given name.

Parameters:

  • name – Name of the resource to attach to

  • image_attachment – ImageAttachment to attach

  • initial – Access to the resource prior to this rendergraph

void attach_image_from_allocator(Name name, ImageAttachment image_attachment, Allocator allocator, Access initial = eNone)

Attach an image to be allocated from the specified allocator.

Parameters:

  • name – Name of the resource to attach to

  • image_attachment – ImageAttachment to attach

  • buffer – Buffer to attach

  • initial – Access to the resource prior to this rendergraph

void attach_and_clear_image(Name name, ImageAttachment image_attachment, Clear clear_value, Access initial = eNone)

Attach an image to the given name.

Parameters:

  • name – Name of the resource to attach to

  • image_attachment – ImageAttachment to attach

  • clear_value – Value used for the clear

  • initial – Access to the resource prior to this rendergraph

void attach_in(Name name, Future future)

Attach a future to the given name.

Parameters:

  • name – Name of the resource to attach to

  • future – Future to be attached into this rendergraph

void attach_in(std::span<Future> futures)

Attach multiple futures - the names are matched to future bound names.

Parameters:

futures – Futures to be attached into this rendergraph

std::vector<Future> split()

Compute all the unconsumed resource names and return them as Futures.

void release(Name name, Access final)

Mark resources to be released from the rendergraph with future access.

Parameters:

  • name – Name of the resource to be released

  • final – Access after the rendergraph

void release_for_present(Name name)

Mark resource to be released from the rendergraph for presentation.

Parameters:

name – Name of the resource to be released

Public Members

Name name

Name of the rendergraph.

struct ExecutableRenderGraph

Futures

vuk Futures allow you to reason about computation of resources that happened in the past, or will happen in the future. In general the limitation of RenderGraphs are that they don’t know the state of the resources produces by previous computation, or the state the resources should be left in for future computation, so these states must be provided manually (this is error-prone). Instead you can encapsulate the computation and its result into a Future, which can then serve as an input to other RenderGraphs.

Futures can be constructed from a RenderGraph and a named Resource that is considered to be the output. A Future can optionally own the RenderGraph - but in all cases a Future must outlive the RenderGraph it references.

You can submit Futures manually, which will compile, execute and submit the RenderGraph it references. In this case when you use this Future as input to another RenderGraph it will wait for the result on the device. If a Future has not yet been submitted, the contained RenderGraph is simply appended as a subgraph (i.e. inlined).

It is also possible to wait for the result to be produced to be available on the host - but this forces a CPU-GPU sync and should be used sparingly.

class Future

Public Functions

Future(std::shared_ptr<RenderGraph> rg, Name output_binding, DomainFlags dst_domain = DomainFlagBits::eDevice)

Create a Future with ownership of a RenderGraph and bind to an output.

Parameters:

  • rg –

  • output_binding –

Future(std::shared_ptr<RenderGraph> rg, QualifiedName output_binding, DomainFlags dst_domain = DomainFlagBits::eDevice)

Create a Future with ownership of a RenderGraph and bind to an output.

Parameters:

  • rg –

  • output_binding –

inline Future(ImageAttachment value)

Create a Future from a value, automatically making the result available on the host.

Parameters:

value –

inline Future(Buffer value)

Create a Future from a value, automatically making the result available on the host.

Parameters:

value –

inline FutureBase::Status &get_status()

Get status of the Future.

inline std::shared_ptr<RenderGraph> get_render_graph()

Get the referenced RenderGraph.

Result<void> submit(Allocator &allocator, Compiler &compiler)

Submit Future for execution.

Result<void> wait(Allocator &allocator, Compiler &compiler)

Wait for Future to complete execution on host.

template<class T>
Result<T> get(Allocator &allocator, Compiler &compiler)

Wait and retrieve the result of the Future on the host.

inline FutureBase *get_control()

Get control block for Future.

Composing render graphs

Futures make easy to compose complex operations and effects out of RenderGraph building blocks, linked by Futures. These building blocks are termed partials, and vuk provides some built-in. Such partials are functions that take a number of Futures as input, and produce a Future as output.

The built-in partials can be found below. Built on these, there are some convenience functions that couple resource allocation with initial data (create_XXX()).

namespace vuk

Functions

inline Future host_data_to_buffer(Allocator &allocator, DomainFlagBits copy_domain, Buffer dst, const void *src_data, size_t size)

Fill a buffer with host data.

Parameters:

  • allocator – Allocator to use for temporary allocations

  • copy_domain – The domain where the copy should happen (when dst is mapped, the copy happens on host)

  • buffer – Buffer to fill

  • src_data – pointer to source data

  • size – size of source data

template<class T>
Future host_data_to_buffer(Allocator &allocator, DomainFlagBits copy_domain, Buffer dst, std::span<T> data)

Fill a buffer with host data.

Parameters:

  • allocator – Allocator to use for temporary allocations

  • copy_domain – The domain where the copy should happen (when dst is mapped, the copy happens on host)

  • dst – Buffer to fill

  • data – source data

inline Future download_buffer(Future buffer_src)

Download a buffer to GPUtoCPU memory.

Parameters:

buffer_src – Buffer to download

inline Future host_data_to_image(Allocator &allocator, DomainFlagBits copy_domain, ImageAttachment image, const void *src_data)

Fill an image with host data.

Parameters:

  • allocator – Allocator to use for temporary allocations

  • copy_domain – The domain where the copy should happen (when dst is mapped, the copy happens on host)

  • image – ImageAttachment to fill

  • src_data – pointer to source data

inline Future transition(Future image, Access dst_access)

Transition image for given access - useful to force certain access across different RenderGraphs linked by Futures.

Parameters:

  • image – input Future of ImageAttachment

  • dst_access – Access to have in the future

inline Future generate_mips(Future image, uint32_t base_mip, uint32_t num_mips)

Generate mips for given ImageAttachment.

Parameters:

  • image – input Future of ImageAttachment

  • base_mip – source mip level

  • num_mips – number of mip levels to generate

template<class T>
std::pair<Unique<Buffer>, Future> create_buffer(Allocator &allocator, vuk::MemoryUsage memory_usage, DomainFlagBits domain, std::span<T> data, size_t alignment = 1)

Allocates & fills a buffer with explicitly managed lifetime.

Parameters:

  • allocator – Allocator to allocate this Buffer from

  • mem_usage – Where to allocate the buffer (host visible buffers will be automatically mapped)

inline std::pair<Texture, Future> create_texture(Allocator &allocator, Format format, Extent3D extent, void *data, bool should_generate_mips, SourceLocationAtFrame loc = VUK_HERE_AND_NOW())

Allocates & fills an image, creates default ImageView for it (legacy)

Parameters:

  • allocator – Allocator to allocate this Texture from

  • format – Format of the image

  • extent – Extent3D of the image

  • data – pointer to data to fill the image with

  • should_generate_mips – if true, all mip levels are generated from the 0th level