node-builder.hpp File Reference

Go to the source code of this file.

Description

Specialised shorthand notation for building the Render Node network.

During the Builder run, the render nodes network will be constructed by gradually refining the connectivity structure derived from interpreting the »high-level model« from the current Session. At some point, it is essentially clear what data streams must be produced and what media processing functionality from external libraries will be utilised to achieve this goal. This is when the fluent builder notation defined in this header comes into play, allowing to package the fine grained and in part quite confusing details of parameter wiring and invocation preparation into some goal oriented building blocks, that can be combined and directed with greater clarity by the control structure to govern the build process.

Levels of connectivity building

The actual node connectivity is established by a process of gradual refinement, operating over several levels of abstraction. Each of these levels uses its associated builder and descriptor records to collect information, which is then emitted by a terminal invocation to produce the result; the higher levels thereby rely on the lower levels to fill in and elaborate the details.

• Level-1 is the preparation of an actual frame processing operation; the Level-1-builder is in fact the implementation class sitting behind a Render Node's Port. It is called a Turnout and contains a preconfigured »blue print« for the data structure layout used for the invocation; its purpose is to generate the actual data structure on the stack, holding all the necessary buffers and parameters ready for invoking the external library functions. Since the actual data processing is achieved by a pull processing, originating at the top level exit nodes and propagating down towards the data sources, all the data feeds at all levels gradually link together, forming a TurnoutSystem.
• Level-2 generates the actual network of Render Nodes, which in turn will have the Turnout instances for Level-1 embedded into their internal ports. Conceptually, a Port is where data production can be requested, and the processing will then retrieve its prerequisite data from the ports of the Leads, which are the prerequisite nodes situated one level below or one step closer to the source.
• Level-3 establishes the processing steps and data retrieval links between them; at this level, thus the outline of possible processing pathways is established. After spelling out the desired connectivity at a high level, the so called »Level-3 build walk« is triggered by invoking the [terminal builder operation](ProcBuilder::build() on the processing builder corresponding to the topmost node. This build walk will traverse the connectivity graph depth-first, and then start invoking the Level-2 builder operations bottom-up to generate and wire up the corresponding Render Nodes.

Using custom allocators

Since the low-level-Model is a massive data structure comprising thousands of nodes, each with specialised parametrisation for some media handling library, and a lot of cross-linking pointers, it is important to care for efficient usage of memory with good locality. Furthermore, the higher levels of the build process will generate additional temporary data structures, refined gradually until the actual render node network can be emitted. Each builder level can thus be outfitted with a custom allocator — typically an instance of lib::AllocationCluster. Notably the higher levels can be attached to a separate AllocationCluster instance, which will be discarded once the build process is complete, while Level-2 (and below) uses the allocator for the actual target data structure, which has to be retained while the render graph is used; more specifically until a complete segment of the timeline is superseded and has been re-built.

Remarks

syntactically, the custom allocator specification is given after opening a top-level builder, by means of the builder function .withAllocator<ALO> (args...)

Todo:

WIP-WIP-WIP 10/2024 Node-Invocation is reworked from ground up – some parts can not be spelled out completely yet, since we have to build this tightly interlocked system of code moving bottom up, and then filling in further details later working top-down.

See also

steam::engine::NodeFactory

nodewiring.hpp

node-basic-test.cpp

Definition in file node-builder.hpp.

#include "lib/error.hpp"
#include "lib/nocopy.hpp"
#include "steam/engine/weaving-pattern-builder.hpp"
#include "steam/engine/proc-node.hpp"
#include "steam/engine/turnout.hpp"
#include "lib/several-builder.hpp"
#include "lib/format-string.hpp"
#include "lib/index-iter.hpp"
#include "lib/test/test-helper.hpp"
#include <utility>
#include <vector>

Classes
class	LinkBuilder
class	NodeBuilder< POL, DAT >
class	NodeBuilder< POL, DAT >
class	PortBuilder< POL, DAT, WAB >
class	PortBuilderRoot< POL, DAT >
class	PortBuilderRoot< POL, DAT >
class	ProcBuilder
struct	UseHeapAlloc

Typedefs
template<class POL , class I , class E = I>
using	DataBuilder = lib::SeveralBuilder< I, E, POL::template Policy >
	A builder to collect working data. More...

Functions
template<class POL , class D0 , uint siz, class BUILD >
	NodeBuilder (NodeBuilder< POL, D0 > &&, SizMark< siz >, BUILD &&) -> NodeBuilder< POL, PatternData< D0, BUILD, siz >>
	Deduction Guide: help the compiler with deducing follow-up NodeBuilder parameters.
auto	prepareNode (StrView nodeSymbol)
	Entrance point for building actual Render Node Connectivity (Level-2) More...
auto	retrieve (void *streamType)
	Entrance point for defining data flows and processing steps.

Namespaces
	steam
	Steam-Layer implementation namespace root.
	steam::engine
	Lumiera's render engine core and operational control.

---

Class Documentation

steam::engine::anonymous_namespace{node-builder.hpp}::UseHeapAlloc

struct steam::engine::anonymous_namespace{node-builder.hpp}::UseHeapAlloc

Class Members
typedef HeapOwn< I, E >	Policy

Collaboration diagram for UseHeapAlloc: