buffhandle.hpp File Reference

Go to the source code of this file.

Description

A front-end to support the buffer management within the render nodes.

When pulling data from predecessor nodes and calculating new data, each render node needs several input and output buffers. These may be allocated and provided by various different "buffer providers" (for example the frame cache). Typically, the real buffers will be passed as parameters to the actual job instance when scheduled, drawing on the results of prerequisite jobs. Yet the actual job implementation remains agnostic with respect to the way actual buffers are provided; the invocation just pushes BuffHandle objects around. The actual render function gets an array of C-pointers to the actual buffers, and for accessing those buffers, the node needs to keep a table of buffer pointers, and for releasing the buffers later on, we utilise the buffer handles.

These buffer handles are based on a Buffer Descriptor record, which is opaque as far as the client is concerned. BuffDescr acts as a representation of the type or kind of buffer. The only way to obtain such a BuffDescr is from a concrete BufferProvider implementation. A back-link to this owning and managing provider is embedded into the BuffDescr, which thus may be used as a configuration tag, allowing to retrieve a concrete buffer handle when needed, corresponding to an actual buffer provided and managed behind the scenes. There is no automatic resource management; clients are responsible to invoke BuffHandle::release when done.

Warning

buffer management via BuffHandle and BuffDescr does not automatically maintain proper alignment. Rather, it relies on the storage allocator to provide a buffer suitably aligned for the target type to hold. In most cases, this target location will actually be storage maintained on heap through some STL collection; this topic is a possible subtle pitfall non the less.

See also

BufferProvider

BufferProviderProtocol_test usage demonstration

OutputSlot

bufftable.hpp storage for the buffer table /////////////////////OOO where to point into the new structure for documentation?

engine::RenderInvocation

Definition in file buffhandle.hpp.

#include "lib/error.hpp"
#include "lib/hash-value.h"
#include "steam/streamtype.hpp"

Classes
class	BuffDescr
	An opaque descriptor to identify the type and further properties of a data buffer. More...
class	BuffHandle
	Handle for a buffer for processing data, abstracting away the actual implementation. More...

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