param-weaving-pattern.hpp File Reference

Construction kit to establish a set of parameters pre-computed prior to invocation of nested nodes. More...

Go to the source code of this file.

Description

Construction kit to establish a set of parameters pre-computed prior to invocation of nested nodes.

This arrangement is also known as »Parameter Agent Node« (while actually it is a Weaving Pattern residing within some Node's Port). The use-case is to provide a set of additional parameter values, beyond what can be derived directly by a parameter-functor based on the absolute-nominal-Time of the invocation. The necessity for such a setup may arise when additional context or external state must be combined with the nominal time into a tuple of data values, which shall then be consumed by several follow-up evaluations further down into a recursive invocation tree for one single render job. The solution provided by the Parameter Agent Node relies on placing those additional data values into a tuple, which is then stored directly in the render invocation stack frame, prior to descending into further recursive Node evaluations. Notably, parameter-functors within the scope of this evaluation tree can then access these additional parameters through the TurnoutSystem of the overall invocation.

Configuration

In order to setup such an evaluation scheme involving a Parameter Agent as top entrance point, and a delegate Node tree below, in a first step, the evaluations for the additional parameter values must be established. This is achieved by defining a Parameter Build Spec, which is a descriptor record with a builder-DSL notation to be assembled step by step. Internally, this ParamBuildSpec embeds a tuple of parameter-functors, one for each new parameter value. Furthermore, since the intended usage scheme calls for a lib::HeteroData »chain block« as storage for the extended parameter values, an anchor type is embedded into the type signature of ParamBuildSpec; this anchor is assumed to be the HeteroData-prefix-chain, where the new data block is assumed to be attached at the end. In the common use case, this prefix will be the default layout of a TurnoutSystem, which internally embeds a lib::HeteroData record, configured to hold some basic parameters, which are present in every render invocation:

• the absolute nominal Time in the timeline
• a process Key

Since this is a well-known, fixed layout, the definition of a ParamBuildSpec can be started from a static convenience function, steam::engine::buildParamSpec(), which yields an (initially empty) ParamBuildSpec, anchored at the default layout of the TurnoutSystem. On this builder term, several «parameter slots» can be added successively, either

• by embedding a fixed (constant) parameter value
• or with a parameter-functor, which works on the basic default TurnoutSystem

Once a ParamBuildSpec is outfitted with all desired functors, it can be used to generate accessor functors — which are the crucial ingredient for actually accessing the extended parameter values from the nested node tree. Please recall that also a regular Render Node Port can embed a parameter-functor, which works on the TurnoutSystem. Usually this param-functor will retrieve the absolute nominal time from there, but in our case here, the purpose of the whole elaborate scheme is that such an parameter-functor embedded into some processing node down in the nested tree can access the extended parameters, which were generated initially by the Param Agent Node at top-level and reside in a storage block somewhere up the call stack, from where they are linked-in temporarily into the TurnoutSystem. Thus, after building the ParamBuildSpec, next some actual Render Nodes have to be built, which include the accessor functors retrieved from the ParamBuildSpec. These are actually static type markers, as they do not actually refer to the ParamBuildSpec, but rather to the «slot number» in the structure (which is encoded into the type signature). Such an accessor functor can be applied to the extended TurnoutSystem, and will retrieve the corresponding extended parameter value from the chain-block linked temporarily into the TurnoutSystem.

Finally, when the nested delegate Node tree is complete, the actual Param Agent Node can be built through a special hook in the NodeBuilder: After opening the nested definition of a port, invoke steam::engine::PortBuilderRoot::computeParam(spec), passing the ParamBuildSpec record (with the actual functor instances embedded!). Furthermore, the link to the delegate Node tree must be added, followed by .completePort(). Optionally, a post-processing functor can be added, which will be invoked after all parameters are generated, but before delegating to the nested Node tree.

As should be clear from context, the so called »Param Agent Node« is actually a special port. Yet in practice, you'd typically set up a top-level node, where each port is configured with a suitable Param Agent setup, and then delegates to the processing chain to produce the content to produce for this port. Internally, this Param Agent setup is a Turnout (thus implementing the Port interface) with a special ParamWeavingPattern. The latter incorporates all the steps necessary to establish this special extended parameter setup

• it first invokes all the parameter-functors in the tuple
• it forms a parameter tuple from the result values
• this parameter-tuple is dropped off into a storage within the current stack frame
• then this storage block (which is a valid HeteroData chain-block), will be linked temporarily with the current TurnoutSystem of the invocation
• next an optional postprocessing-functor will be invoked
• followed by a regular recursive invocation of the delegate tree
• as a last step, the temporary storage block is disconnected from the TurnoutSystem
• and the result buffer of the recursive delegate tree is returned as result.

See also

node-builder.hpp

weaving-pattern-builder.hpp

elaborate demonstration example

Overview of Render Node structures

Warning

WIP as of 12/2024 first complete integration round of the Render engine ////////////////////////////TICKET #1367

Definition in file param-weaving-pattern.hpp.

#include "steam/common.hpp"
#include "steam/engine/turnout.hpp"
#include "steam/engine/turnout-system.hpp"
#include "lib/uninitialised-storage.hpp"
#include "lib/meta/variadic-rebind.hpp"
#include "lib/meta/tuple-helper.hpp"
#include "lib/meta/function.hpp"
#include <tuple>
#include <utility>

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

Classes
struct	ParamBuildSpec< ANCH, FUNZ >
	Specification record for the setup of a »Param Agent Node«. More...
struct	ParamBuildSpec< ANCH, FUNZ >::Accessor< slot >
	a (static) getter functor able to work on the full extended HeteroData-Chain More...
class	ParamBuildSpec< ANCH, FUNZ >::BlockBuilder
struct	ParamWeavingPattern< SPEC >
	Implementation for a Weaving Pattern to conduct extended parameter evaluation. More...
struct	ParamWeavingPattern< SPEC >::Feed
	Storage data frame placed on the call stack. More...

Functions
auto	buildParamSpec ()