diff --git a/src/proc/engine/buffhandle.hpp b/src/proc/engine/buffhandle.hpp index eb87ffec2..185914fa5 100644 --- a/src/proc/engine/buffhandle.hpp +++ b/src/proc/engine/buffhandle.hpp @@ -21,9 +21,9 @@ */ /** @file buffhandle.hpp - ** Various bits needed to support the buffer management within the render nodes. + ** 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 several + ** 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 @@ -31,12 +31,18 @@ ** 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. - ** The usage pattern of those buffer pointer tables is stack-like, thus the actual - ** implementation utilises a single large buffer pointer array per pull() call - ** sequence and dynamically claims small chunks for each node. ** - ** @see nodewiring-def.hpp - ** @see nodeoperation.hpp + ** These buffer handles are based on a buffer descriptor record, which is opaque as far + ** as the client is concerned. BufferDescriptor acts as a representation of the type or + ** kind of buffer. The only way to obtain such a BufferDescriptor is from a concrete + ** BufferProvider implementation. A back-link to this owning and managing provider is + ** embedded into the BufferDescriptor, allowing to retrieve an buffer handle, 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. + ** + ** @see BufferProvider + ** @see BufferProviderProtocol_test usage demonstration + ** @see OutputSlot ** @see bufftable.hpp storage for the buffer table ** @see engine::RenderInvocation */ @@ -99,24 +105,6 @@ namespace engine { - class ProcNode; - typedef ProcNode* PNode; - - - struct ChannelDescriptor ///////TODO really need to define that here? it is needed for node wiring only - { - const lumiera::StreamType * bufferType; /////////////////////////////////////////TICKET #828 - }; - - struct InChanDescriptor : ChannelDescriptor - { - PNode dataSrc; ///< the ProcNode to pull this input from - uint srcChannel; ///< output channel to use on the predecessor node - }; - - - - /** * Handle for a buffer for processing data, abstracting away the actual implementation. diff --git a/src/proc/engine/channel-descriptor.hpp b/src/proc/engine/channel-descriptor.hpp index 1631690dc..0a8e9887a 100644 --- a/src/proc/engine/channel-descriptor.hpp +++ b/src/proc/engine/channel-descriptor.hpp @@ -20,24 +20,15 @@ */ -/** @file buffhandle.hpp - ** Various bits needed 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 several - ** 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. - ** The usage pattern of those buffer pointer tables is stack-like, thus the actual - ** implementation utilises a single large buffer pointer array per pull() call - ** sequence and dynamically claims small chunks for each node. +/** @file channel-descriptor.hpp + ** Representation of the Media type of a data channel used within the engine. + ** + ** @todo as it stands (11/2011) this file is obsoleted and needs to be refactored, + ** alongside with adapting the node invocation to the new BufferProvider interface. ** ** @see nodewiring-def.hpp ** @see nodeoperation.hpp - ** @see bufftable.hpp storage for the buffer table + ** @see bufftable-obsolete.hpp storage for the buffer table ** @see engine::RenderInvocation */ @@ -59,43 +50,7 @@ namespace engine { class BuffHandle; class BufferProvider; - - - - /** - * An opaque descriptor to identify the type and further properties of a data buffer. - * For each kind of buffer, there is somewhere a BufferProvider responsible for the - * actual storage management. This provider may "lock" a buffer for actual use, - * returning a BuffHandle. - * @note this descriptor and especially the #subClassification_ is really owned - * by the BufferProvider, which may use (and even change) the opaque contents - * to organise the internal buffer management. - * - * @todo try to move that definition into buffer-provider.hpp ////////////////////////////////////TICKET #249 - */ - class BufferDescriptor - { - BufferProvider* provider_; - HashVal subClassification_; - - BufferDescriptor(BufferProvider& manager, HashVal detail) - : provider_(&manager) - , subClassification_(detail) - { } - - friend class BufferProvider; - - public: - // using standard copy operations - - bool verifyValidity() const; - size_t determineBufferSize() const; - - void emit (BuffHandle const&) const; - void release (BuffHandle const&) const; - - operator HashVal() const { return subClassification_; } - }; + class BufferDescriptor; @@ -116,127 +71,5 @@ namespace engine { - - - /** - * Handle for a buffer for processing data, abstracting away the actual implementation. - * The real buffer pointer can be retrieved by dereferencing this smart-handle class. - * - * @todo as of 6/2011 it isn't clear how buffer handles are actually created - * and how the lifecycle (and memory) management works //////////////////////TICKET #249 rework BuffHandle creation and usage - */ - class BuffHandle - : public lib::BoolCheckable - { - typedef lumiera::StreamType::ImplFacade::DataBuffer Buff; - - BufferDescriptor descriptor_; - Buff* pBuffer_; - - - public: - typedef Buff* PBuff; - - /** @internal a buffer handle may be obtained by "locking" - * a buffer from the corresponding BufferProvider */ - BuffHandle(BufferDescriptor const& typeInfo, void* storage = 0) - : descriptor_(typeInfo) - , pBuffer_(static_cast(storage)) - { } - - // using standard copy operations - - - - void - emit() - { - REQUIRE (pBuffer_); - descriptor_.emit (*this); - } - - void release() - { - if (pBuffer_) - { - REQUIRE (isValid()); - descriptor_.release (*this); - pBuffer_ = 0; - } - ENSURE (!isValid()); - } - - - template - BU& create(); - - template - BU& accessAs(); - - - //////////////////////////////////////////TICKET #249 this operator looks obsolete. The Buff type is a placeholder type, - //////////////////////////////////////////TODO it should never be accessed directly from within Lumiera engine code - Buff& - operator* () const - { - ENSURE (pBuffer_); - return *pBuffer_; - } - - bool - isValid() const - { - return bool(pBuffer_) - && descriptor_.verifyValidity(); - } - - HashVal - entryID() const - { - return descriptor_; - } - - size_t - size() const - { - return descriptor_.determineBufferSize(); - } - - }; - - - /* === Implementation details === */ - - /** convenience shortcut: place and maintain an object within the buffer. - * This operation performs the necessary steps to attach an object; - * if the buffer isn't locked yet, it will do so. Moreover, the created - * object will be owned by the buffer management facilities, i.e. the - * destructor is registered as cleanup function. - */ - template - BU& - BuffHandle::create() - { - UNIMPLEMENTED ("convenience shortcut to attach/place an object in one sway"); - } - - - /** convenience shortcut: access the buffer contents casted to a specific type. - * @warning this is a \em blind cast, there is no type safety. - * @note clients can utilise the metadata::LocalKey to keep track of some - * specific property of the buffer, like e.g. the type of object. - */ - template - BU& - BuffHandle::accessAs() - { - if (!pBuffer_) - throw error::Logic ("buffer not (yet) locked for access by clients" - , LUMIERA_ERROR_LIFECYCLE); - return *reinterpret_cast (pBuffer_); - } - - - } // namespace engine #endif diff --git a/src/proc/engine/procnode.hpp b/src/proc/engine/procnode.hpp index 757524914..4017140c6 100644 --- a/src/proc/engine/procnode.hpp +++ b/src/proc/engine/procnode.hpp @@ -46,6 +46,7 @@ #include "proc/state.hpp" #include "proc/asset/proc.hpp" #include "proc/mobject/parameter.hpp" +#include "proc/engine/channel-descriptor.hpp" #include "lib/frameid.hpp" #include "lib/ref-array.hpp"