OGRE  2.0
Object-Oriented Graphics Rendering Engine
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
Ogre::CompositorNode Class Reference

Compositor nodes are the core subject of compositing. More...

#include <OgreCompositorNode.h>

+ Inheritance diagram for Ogre::CompositorNode:
+ Collaboration diagram for Ogre::CompositorNode:

Public Member Functions

 CompositorNode (IdType id, IdString name, const CompositorNodeDef *definition, CompositorWorkspace *workspace, RenderSystem *renderSys, const RenderTarget *finalTarget)
 The Id must be unique across all engine so we can create unique named textures. More...
 
virtual ~CompositorNode ()
 
const CompositorPassVec_getPasses () const
 
void _notifyCleared (void)
 Internal Use. More...
 
void _update (const Camera *lodCamera, SceneManager *sceneManager)
 Calling this function every frame will cause us to execute all our passes (ie. More...
 
bool areAllInputsConnected () const
 
void connectFinalRT (RenderTarget *rt, CompositorChannel::TextureVec &textures, size_t inChannelA)
 Connects (injects) an external RT into the given channel. More...
 
void connectTo (size_t outChannelA, CompositorNode *nodeB, size_t inChannelB)
 Connects this node (let's call it node 'A') to node 'B', mapping the output channel from A into the input channel from B. More...
 
void createPasses (void)
 Creates all passes based on our definition. More...
 
virtual void finalTargetResized (const RenderTarget *finalTarget)
 Called by CompositorManager2 when (i.e.) the RenderWindow was resized, thus our RTs that depend on their resolution need to be recreated. More...
 
TexturePtr getDefinedTexture (IdString textureName, size_t mrtIndex) const
 Returns the texture pointer of a texture based on it's name & mrt index. More...
 
const CompositorNodeDefgetDefinition () const
 
bool getEnabled (void) const
 Returns if this instance is enabled. setEnabled. More...
 
IdType getId () const
 Get the unique id of this object. More...
 
const CompositorChannelVecgetInputChannel () const
 
const CompositorChannelVecgetLocalTextures () const
 
IdString getName (void) const
 
CompositorWorkspacegetWorkspace (void)
 Returns our parent workspace. More...
 
const CompositorWorkspacegetWorkspace (void) const
 Returns our parent workspace. More...
 
void notifyDestroyed (const CompositorChannel &channel)
 Call this function when caller has destroyed a RenderTarget in which the callee may have a reference to that pointer, so that we can clean it up. More...
 
void notifyRecreated (const CompositorChannel &oldChannel, const CompositorChannel &newChannel)
 Call this function when you're replacing the textures from oldChannel with the ones in newChannel. More...
 
void operator delete (void *ptr)
 
void operator delete (void *ptr, void *)
 
void operator delete (void *ptr, const char *, int, const char *)
 
void operator delete[] (void *ptr)
 
void operator delete[] (void *ptr, const char *, int, const char *)
 
void * operator new (size_t sz, const char *file, int line, const char *func)
 operator new, with debug line info More...
 
void * operator new (size_t sz)
 
void * operator new (size_t sz, void *ptr)
 placement operator new More...
 
void * operator new[] (size_t sz, const char *file, int line, const char *func)
 array operator new, with debug line info More...
 
void * operator new[] (size_t sz)
 
bool operator() (const IdObject *left, const IdObject *right)
 
bool operator() (const IdObject &left, const IdObject &right)
 
void setEnabled (bool bEnabled)
 Enables or disables all instances of this node. More...
 

Protected Member Functions

void _setId (IdType newId)
 In the rare case our derived class wants to override our Id (normally we don't want that, that's why it's private). More...
 
void disconnectOutput ()
 Disconnects this node's output from all nodes we send our textures to. More...
 
virtual void postInitializePassScene (CompositorPassScene *pass)
 Called right after we create a PASS_SCENE pass. More...
 
void routeOutputs ()
 Used to create/destroy MRTs. More...
 

Protected Attributes

CompositorNodeVec mConnectedNodes
 Nodes we're connected to. If we destroy our local textures, we need to inform them. More...
 
bool mEnabled
 
CompositorChannelVec mInTextures
 
CompositorChannelVec mLocalTextures
 
IdString mName
 Unique name across the same workspace. More...
 
size_t mNumConnectedInputs
 Must be <= mInTextures.size(). Tracks how many pointers are not null in mInTextures. More...
 
CompositorChannelVec mOutTextures
 Contains pointers that are ither in mInTextures or mLocalTextures. More...
 
CompositorPassVec mPasses
 
RenderSystemmRenderSystem
 
CompositorWorkspacemWorkspace
 

Private Attributes

CompositorNodeDef const * mDefinition
 

Detailed Description

Compositor nodes are the core subject of compositing.

This is an instantiation. All const, shared parameters are in the definition (CompositorNodeDef) and we assume they don't change throughout the lifetime of our instance.

The textures in mLocalTextures are managed by us and we're responsible for freeing them when they're no longer needed.
Before nodes can be used, they have to be connected between each other, followed by a call to routeOutputs() Connections must be done in a very specific order, so let the manager take care of solving the dependencies. Basically the problem is that if the chain is like this: A -> B -> C; if we connect node B to C first, then there's a chance of giving null pointers to C instead of the valid ones that belong to A.
To solve this problem, we first start with nodes that have no input, and then continue with those who have all of their input set; then repeat until there are no nodes to be processed. If there's still nodes with input left open; then those nodes can't be activated and the workspace is invalid.
No Node can be valid if it has disconnected input channels left. Nodes can have no input because they either use passes that don't need it (eg. scene pass) or use global textures as means for sharing their work Similarly, Nodes may have no output because they use global textures.
Nodes with feedback loops are not supported and may or may not work. A feedback loop is when A's output is used in B, B to C, then C is plugged back into A.
It's possible to assign the same output to two different input channels, though it could work very unintuitively... (because two textures that may be intended to be hard copies are actually sharing the same memory)
Remarks
We own the local textures, so it's our job to destroy them
Author
Matias N. Goldberg
Version
1.0

Definition at line 90 of file OgreCompositorNode.h.

Constructor & Destructor Documentation

Ogre::CompositorNode::CompositorNode ( IdType  id,
IdString  name,
const CompositorNodeDef definition,
CompositorWorkspace workspace,
RenderSystem renderSys,
const RenderTarget finalTarget 
)

The Id must be unique across all engine so we can create unique named textures.

The name is only unique across the workspace

virtual Ogre::CompositorNode::~CompositorNode ( )
virtual

Member Function Documentation

const CompositorPassVec& Ogre::CompositorNode::_getPasses ( ) const
inline

Definition at line 214 of file OgreCompositorNode.h.

void Ogre::CompositorNode::_notifyCleared ( void  )

Internal Use.

Called when connections are all being zero'ed. We rely our caller is doing this to all nodes, hence we do not notify our nodes. Failing to clear them too may leave dangling pointers or graphical glitches

Remarks
Destroys all of our passes.
void Ogre::IdObject::_setId ( IdType  newId)
inlineprotectedinherited

In the rare case our derived class wants to override our Id (normally we don't want that, that's why it's private).

Definition at line 63 of file OgreId.h.

void Ogre::CompositorNode::_update ( const Camera lodCamera,
SceneManager sceneManager 
)

Calling this function every frame will cause us to execute all our passes (ie.

render)

Parameters
lodCameraLOD Camera to be used by our passes. Pointer can be null, and note however passes can ignore this hint and use their own camera pointer for LOD (this parameter is mostly used for syncing shadow mapping).
bool Ogre::CompositorNode::areAllInputsConnected ( ) const
inline

Definition at line 185 of file OgreCompositorNode.h.

void Ogre::CompositorNode::connectFinalRT ( RenderTarget rt,
CompositorChannel::TextureVec textures,
size_t  inChannelA 
)

Connects (injects) an external RT into the given channel.

Usually used for the "connect_output" directive for the RenderWindow.

Parameters
rtThe RenderTarget.
texturesThe Textures associated with the RT. Can be empty (eg. RenderWindow) but could cause crashes/exceptions if tried to use in PASS_QUAD passes.
inChannelAIn which channel number to inject to.
void Ogre::CompositorNode::connectTo ( size_t  outChannelA,
CompositorNode nodeB,
size_t  inChannelB 
)

Connects this node (let's call it node 'A') to node 'B', mapping the output channel from A into the input channel from B.

Parameters
outChannelAOutput to use from node A.
inChannelBInput to connect the output from A.
void Ogre::CompositorNode::createPasses ( void  )

Creates all passes based on our definition.

Remarks
Call this function after connecting all channels (at least our input) otherwise we may bind null pointer RTs to the passes (and then crash) connectTo and
See also
connectFinalRT
void Ogre::CompositorNode::disconnectOutput ( )
protected

Disconnects this node's output from all nodes we send our textures to.

We only disconnect local textures.

Remarks
Textures that we got from our input channel and then pass it to the output channel are left untouched. This allows for some node to be plugged back & forth without making much mess and leaving everything else working.
virtual void Ogre::CompositorNode::finalTargetResized ( const RenderTarget finalTarget)
virtual

Called by CompositorManager2 when (i.e.) the RenderWindow was resized, thus our RTs that depend on their resolution need to be recreated.

Remarks
We inform all connected nodes and passes related to us of RenderTargets/Textures that may have been recreated (pointers could become danlging otherwise).
Parameters
finalTargetThe Final Target (i.e. RenderWindow) from which we'll base our local textures' resolution.

Reimplemented in Ogre::CompositorShadowNode.

TexturePtr Ogre::CompositorNode::getDefinedTexture ( IdString  textureName,
size_t  mrtIndex 
) const

Returns the texture pointer of a texture based on it's name & mrt index.

Remarks
The texture name must have been registered with CompositorNodeDef::addTextureSourceName
Parameters
textureNameThe name of the texture. This name may only be valid at node scope. It can refer to an input texture, a local texture, or a global one. If the global texture wasn't registered with addTextureSourceName, it will fail.
mrtIndexThe MRT (Multiple Render Target) index. If the texture isn't MRT or has less RTs than the index, it returns the highest valid index found.
Returns
Null if not found (or global texture not registered). The texture otherwise
const CompositorNodeDef* Ogre::CompositorNode::getDefinition ( ) const
inline

Definition at line 146 of file OgreCompositorNode.h.

bool Ogre::CompositorNode::getEnabled ( void  ) const
inline

Returns if this instance is enabled. setEnabled.

Definition at line 161 of file OgreCompositorNode.h.

IdType Ogre::IdObject::getId ( ) const
inlineinherited

Get the unique id of this object.

Definition at line 74 of file OgreId.h.

const CompositorChannelVec& Ogre::CompositorNode::getInputChannel ( ) const
inline

Definition at line 186 of file OgreCompositorNode.h.

const CompositorChannelVec& Ogre::CompositorNode::getLocalTextures ( ) const
inline

Definition at line 187 of file OgreCompositorNode.h.

IdString Ogre::CompositorNode::getName ( void  ) const
inline

Definition at line 145 of file OgreCompositorNode.h.

CompositorWorkspace* Ogre::CompositorNode::getWorkspace ( void  )
inline

Returns our parent workspace.

Definition at line 260 of file OgreCompositorNode.h.

const CompositorWorkspace* Ogre::CompositorNode::getWorkspace ( void  ) const
inline

Returns our parent workspace.

Definition at line 263 of file OgreCompositorNode.h.

void Ogre::CompositorNode::notifyDestroyed ( const CompositorChannel channel)

Call this function when caller has destroyed a RenderTarget in which the callee may have a reference to that pointer, so that we can clean it up.

Parameters
channelChannel containing the pointer about to be destroyed (must still be valid)
void Ogre::CompositorNode::notifyRecreated ( const CompositorChannel oldChannel,
const CompositorChannel newChannel 
)

Call this function when you're replacing the textures from oldChannel with the ones in newChannel.

Useful when recreating textures (i.e. resolution changed)

Parameters
oldChannelThe old textures that are going to be removed. Pointers in it must be still valid
newChannelThe new replacement textures
template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr)
inlineinherited

Definition at line 96 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr,
void *   
)
inlineinherited

Definition at line 102 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr,
const char *  ,
int  ,
const char *   
)
inlineinherited

Definition at line 108 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete[] ( void *  ptr)
inlineinherited

Definition at line 113 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete[] ( void *  ptr,
const char *  ,
int  ,
const char *   
)
inlineinherited

Definition at line 119 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new ( size_t  sz,
const char *  file,
int  line,
const char *  func 
)
inlineinherited

operator new, with debug line info

Definition at line 68 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new ( size_t  sz)
inlineinherited

Definition at line 73 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new ( size_t  sz,
void *  ptr 
)
inlineinherited

placement operator new

Definition at line 79 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new[] ( size_t  sz,
const char *  file,
int  line,
const char *  func 
)
inlineinherited

array operator new, with debug line info

Definition at line 86 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new[] ( size_t  sz)
inlineinherited

Definition at line 91 of file OgreMemoryAllocatedObject.h.

bool Ogre::IdObject::operator() ( const IdObject left,
const IdObject right 
)
inlineinherited

Definition at line 76 of file OgreId.h.

References Ogre::IdObject::mId.

bool Ogre::IdObject::operator() ( const IdObject left,
const IdObject right 
)
inlineinherited

Definition at line 81 of file OgreId.h.

References Ogre::IdObject::mId.

virtual void Ogre::CompositorNode::postInitializePassScene ( CompositorPassScene pass)
inlineprotectedvirtual

Called right after we create a PASS_SCENE pass.

Derived classes may want to do something with it

Parameters
passNewly created pass to toy with.

Reimplemented in Ogre::CompositorShadowNode.

Definition at line 134 of file OgreCompositorNode.h.

void Ogre::CompositorNode::routeOutputs ( )
protected

Used to create/destroy MRTs.

Fills mOutTextures with the pointers from mInTextures & mLocalTextures according to CompositorNodeDef::mOutChannelMapping. Call this immediately after modifying mInTextures or mLocalTextures

void Ogre::CompositorNode::setEnabled ( bool  bEnabled)
inline

Enables or disables all instances of this node.

Remarks
Note that we just won't execute our passes. It's your job to change the channel connections accordingly if you have to. A disabled node won't complain when its connections are incomplete in a workspace.
This function is useful frequently toggling a compositor effect without having to recreate any API resource (which often would involve stalls).

Definition at line 158 of file OgreCompositorNode.h.

Member Data Documentation

CompositorNodeVec Ogre::CompositorNode::mConnectedNodes
protected

Nodes we're connected to. If we destroy our local textures, we need to inform them.

Definition at line 108 of file OgreCompositorNode.h.

CompositorNodeDef const* Ogre::CompositorNode::mDefinition
private

Definition at line 266 of file OgreCompositorNode.h.

bool Ogre::CompositorNode::mEnabled
protected

Definition at line 95 of file OgreCompositorNode.h.

CompositorChannelVec Ogre::CompositorNode::mInTextures
protected

Definition at line 99 of file OgreCompositorNode.h.

CompositorChannelVec Ogre::CompositorNode::mLocalTextures
protected

Definition at line 100 of file OgreCompositorNode.h.

IdString Ogre::CompositorNode::mName
protected

Unique name across the same workspace.

Definition at line 94 of file OgreCompositorNode.h.

size_t Ogre::CompositorNode::mNumConnectedInputs
protected

Must be <= mInTextures.size(). Tracks how many pointers are not null in mInTextures.

Definition at line 98 of file OgreCompositorNode.h.

CompositorChannelVec Ogre::CompositorNode::mOutTextures
protected

Contains pointers that are ither in mInTextures or mLocalTextures.

Definition at line 103 of file OgreCompositorNode.h.

CompositorPassVec Ogre::CompositorNode::mPasses
protected

Definition at line 105 of file OgreCompositorNode.h.

RenderSystem* Ogre::CompositorNode::mRenderSystem
protected

Definition at line 112 of file OgreCompositorNode.h.

CompositorWorkspace* Ogre::CompositorNode::mWorkspace
protected

Definition at line 110 of file OgreCompositorNode.h.


The documentation for this class was generated from the following file: