Declaring Node

The basic syntax for creating a new node is as follows:

auto handle = daframegraph::register_node("node_name", DAFG_PP_NODE_SRC,
  [](daframegraph::Registry registry)
  {
    // use registry's methods to declare what your node does
    return []()
      {
        // dispatch GPU commands
      };
  });

The outer lambda is referred to as the declaration callback and is executed rarely, in most cases even once. The declaration callback returns another lambda, referred to as the execution callback, which can be executed once or several times per frame depending on the current multiplexing settings. See Dispatching Work in Nodes at Runtime for further information on runtime behavior. Below is a comprehensive documentation of dabfg::Registry and the related request builder objects. These must be used inside the declaration callback for specifying the following data:

What resources your node is going to operate on,

What it is going to do with them,

What bindings it requires for executing it’s work (shader resources, render targets, etc)

What global state the node requires (e.g. shader blocks)

Additional metadata (multiplexing mode, priority, explicit dependencies, etc)

class Registry : private dafg::NameSpaceRequest 

The main builder object for describing at declaration time what your node intends to do at runtime.

Resource requesting methods

Every one of these returns a request object that must be used to specify further options for the request. See docs for the relevant request objects for details.

Note

All methods present here look up the resource in the current node’s namespace, i.e. registry.currNameSpace().

Note

We explicitly prohibit creating resources in any namespace but the current node’s one.

VirtualResourceCreationSemiRequest create(const char *name, History history)

Creates a new resource at node execution time. The resource will be provided by FG before the node starts executing.

Parameters:

name – A unique name identifying this resource within the current node’s namespace.
history – Specifies the way in which history should be handled for this texture. A history for a virtual resource is a physical resource that contains the data this virtual resource had at the end of the previous frame. See dafg::History for details.

template<class F> inline VirtualTextureRequest<NewRwRequestPolicy> registerTexture(const char *name, F &&texture_provider_callback)

Creates a new texture at node execution time, which will not be FG-provided, but acquired from the callback before the node starts executing and stored somewhere outside. Note that history is not supported for external resources.

Parameters:

name – A unique name identifying this resource within the current node’s namespace.
texture_provider_callback – A callback that maps a multiplexing index to a ManagedTexView. It might be called an arbitrary number of times, but only while the current node is registered.

VirtualTextureRequest<NewRwRequestPolicy> registerBackBuffer(const char *name)

Marks this node as the back buffer provider and creates a virtual dafg resource that corresponds to it.

The back buffer is not a real resource in dagor, but rather a special value that will be replaced with the actual swapchain image when it’s acquired on the driver thread. This makes the back buffer a special case everywhere, it is not possible to read from it, nor is it possible to UAV-write to it. In daFG, we only to render to it, and only with a single attachment at that, so no MRT and no depth-stencil even.

Note

This is a hot discussion topic and might change in the future.

Parameters:: name – a unique name identifying the back buffer as a resource within the current node’s namespace.

template<class F> inline VirtualBufferRequest<NewRwRequestPolicy> registerBuffer(const char *name, F &&buffer_provider_callback)

Creates a new buffer at node execution time, which will not be FG-provided, but acquired from the callback before the node starts executing and stored somewhere outside. Note that history is not supported for external resources.

Parameters:

name – A unique name identifying this resource within the current node’s namespace.
buffer_provider_callback – A callback that maps a multiplexing index to a ManagedBufferView. It might be called an arbitrary number of times, but only while the current node is registered.

VirtualResourceSemiRequest<NewHistRequestPolicy> historyFor(const char *name) const

Reads the history of an existing resource at node execution time.

Parameters:: name – The name of the resource the history of which to read.

VirtualResourceSemiRequest<NewRwRequestPolicy> modify(const char *name) const

Modifies an existing resource at node execution time. Modifications always happen after creation and before all reads.

Parameters:: name – The name of the resource to modify.

VirtualResourceSemiRequest<NewRwRequestPolicy> modify(NamedSlot slot_name) const

Modifies an existing resource at node execution time, but indirectly, through a “slot”, which must be specified with dafg::fill_slot. Modifications always happen after creation and before all reads.

Parameters:: slot_name – The name of the slot to be used for this modification.

VirtualResourceSemiRequest<NewRoRequestPolicy> read(const char *name) const

Reads an existing resource at node execution time. Reads always happen after all modifications and before the renaming.

Parameters:: name – The name of the resource to read.

VirtualResourceSemiRequest<NewRoRequestPolicy> read(NamedSlot slot_name) const

Reads an existing resource at node execution time, but indirectly, through a “slot”, which must be specified with dafg::fill_slot. Reads always happen after all modifications and before the renaming.

Parameters:: slot_name – The name of the slot to be used for this read.

VirtualResourceSemiRequest<NewRwRequestPolicy> rename(const char *from, const char *to, History history) const

Modifies and renames an existing resource at node execution time. Renaming always happens last among all operations on a resource. The renamed version is considered to be a new virtual resource.

Note

Parameters from and to are looked up in different namespaces when calling this function on an arbitrary NameSpaceRequest object! Current node’s namespace is used for creating to, while from is looked up in the current request object’s namespace!

Parameters:

from – Old resource name. Note that this resource may not have history enabled, as renaming it “consumes” it on the current frame, so it is not possible to read it on the next one. It will be looked up relative to this namespace.
to – New resource name, created inside the current node’s namespace!
history – Whether the new resource needs history enabled, see create for details about history.

Convenience aliases

inline VirtualTextureRequest<TexCreateRequestPolicy> createTexture2d(const char *name, History history, Texture2dCreateInfo info): Alias. See create function for details.

template<class T> inline VirtualBlobRequest<T, NonTexCreateRequestPolicy> createBlob(const char *name, History history): Alias. See create function for details.

template<class T> inline VirtualBlobRequest<T, NewRwRequestPolicy> modifyBlob(const char *name) const: Alias. See modify function for details.

inline VirtualTextureRequest<NewRwRequestPolicy> modifyTexture(const char *name) const: Alias. See modify function for details.

inline VirtualTextureRequest<NewRwRequestPolicy> modifyTexture(NamedSlot slot_name) const: Alias. See modify function for details.

template<class T> inline VirtualBlobRequest<T, NewRoRequestPolicy> readBlob(const char *name) const: Alias. See read functions for details.

template<class T> inline VirtualBlobRequest<T, NewHistRequestPolicy> readBlobHistory(const char *name) const: Alias. See historyFor function for details.

inline VirtualTextureRequest<NewRoRequestPolicy> readTexture(const char *name) const: Alias. See read functions for details.

inline VirtualTextureRequest<NewRoRequestPolicy> readTexture(NamedSlot slot_name) const: Alias. See read functions for details.

inline VirtualTextureRequest<NewHistRequestPolicy> readTextureHistory(const char *name) const: Alias. See historyFor function for details.

template<class T> inline VirtualBlobRequest<T, NewRwRequestPolicy> renameBlob(const char *from, const char *to, History history) const: Alias. See rename function for details.

inline VirtualTextureRequest<NewRwRequestPolicy> renameTexture(const char *from, const char *to, History history) const: Alias. See rename function for details.

Public Functions

Registry allowAsyncPipelines(): Allows async pipeline compilation Graphics pipelines will be async compiled with draw call skip when pipeline is not yet ready.

Registry orderMeBefore(const char *name)

Orders the current node before a certain node. This means that the node name will only start executing after the current node has finished.

Note

Ordering with nodes from different name spaces is not supported.

Parameters:: name – The name of the node to order before, looked up in the current namespace.

Registry orderMeBefore(std::initializer_list<const char*> names)

Alias for calling orderMeBefore(const char *name) several times.

Parameters:: names – List of names of the nodes to order before.

Registry orderMeAfter(const char *name)

Orders the current node after a certain node. This means that the current node will only start executing after node name has finished.

Note

Ordering with nodes from different name spaces is not supported.

Parameters:: name – The name of the node to order after, looked up in the current namespace.

Registry orderMeAfter(std::initializer_list<const char*> names)

Alias for calling orderMeAfter(const char *name) several times.

Parameters:: names – List of names of the nodes to order after.

Registry setPriority(priority_t prio)

Sets a priority for this node that will be used to order parallel nodes. Should only be used for optimizations.

Parameters:: prio – The priority to set.

Registry multiplex(multiplexing::Mode mode)

Choses multiplexing mode for this node. Default is multiplexing over all axes (i.e. normal world rendering).

Parameters:: mode – The multiplexing mode to set.

Registry executionHas(SideEffects side_effect)

Sets the side effect of the node that will control how the framegraph handles execution.

Parameters:: side_effect – The side effect type to set.

StateRequest requestState()

Requests a certain global state for the execution time of this node.

Returns:: A builder object for specifying concrete states.

VirtualPassRequest requestRenderPass()

Requests that this node is going to be drawing stuff, which is always done inside a (possibly implicit) render pass. The returned object allows fine-tuning the render pass.

Returns:: A builder object for specifying attachments and other details of the render pass.

DrawRequest<detail::DrawRequestPolicy::Default, false> draw(const char *shader_name, dafg::DrawPrimitive primitive)

Requests a node to execute draw with shader.

Parameters:

shader_name – The name of the shader to be used for drawing.
primitive – The primitive type to be drawn.

Returns:

A builder object for specifying the draw parameters.

DrawRequest<detail::DrawRequestPolicy::Default, true> drawIndexed(const char *shader_name, dafg::DrawPrimitive primitive)

Requests a node to execute indexed draw with shader.

Parameters:

shader_name – The name of the shader to be used for drawing.
primitive – The primitive type to be drawn.

Returns:

A builder object for specifying the indexed draw parameters.

DispatchComputeThreadsRequest dispatchThreads(const char *shader_name)

Requests a node to execute dispatch compute threads with shader.

Parameters:: shader_name – The name of the shader to be used for dispatch.
Returns:: A builder object for specifying the dispatch parameters.

DispatchComputeGroupsRequest dispatchGroups(const char *shader_name)

Requests a node to dispatch compute thread groups with shader.

Parameters:: shader_name – The name of the shader to be used for dispatch.
Returns:: A builder object for specifying the dispatch parameters.

DispatchComputeIndirectRequest dispatchIndirect(const char *shader_name, const char *buffer)

Requests a node to dispatch compute indirect with shader.

Parameters:

shader_name – The name of the shader to be used for dispatch.
buffer – The name of the buffer to be used for indirect dispatch.

Returns:

A builder object for specifying the dispatch parameters.

DispatchMeshThreadsRequest dispatchMeshThreads(const char *shader_name)

Requests a node to dispatch mesh threads with shader.

Parameters:: shader_name – The name of the shader to be used for dispatch.
Returns:: A builder object for specifying the dispatch parameters.

DispatchMeshGroupsRequest dispatchMeshGroups(const char *shader_name)

Requests a node to dispatch mesh thread groups with shader.

Parameters:: shader_name – The name of the shader to be used for dispatch.
Returns:: A builder object for specifying the dispatch parameters.

DispatchMeshIndirectRequest dispatchMeshIndirect(const char *shader_name, const char *buffer)

Requests a node to dispatch mesh indirect with shader.

Parameters:

shader_name – The name of the shader to be used for dispatch.
buffer – The name of the buffer to be used for indirect dispatch.

Returns:

A builder object for specifying the dispatch parameters.

inline NameSpaceRequest currNameSpace()

Returns a request object for this node’s name space that can be used to get sub-namespace request objects or request resources.

Returns:: NameSpaceRequest object representing the current name space.

NameSpaceRequest root() const

Returns a request object for the root name space which can be used to access global resources.

Returns:: NameSpaceRequest object representing the root name space.

template<int D> AutoResolutionRequest<D> getResolution(const char *type_name, float multiplier = 1.f) const

Get a request object for the 2D resolution of a particular type inside of this namespace, which can then be used to create textures or be resolved into an actual number at execution time. The resulting resolution will be the product of what was set with NameSpace::setResolution with the multiplier.

Template Parameters:

D – Dimensionality of the resolution.

Parameters:

type_name – Auto resolution type name.
multiplier – A multiplier for the resolution type.

Returns:

AutoResolutionRequest Object representing the auto resolution type.

class NameSpaceRequest

An object representing a name space within the node declaration callback. It can be used to request objects from the current namespace or its sub-namespaces.

Subclassed by dafg::Registry

Resource requesting methods

Every one of these returns a request object that must be used to specify further options for the request. See docs for the relevant request objects for details.

Note

All methods present here look up the resource in this namespace.

VirtualResourceSemiRequest<NewRoRequestPolicy> read(const char *name) const

Reads an existing resource at node execution time. Reads always happen after all modifications and before the renaming.

Parameters:: name – The name of the resource to read.

VirtualResourceSemiRequest<NewRoRequestPolicy> read(NamedSlot slot_name) const

Reads an existing resource at node execution time, but indirectly, through a “slot”, which must be specified with dafg::fill_slot. Reads always happen after all modifications and before the renaming.

Parameters:: slot_name – The name of the slot to be used for this read.

VirtualResourceSemiRequest<NewHistRequestPolicy> historyFor(const char *name) const

Reads the history of an existing resource at node execution time.

Parameters:: name – The name of the resource the history of which to read.

VirtualResourceSemiRequest<NewRwRequestPolicy> modify(const char *name) const

Modifies an existing resource at node execution time. Modifications always happen after creation and before all reads.

Parameters:: name – The name of the resource to modify.

VirtualResourceSemiRequest<NewRwRequestPolicy> modify(NamedSlot slot_name) const

Modifies an existing resource at node execution time, but indirectly, through a “slot”, which must be specified with dafg::fill_slot. Modifications always happen after creation and before all reads.

Parameters:: slot_name – The name of the slot to be used for this modification.

VirtualResourceSemiRequest<NewRwRequestPolicy> rename(const char *from, const char *to, History history) const

Modifies and renames an existing resource at node execution time. Renaming always happens last among all operations on a resource. The renamed version is considered to be a new virtual resource.

Note

Parameters from and to are looked up in different namespaces when calling this function on an arbitrary NameSpaceRequest object! Current node’s namespace is used for creating to, while from is looked up in the current request object’s namespace!

Parameters:

from – Old resource name. Note that this resource may not have history enabled, as renaming it “consumes” it on the current frame, so it is not possible to read it on the next one. It will be looked up relative to this namespace.
to – New resource name, created inside the current node’s namespace!
history – Whether the new resource needs history enabled, see create for details about history.

Convenience aliases

inline VirtualTextureRequest<NewRoRequestPolicy> readTexture(const char *name) const: Alias. See read functions for details.

inline VirtualTextureRequest<NewRoRequestPolicy> readTexture(NamedSlot slot_name) const: Alias. See read functions for details.

inline VirtualTextureRequest<NewHistRequestPolicy> readTextureHistory(const char *name) const: Alias. See historyFor function for details.

inline VirtualTextureRequest<NewRwRequestPolicy> modifyTexture(const char *name) const: Alias. See modify function for details.

inline VirtualTextureRequest<NewRwRequestPolicy> modifyTexture(NamedSlot slot_name) const: Alias. See modify function for details.

inline VirtualTextureRequest<NewRwRequestPolicy> renameTexture(const char *from, const char *to, History history) const: Alias. See rename function for details.

template<class T> inline VirtualBlobRequest<T, NewRoRequestPolicy> readBlob(const char *name) const: Alias. See read functions for details.

template<class T> inline VirtualBlobRequest<T, NewHistRequestPolicy> readBlobHistory(const char *name) const: Alias. See historyFor function for details.

template<class T> inline VirtualBlobRequest<T, NewRwRequestPolicy> modifyBlob(const char *name) const: Alias. See modify function for details.

template<class T> inline VirtualBlobRequest<T, NewRwRequestPolicy> renameBlob(const char *from, const char *to, History history) const: Alias. See rename function for details.

Public Functions

NameSpaceRequest operator/(const char *child_name) const

Creates a namespace object for a sub-namespace of this one.

Parameters:: child_name – Name of the sub-namespace.
Returns:: NameSpace Object representing the child namespace.

template<int D> AutoResolutionRequest<D> getResolution(const char *type_name, float multiplier = 1.f) const

Get a request object for the 2D resolution of a particular type inside of this namespace, which can then be used to create textures or be resolved into an actual number at execution time. The resulting resolution will be the product of what was set with NameSpace::setResolution with the multiplier.

Template Parameters:

D – Dimensionality of the resolution.

Parameters:

type_name – Auto resolution type name.
multiplier – A multiplier for the resolution type.

Returns:

AutoResolutionRequest Object representing the auto resolution type.

template<int D> class AutoResolutionRequest

This class represents a daFG-managed automatic resolution type for a texture. If this resolution is specified for a texture, the actual texture’s resolution at runtime will be the dynamic resolution scaled by the multiplier, but the consumed memory will always be equal to the static resolution times the multiplier. See NameSpace::setResolution and NameSpace::setDynamicResolution. Note that objects of this type MAY be captured into the execution callback and used to access the actual resolution on a particular frame, but the resolution should NEVER be accessed in the declaration callback, as the value will be undefined.

Template Parameters:: D – — dimensionality of the resolution, either 2 or 3.

Public Functions

IPoint<D> get() const

Returns the current dynamic resolution for this auto-res type.

Warning

Should only be used for setting the d3d viewport/scissor, NEVER create textures with this resolution, as it might be changing every single frame!!! Also never call this outside of the execution callback for the same reason!

Returns:: The current dynamic resolution for this type.

namespace multiplexing

Multiplexing allows a single run_nodes call to result in several consequent executions of frameGraph with some nodes being run only once. As an example, when rendering for VR, shadows need to be rendered only once, not for every eye/viewport, while most scene geometry should be rendered for every viewport/eye.

Enums

enum class Mode : uint32_t

Describes the dimensions along which a node shall be multiplexed.

Values:

enumerator None: Run once, ignore multiplexing (i.e. global setup)

enumerator SuperSampling: Run the node for every super-sample.

enumerator SubSampling: Run the node for every sub-sample.

enumerator Viewport: Run the node once for every viewport.

enumerator CameraInCamera: Run the node for every sub area in the main camera.

enumerator FullMultiplex: Default: everything is multiplexed (normal scene rendering nodes)

Functions

inline Mode operator|(Mode a, Mode b): Bitwise OR operator for combining several modes.

inline Mode operator&(Mode a, Mode b): Bitwise AND operator to check if mode set.

struct Extents

#include <multiplexing.h>

A struct describing the amount of multiplexing that occurs over every dimension.

The application is free to interpret these dimensions however it pleases, but the intended interpretation is

superSamples — used when rendering the entire scene multiple times to achieve a higher resolution result than the user’s VRAM would allow otherwise, which is useful for screenshots and cinematics;
subSamples — used for rendering the entire scene multiple times and then blending the results to achieve SSAA without spending any additional VRAM required;
viewports — used for VR/AR.

Public Functions

bool operator==(const Extents &other) const = default: Equality comparison operator.

Public Members

uint32_t superSamples = {1}: Number of super-samples.

uint32_t subSamples = {1}: Number of sub-samples.

uint32_t viewports = {1}: Number of viewports.

uint32_t subCameras = {1}: Number of main camera areas.

struct Index

#include <multiplexing.h>

Identifies a concrete iteration of multiplexing.

Can be accessed from an execution callback by simply adding an argument of this type to it. It is then possible to achieve different behavior for different eyes or sub/super samples.

Public Functions

bool operator==(const Index &other) const = default: Equality comparison operator.

Public Members

uint32_t superSample = {0}: Index of the super-sample.

uint32_t subSample = {0}: Index of the sub-sample.

uint32_t viewport = {0}: Index of the viewport.

uint32_t subCamera = {0}: Index of the camera in camera area.

class StateRequest

Represents a request for a certain global state to be set during the node’s execution.

Public Functions

StateRequest setFrameBlock(const char *block) &&

Requests for a block to be set to FRAME layer Values of frame block shader vars are supposed to change once per frame.

Parameters:: block – The name of the block to set. Must be present in the shader dump.

StateRequest setSceneBlock(const char *block) &&

Requests for a block to be set to SCENE layer. Values of scene block shader vars are supposed to change when the rendering mode changes. Examples of rendering modes are; depth pre-pass, shadow pass, color pass, voxelization pass, etc.

Parameters:: block – The name of the block to set. Must be present in the shader dump.

StateRequest setObjectBlock(const char *block) &&

Requests for a block to be set to OBJECT layer. Per-object blocks are evil and should be avoided at all costs. They imply a draw-call-per-object model, which has historically proven itself antagonistic to performance.

Parameters:: block – The name of the block to set. Must be present in the shader dump.

StateRequest allowWireframe() &&: Requests for the driver wireframe mode to be enabled for this node when the user turns it on for debug purposes.

StateRequest maxVrs() &&: Enable variable rate shading with as little rendering as possible.

Warning

Incompatible with using a VRS rate texture.

StateRequest enableOverride(shaders::OverrideState override) &&

Requests a shader pipeline state override to be active while this node is executing.

Parameters:: override – The override to use.

namespace dafg

Variables

constexpr int AUTO_MIP_COUNT = 0: Special value for Texture2dCreateInfo::mipLevels. daFG will automatically generate all mip levels for such a texture.

struct BufferCreateInfo

#include <resourceCreation.h>

An effort to create a less error-prone buffers API is currently ongoing, this structure exposes the to-be-deprecated \inlinerst :cpp:func:d3d::create_sbuffer \endrst buffer creation mechanism. You are on your own trying to figure out how to use this.

Public Members

uint32_t elementSize: Size of a single element in bytes.

uint32_t elementCount: Amount of elements in this buffer.

uint32_t flags: Use SBCF_ flags here.

uint32_t format: This is for so-called T-buffers, which are basically 1d textures masquerading as buffers. If you are not targeting DX10, don’t use these

struct NamedSlot

#include <resourceCreation.h>

Named slots do not represent any resource by default and must be explicitly set to point to a different resource through dafg::fill_slot.

Public Functions

inline explicit NamedSlot(const char *slot_name): Enables using regular parentheses for construction.

Public Members

const char *name: String name for this slot, must not match any other resource’s name.

struct Texture2dCreateInfo

#include <resourceCreation.h>

Specifies the creation parameters for a 2D texture.

Note

Resources will ALWAYS contain garbage right after they’ve been created. Use virtual passes to clear them if you need to, or write explicit clears.

Public Members

uint32_t creationFlags = 0: Use TEXCF_ prefixed flags.

eastl::variant<IPoint2, AutoResolutionRequest<2>> resolution: Resolution for this texture. May either be hard-coded or automatic, see AutoResolutionRequest.

uint32_t mipLevels = 1: Use 0 for automatic mip levels.

struct Texture3dCreateInfo

#include <resourceCreation.h>

Specifies the creation parameters for a 3D volumetric texture.

Public Members

uint32_t creationFlags = 0: Use TEXCF_ prefixed flags.

eastl::variant<IPoint3, AutoResolutionRequest<3>> resolution: Resolution for this texture. May either be hard-coded or automatic, see AutoResolutionRequest.

uint32_t mipLevels = 1: Use 0 for automatic mip levels.

class VirtualResourceCreationSemiRequest

A builder object for an incomplete resource creation request: we want to create something, but don’t know what yet. Note that all methods of this class return a new request object which should be used for further specification. Never re-use objects of this type for several requests.

Buffer methods

The buffer naming convention repeats the one in the d3d driver interface, see functions in namespace \inlinerst :cpp:type:d3d::buffers \endrst

Public Functions

inline VirtualResourceRequest<BaseTexture, RRP::None> texture(const Texture2dCreateInfo &info) &&

Specifies the request to be a 2D texture creation one.

Parameters:: info – The 2D texture creation info.

inline VirtualResourceRequest<BaseTexture, RRP::None> texture(const Texture3dCreateInfo &info) &&

Specifies the request to be a 3D texture creation one.

Parameters:: info – The 3D texture creation info.

inline VirtualResourceRequest<Sbuffer, RRP::HasClearValue> buffer(const BufferCreateInfo &info) &&

Specifies the request to be a buffer creation one. Note that this is a legacy method that is error-prone and hard to use correctly. Avoid this in favor of one of the methods below if possible.

Parameters:: info – The buffer creation info.

template<class T> inline VirtualResourceRequest<T, RRP::HasClearValue> blob() &&

Specifies the request to be a blob creation one.

Template Parameters:: T – The type of the CPU data blob

template<class T> inline VirtualResourceRequest<T, RRP::HasClearValue> blob(const T defaultValue) &&

Specifies the request to be a blob creation one.

Template Parameters:: T – The type of the CPU data blob
Parameters:: defaultValue – The default value to initialize the blob with.

template<detail::ResourceRequestPolicy policy> class VirtualResourceSemiRequest

A builder object for an incomplete resource creation request: we want to read, modify or rename something, but don’t know what yet. Note that all methods of this class return a new request object which should be used for further specification. Never re-use objects of this type for several requests.

Template Parameters:: policy – Static data about this request’s structure used for erroring out at compile time if this class is used incorrectly.

Public Functions

inline VirtualResourceRequest<BaseTexture, policy> texture() &&: Specifies this to be a texture request.

inline VirtualResourceRequest<Sbuffer, policy> buffer() &&: Specifies this to be a buffer request.

template<class T> inline VirtualResourceRequest<T, policy> blob() &&

Specifies this to be a blob request.

Template Parameters:: T – The type of the blob to be requested.

template<class Res, detail::ResourceRequestPolicy policy> class VirtualResourceRequest

Request for a virtual resource known to FG. Should be used to further configure the properties of the request.

The intended usage is

auto myTexHandle = registry.readTexture("my_tex")
  .optional()
  ...
  .handle();

Hence methods are only rvalue-callable. Don’t try to get smart with these request classes. Don’t cache them, don’t pass them around a bunch of functions, KISS.

Template Parameters:

Res – The C++ type representing this resource. BaseTex/Sbuffer for GPU resources, any C++ type for CPU resources.
policy – Static data about this request’s structure used for erroring out at compile time if this class is used incorrectly.

Public Functions

inline VirtualResourceRequest<Res, flipPolicy(RRP::Optional)> optional() &&: Makes this request optional. The node will not get disabled if the resource is missing, the handle will return an empty value.

