feed-manifold.hpp File Reference

Adapter to connect parameters and data buffers to an external processing function. More...

Go to the source code of this file.

Description

Adapter to connect parameters and data buffers to an external processing function.

The Lumiera Render Engine relies on a »working substrate« of Render Nodes, interconnected in accordance to the structure of foreseeable computations. Yet the actual media processing functionality is provided by external libraries — while the engine is arranged in a way to remain agnostic regarding any details of actual computation. Those external libraries are attached into the system by means of a library plugin, which cares to translate the external capabilities into a representation as Processing Assets. These can be picked up and used in the Session, and will eventually be visited by the Builder as part of the effort to establish the aforementioned »network of Render Nodes.« At this point, external functionality must actually be connected to internal structures: this purpose is served by the FeedManifold.

This amounts to an two-stage adaptation process. Firstly, the plug-in for an external library has to wrap-up and package the library functions into an invocation functor — which thereby creates a low-level Specification of the functionality to invoke. This functor is picked up and stored as a prototype within the associated render node. More specifically, each node can offer several ports for computation. This interface is typically implemented by a Turnout, which in turn is based on some »weaving pattern« performed around and on top of a FeedManifold instance, which is created anew on the stack for each invocation. This invocation scheme implies that the FeedManifold is tailored specifically for a given functor, matching the expectations indicated by the invocation functor's signature:

• A proper invocation functor may accept one to three arguments;
• in must accept one or several output buffers,
• optionally it can accept one or several input buffers,
• optionally it can accept also one or several parameters to control specifics.
• the order of these arguments is fixed to the sequence: parameters, inputs, outputs.
• Parameters are assumed to have value semantics. They must be copyable and default-constructible.
• Buffers are always passed by pointer. The type of the pointee is picked up and passed-through.
• such a pointee or buffer-type is assumed to be default constructible, since the engine will have to construct result buffers within its internal memory management scheme. The library-plugin might have to create a wrapper type in cases where the external library requires to use a specific constructor function for buffers (if this requirement turns out as problematic, there is leeway to pass constructor arguments to such a wrapper — yet Lumiera will insist on managing the memory, so frameworks enforcing their own memory management will have to be broken up and side-stepped, in order to be usable with Lumiera).
• when several and even mixed types of a kind must be given, e.g. several buffers or several parameters, then the processing functor should be written such as to accept a std::tuple or a std::array.

Implementation remarks

A suitable storage layout is chosen at compile type, based on the given functor type.

• essentially, FeedManifold is structured storage with some default-wiring.
• the trait functions #hasInput() and #hasParam() should be used by downstream code to find out if some part of the storage is present and branch accordingly...

Remarks

in the first draft version of the Render Engine from 2009/2012, there was an entity called BuffTable, which however provided additional buffer-management capabilities. This name describes well the basic functionality, which can be hard to see with all the additional meta-programming related to the flexible functor signature. When it comes to actual invocation, we collect input buffers from predecessor nodes and we prepare output buffers, and then we pass both to a processing function.

See also

NodeBase_test

weaving-pattern-builder.hpp

lib::meta::ElmTypes in variadic-helper.hpp "uniform processing of »tuple-like« data"

Definition in file feed-manifold.hpp.

#include "lib/error.hpp"
#include "lib/nocopy.hpp"
#include "steam/engine/buffhandle.hpp"
#include "lib/uninitialised-storage.hpp"
#include "lib/meta/function.hpp"
#include "lib/meta/trait.hpp"
#include "lib/meta/typeseq-util.hpp"
#include "lib/meta/variadic-helper.hpp"
#include "lib/meta/tuple-helper.hpp"
#include "lib/meta/generator.hpp"
#include "lib/test/test-helper.hpp"

Namespaces
namespace	steam
	Steam-Layer implementation namespace root.
namespace	steam::engine
	Lumiera's render engine core and operational control.
namespace	steam::engine::anonymous_namespace{feed-manifold.hpp}

Classes
struct	is_Value< V >
struct	is_Buffer< B >
struct	_ProcFun< FUN >
	Trait template to analyse and adapt to the given processing function. More...
struct	_ProcFun< FUN >::_Case< SIG, SEL >
	Detect use-case as indicated by the function signature. More...
struct	_ProcFun< FUN >::_Case< SIG, enable_if< is_UnaryFun< SIG > > >
struct	_ProcFun< FUN >::_Case< SIG, enable_if< is_BinaryFun< SIG > > >
struct	_ProcFun< FUN >::_Case< SIG, enable_if< is_TernaryFun< SIG > > >
struct	_ParamFun< FUN >
	Trait template to handle an associated parameter functor. More...
struct	_Disabled
	a function of total void More...
struct	_StorageSetup< FUN >
	Configuration context for a FeedManifold. More...
struct	_StorageSetup< FUN >::ParamStorage
	FeedManifold building block: hold parameter data. More...
struct	_StorageSetup< FUN >::BufferSlot_Input
	FeedManifold building block: hold input buffer pointers. More...
struct	_StorageSetup< FUN >::BufferSlot_Output
	FeedManifold building block: hold output buffer pointers. More...
struct	_StorageSetup< FUN >::Storage
	Data Storage block for the FeedManifold Flexibly configured based on the processing function. More...
struct	FeedManifold< FUN >
	Adapter to connect input/output buffers to a processing functor backed by an external library. More...
class	FeedPrototype< FUN, PAM >
	Builder-Prototype to create FeedManifold instances. More...

---

Class Documentation

steam::engine::anonymous_namespace{feed-manifold.hpp}::_ProcFun::_Case

struct steam::engine::anonymous_namespace{feed-manifold.hpp}::_ProcFun::_Case

Collaboration diagram for _ProcFun< FUN >::_Case< SIG, SEL >:

steam::engine::_StorageSetup::BufferSlot_Input

struct steam::engine::_StorageSetup::BufferSlot_Input

Class Members
BuffI	inBuff
ArgI	inArgs {}

Collaboration diagram for _StorageSetup< FUN >::BufferSlot_Input: