Core Functions

The library exposes several global functions for controlling the global graph state encapsulated inside the library, listed below. The graph is always singular and global by design. This allows for the most effective optimization of memory and other resources due to all information being visible and available to the backend.

However, for separating different logical parts of the global graph, e.g. for different viewports (editor and game preview) all daBfg entities (nodes, resources, automatic resolutions, etc) are namespaced. A node might have the name “/foo/bar/node”, but you never actually use this name to refer to a node, as we don’t want to be parsing strings. Instead, wrapper objects describing a particular namespace are used.

Hence, the code that wants to register various objects inside the graph, like nodes and resolutions, must use the dabfg::NameSpace class to do so, although aliases for calling methods of this class on the global namespace dabfg::root() are available.

group DabfgCore

Core dabfg functions that everything else is accessed through.

Defines

DABFG_PP_NODE_SRC: A macro that expands to the current source location. Should always be provided to dabfg::register_node as the source_location parameter.

Functions

NameSpace root()

Creates a namespace object for the root frame graph namespace.

Returns:: The object representing the root namespace.

void set_multiplexing_extents(multiplexing::Extents extents)

Sets the multiplexing extents for the following frames.

May safely be called every frame, only triggers a recompilation when the values actually change

bool run_nodes()

Executes the frame graph, possibly recompiling it.

Return false if run is not possible (d3d device was lost for example)

void startup(): Initializes the daBfg backend.

void shutdown(): Frees resources held by the daBfg backend.

void invalidate_history()

Invalidates history.

When making changes to the graph history is generally preserved calling this function makes this preservation invalid and the history resources will be recreated.

void update_external_state(ExternalState state): Sets various global state that is external to daBfg.

void mark_external_resource_for_validation(const D3dResource *resource)

Marks an external resource to be validated for illegal access within nodes. Note that daBfg-managed resources are always automatically validated for illegal access through sneaky global variables, but external are often used for gradual migration to FG, at which point they are indeed illegally accessed through global state and that is intended.

Parameters:: resource – The name of the resource to be validated.

struct ExternalState

Describes various global state that can influence the execution of the frame graph but is not managed by daBfg.

Public Members

bool wireframeModeEnabled = false: Enables wireframe debug mode for nodes that allow it.

bool vrsEnabled = false: Enables variable rate shading for all nodes that allow it using the per-node settings specified inside VrsRequirements.

class NameSpace

A type representing some namespace in the frame graph.

Public Functions

NameSpace 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:: An object representing the child namespace.

template<class F> inline NodeHandle registerNode(const char *name, const char *source_location, F &&declaration_callback) const

Either registers a new node inside the frame graph, or re-registers an already existing one.

Parameters:

name – The name that uniquely identifies the node in the current name space. If the function is called twice with the same node name and name space, the second call will overwrite the node resulting from the previous one.
source_location – Should always be the DABFG_PP_NODE_SRC macro
declaration_callback – Should be a callback taking a Registry instance by value and returning an execution callback, which in turn may accept a dabfg::multiplexing::Index object (or may accept nothing). Basically, a function with signature Registry -> (Index -> ()). Note: the declaration and execution callbacks might be called an arbitrary number of times, but only while the resulting node is registered.

Returns:

A handle that represents the lifetime of the new node. The node will be unregistered when the handle is destroyed. Note that it is safe to call this function even without destroying all previous handles up to a couple hundred of times. The intended use case is doing classField = register_node(...) at arbitrary times, without passing these handles anywhere.

template<class T> void setResolution(const char *type_name, T value)

Updates an auto-resolution of a particular type. Note that this causes a complete resource rescheduling, invalidating all history. It also resets dynamic resolution.

Template Parameters:

T – point type, either IPoint2 or IPoint3.

Parameters:

type_name – The name of the auto-res type, looked up in this namespace.
value – The new resolution value.

template<class T> void setDynamicResolution(const char *type_name, T value)

Updates an auto-resolution of a particular type without causing a resource rescheduling, hence preserving history.

Note

This is only available on platforms that support heaps.

Template Parameters:

P – — point type, either IPoint2 or IPoint3.

Parameters:

type_name – The name of the auto-res type, looked up in this namespace.
value – The new dynamic resolution value. Must be smaller than the initial resolution for this type.

void fillSlot(NamedSlot slot, NameSpace res_name_space, const char *res_name)

Sets a value to a named slot. Named slots are basically links that allow for an indirection when looking up a resource name. As an example, volumetric fog is an intrusive feature that requires a bunch of different rendering nodes to read some kind of a downsampled depth resource for tracing the fog, but this depth might be different depending on the current settings. In this situation, it makes sense to introduce a fog_depth slot and fill it in with different resources, allowing one to avoid settings-dependent ifs in node declarations.

Parameters:

slot – Name of the slot, looked up in this namespace.
res_name_space – Name space to look up res_name in.
res_name – Name of the resource to fill this slot with, looked up in res_name_space.

void updateExternallyConsumedResourceSet(eastl::span<const char*const> res_names)

Sets the set of resources which are considered to be somehow externally consumed and hence will never be optimized (pruned) out.

Parameters:: res_names – A list of resource names to assign, looked up in this namespace.

inline void updateExternallyConsumedResourceSet(std::initializer_list<const char*> res_names)

Sets the set of resources which are considered to be somehow externally consumed and hence will never be optimized (pruned) out.

Parameters:: res_names – A list of resource names to assign, looked up in this namespace.

void markResourceExternallyConsumed(const char *res_name)

Marks a single resource as being externally consumed. See dabfg::updateExternallyConsumedResourceSet(eastl::span<const char *const> res_names)

Parameters:: res_name – Name of the resource to mark, looked up in this namespace.

void unmarkResourceExternallyConsumed(const char *res_name)

Unmarks a single resource as being externally consumed. See dabfg::updateExternallyConsumedResourceSet(eastl::span<const char *const> res_names)

Parameters:: res_name – Name of the resource to unmark, looked up in this namespace.

group DabfgCoreAliases

Compatibility aliases for access to the root name space.

Functions

template<class F> NodeHandle register_node(const char *name, const char *source_location, F &&declaration_callback): Alias for dabfg::root().registerNode, see NameSpace::registerNode.

template<class T> inline void set_resolution(const char *typeName, T value): Alias for dabfg::root().setResolution, see NameSpace::setResolution.

template<class T> inline void set_dynamic_resolution(const char *typeName, T value): Alias for dabfg::root().setDynamicResolution, see NameSpace::setDynamicResolution.

inline void fill_slot(NamedSlot slot, const char *res_name): Alias for dabfg::root().fillSlot(slot, dabfg::root(), res_name), see NameSpace::fillSlot.

inline void update_externally_consumed_resource_set(eastl::span<const char*const> res_names): Alias for dabfg::root().updateExternallyConsumedResourceSet, see NameSpace::updateExternallyConsumedResourceSet(eastl::span<const char *const> res_names)

inline void update_externally_consumed_resource_set(std::initializer_list<const char*> res_names)

inline void mark_resource_externally_consumed(const char *res_name): Alias for dabfg::root().markResourceExternallyConsumed, see NameSpace::markResourceExternallyConsumed.

inline void unmark_resource_externally_consumed(const char *res_name): Alias for dabfg::root().unmarkResourceExternallyConsumed, see NameSpace::unmarkResourceExternallyConsumed.