inline VirtualResourceRequest<Res, flipPolicy(RRP::HasUsageType)> bindToShaderVar(const char *shader_var_name = nullptr) &&

Requests for this resource to be bound to a shader variable with the specified name. The usage stage MUST have been set beforehand and MUST include all shader stages that this shader var will be accessed from within this node.

Parameters:: shader_var_name – The name of the shader variable to bind. If not specified, the name of the resource will be used.

template<auto projector, class = void> inline VirtualResourceRequest<Res, policy> bindToShaderVar(const char *shader_var_name = nullptr) &&

Requests for a sub-object of a blob to be bound to a shader variable with the specified name.

Template Parameters:: projector – A function to extract the value to bind from the blob. Can be a pointer-to-member, i.e. &BlobType::field or a (pure) function pointer.
Parameters:: shader_var_name – The name of the shader variable to bind. If not specified, the name of the resource will be used.

inline VirtualResourceRequest<Res, policy> bindAsView() &&: Requests for a matrix-like blob to be bound as the current view matrix.

template<auto projector, class = void> inline VirtualResourceRequest<Res, policy> bindAsView() &&

Requests for a matrix-like sub-object of a blob to be bound as the current view matrix.

Template Parameters:: projector – A function to extract the value to bind from the blob. Can be a pointer-to-member, i.e. &BlobType::field or a (pure) function pointer.

inline VirtualResourceRequest<Res, policy> bindAsProj() &&: Requests for a matrix-like blob to be bound as the current projection matrix.

template<auto projector, class = void> inline VirtualResourceRequest<Res, policy> bindAsProj() &&

Requests for a matrix-like sub-object of a blob to be bound as the current projection matrix.

Template Parameters:: projector – A function to extract the value to bind from the blob. Can be a pointer-to-member, i.e. &BlobType::field or a (pure) function pointer.

inline VirtualResourceRequest<Res, policy> bindAsVertexBuffer(uint32_t stream, uint32_t stride) &&

Requests for a buffer to be bound for the specified vertex stream.

Parameters:

stream – The vertex stream index to bind the buffer to.
stride – The stride of the buffer.

inline VirtualResourceRequest<Res, policy> bindAsIndexBuffer() &&: Requests for a buffer to be bound as current index buffer.

inline VirtualResourceRequest<Res, flipPolicy(RRP::HasUsageStage)> atStage(Stage stage) &&: Must be used when the resource is manually accessed through the handle or bound to a shader var to specify what shader stage this resource will be used at.

inline VirtualResourceRequest<Res, flipPolicy(RRP::HasUsageType)> useAs(Usage type) &&: Must be used when the resource is manually accessed through the handle to specify how exactly the resource will be used.

inline HandleType handle() &&: Returns a handle that can be used to access the physical resource underlying this virtual one during execution time. Note that the physical resource will change throughout executions and should never be cached by reference. See dafg::VirtualResourceHandle for further details.

inline VirtualResourceRequest<Res, flipPolicy(RRP::HasClearValue)> clear(const ResourceClearValue &clear_value) &&

Clears the resource with the specified clear value on activation (or render pass begin if its applicable).

This is only applicable to textures.

Parameters:: clear_value – The value to clear the resource with.

inline VirtualResourceRequest<Res, flipPolicy(RRP::HasClearValue)> clear(const char *blob_name) &&

Clears the resource with the specified clear value on activation (or render pass begin if its applicable).

This is only applicable to textures.

Parameters:: blob_name – The name of the blob that contains the clear value.

template<auto projector> inline VirtualResourceRequest<Res, flipPolicy(RRP::HasClearValue)> clear(const char *blob_name) &&

Clears the resource with the specified clear value on activation (or render pass begin if its applicable).

This is only applicable to textures.

Parameters:: blob_name – The name of the blob that contains the clear value.

inline VirtualResourceRequest<Res, flipPolicy(RRP::HasClearValue)> discard() &&

Activates the resource request, but does not clear it.

This is only applicable to textures. Default behaviour is discard, so we need this method only to cast the request to have the same type as modify request.

class VirtualPassRequest

Requests this node to be inside a render pass with specified attachments. It is a virtual pass, as FG will merge these virtual passes into a single physical pass where possible. This class must be used to further specify the details of a virtual pass.

Attachments is a term that includes both render targets, depth targets and some other mobile-specific stuff. Note that methods that specify attachments take a special helper class, detail::VirtualAttachmentRequest. It is not necessary to understand how this class works, just call these methods either with a resource request or a string resource name, or even a {request/name, mip, layer} initializer list for tricky cases like cube maps.

