Declaring a Node

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

auto handle = dabfg::register_node("node_name", DABFG_PP_NODE_SRC,
  [](dabfg::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 dabfg::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 dabfg::History for details.

template<class F>
inline VirtualTextureRequest<NewRwRequestPolicy> registerTexture2d(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 dabfg 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 daBfg, 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 dabfg::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 dabfg::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<NewRwRequestPolicy> createTexture2d(const char *name, History history, Texture2dCreateInfo info)

Alias. See create function for details.

template<class T>
inline VirtualBlobRequest<T, NewRwRequestPolicy> 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.

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 dabfg::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 dabfg::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 dabfg::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 daBfg-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 – &#8212; 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 FullMultiplex

Default: everything is multiplexed (normal scene rendering nodes)

Functions

inline Mode operator|(Mode a, Mode b)

Bitwise OR operator for combining several modes.

struct Extents

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 &#8212; 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 &#8212; used for rendering the entire scene multiple times and then blending the results to achieve SSAA without spending any additional VRAM required;

  • viewports &#8212; used for VR/AR.

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.

struct Index

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

inline bool operator==(const Index &other)

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.

Warning

doxygenstruct: Cannot find class “dabfg::VrsRequirements” in doxygen xml output for project “daBFG” from directory: _build/breathe/doxygen/daBFG/xml

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 vrs(VrsSettings vrs) &&

Configures VRS settings for this node.

The default settings correspond to no VRS.

Note

VRS will only work if it is supported and enabled through dabfg::update_external_state.

Parameters:

vrs – The VRS settings to use.

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 dabfg

Variables

constexpr int AUTO_MIP_COUNT = 0

Special value for Texture2dCreateInfo::mipLevels. daBfg will automatically generate all mip levels for such a texture.

struct NamedSlot

Named slots do not represent any resource by default and must be explicitly set to point to a different resource through dabfg::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

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

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.

struct BufferCreateInfo

An effort to create a less error-prone buffers API is currently ongoing, this structure exposes the to-be-deprecated d3d::create_sbuffer() 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

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 d3d::buffers

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::None> 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::None> 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::None> 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 BFG. 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, 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 dabfg::VirtualResourceHandle for further details.

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.

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 daBfg, 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 clear(RwVirtualAttachmentRequest attachment, ResourceClearValue color) &&

Specifies that the attachment should be cleared with color at the beginning of this pass.

Warning

This causes a low-level pass break, so should be used sparingly.

Parameters:

  • attachment – The attachment to clear.

  • color – The color to clear it with.

inline VirtualPassRequest clear(RwVirtualAttachmentRequest attachment, const char *color_blob) &&

Specifies that the attachment should be cleared with the color contained in the color_blob at the beginning of this pass.

The requested blob’s type is inferred from the projector’s argument type.

Warning

This causes a low-level pass break, so should be used sparingly.

Parameters:

  • attachment – The attachment to clear.

  • color – The name of the blob to grab the color from.

template<auto projector>
inline VirtualPassRequest clear(RwVirtualAttachmentRequest attachment, const char *color_blob) &&

Specifies that the attachment should be cleared with the color contained in the color_blob at the beginning of this pass.

The requested blob’s type is inferred from the projector’s argument type.

Warning

This causes a low-level pass break, so should be used sparingly.

Template Parameters:

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

Parameters:

  • attachment – The attachment to clear.

  • color – The name of the blob to grab the color from.

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 d3d::set_variable_rate_shading_texture() 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.