Public Types

using RwVirtualAttachmentRequest = detail::VirtualAttachmentRequest<RRP::Readonly | RRP::Optional | RRP::History | RRP::HasUsageStage | RRP::HasUsageType, RRP::None>: Resolve and RW depth cannot be readonly, optional or history requests. Usage should not have been specified yet.

using ColorRwVirtualAttachmentRequest = detail::VirtualAttachmentRequest<RRP::Readonly | RRP::History | RRP::HasUsageStage | RRP::HasUsageType, RRP::None>: Color requests may be optional, but cannot be readonly or history. Usage is specified later.

using DepthRoVirtualAttachmentRequest = detail::VirtualAttachmentRequest<RRP::Optional | RRP::HasUsageStage | RRP::HasUsageType, RRP::None>: RO depth is not allowed to be optional, as it doesn’t seem useful (may be changed later). Usage will be determined by us.

using DepthRoAndSvBindVirtualAttachmentRequest = detail::VirtualAttachmentRequest<RRP::Optional | RRP::HasUsageType, RRP::None>: For RO depth that is also sampled through a shader var (SV), we also prohibit optional requests and while the usage type is determined by us (simultaneous depth+sampling), stage should be provided separately.

using RoVirtualAttachmentRequest = detail::VirtualAttachmentRequest<RRP::History | RRP::HasUsageStage | RRP::HasUsageType, RRP::None>: Input attachments are not allowed to be history, as renderpasses cannot span frame boundaries. Usage is determined by us.

using RwVirtualClearRequest = detail::VirtualAttachmentRequest<RRP::Readonly | RRP::History | RRP::HasUsageStage | RRP::HasUsageType, RRP::None>: Clear requests can be optional, but cannot be readonly or history. Usage should not have been specified yet.

Public Functions

VirtualPassRequest color(std::initializer_list<ColorRwVirtualAttachmentRequest> attachments) &&

Specifies color attachments for this virtual pass, which will be bound in the order specified here. A color attachment is a synonym for “render target”. Call this with a braced list of either request objects or resource names, and optionally mip/layer numbers grouped with an object or name using braces. E.g. {{"cube", 0, 1}, "normals", prevFrameMotionRequest}

Parameters:: attachments – A list of attachments to use as color ones. This method should be usable without understanding the internals of detail::VirtualAttachmentRequest most of the time.

VirtualPassRequest depthRw(RwVirtualAttachmentRequest attachment) &&

Specifies the depth attachment for this virtual pass and enables depth write. The specified resource request MUST be a modify request. Call this with either a resource request object or an object name. You can also optionally specify mip/layer using braces: {"cube", 0, 1}.

Parameters:: attachment – The attachment to use as depth. This method should be usable without understanding the internals of detail::VirtualAttachmentRequest most of the time.

VirtualPassRequest depthRoAndBindToShaderVars(DepthRoAndSvBindVirtualAttachmentRequest attachment, std::initializer_list<const char*> shader_var_names) &&

Specifies the depth attachment for this virtual pass, disables depth write and binds it to several shader variable for sampling inside a shader.

This can only be called with a resource request object and not a string name, due to requiring stage to be specified as all stages where these shader vars will be used.

Note however that the resource request may be either read or modify, which will determine the ordering for this node.

This is is only multi-usage API in daFG, an exception to the one usage per node guideline.

Warning: switching between RO and RW depth requires decompression and recompression on AMD hardware, which is expensive.

Parameters:

attachment – The resource request for the depth attachment.
shader_var_names – A list of shader var names to be bound.

VirtualPassRequest resolve(RwVirtualAttachmentRequest from, RwVirtualAttachmentRequest to) &&

Specifies that the attachment from is a MSAA texture that should be resolved to the texture to at the end of this pass.

Note

The resource from must have been previously requested as either a color or a depth attachment.

Parameters:

from – The attachment to resolve.
to – The resource to resolve it to.

VirtualPassRequest vrsRate(RoVirtualAttachmentRequest attachment) &&

Specifies the VRS rate texture attachment for this virtual pass.

The specified resource request MUST be a read. See \inlinerst :cpp:func:d3d::set_variable_rate_shading_texture \endrst for further details. Call this with either a resource request object or an object name. You can also optionally specify mip/layer using braces: {"cube", 0, 1}.

Warning

Currently, no driver supports mips/layers for VRS textures.

Parameters:: attachment – The attachment to use as a VRS rate. This method should be usable without understanding the internals of detail::VirtualAttachmentRequest most of the time.