Ogre::CompositorNode Class Reference

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

#include <OgreCompositorNode.h>

Inheritance diagram for Ogre::CompositorNode:

Public Member Functions
	CompositorNode (IdType id, IdString name, const CompositorNodeDef *definition, CompositorWorkspace *workspace, RenderSystem *renderSys, TextureGpu *finalTarget)
	The Id must be unique across all engine so we can create unique named textures.
virtual	~CompositorNode ()
const CompositorPassVec &	_getPasses () const
void	_notifyCleared ()
	Internal Use.
void	_update (const Camera *lodCamera, SceneManager *sceneManager)
	Calling this function every frame will cause us to execute all our passes (ie.
bool	areAllInputsConnected () const
void	connectBufferTo (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 (buffer version)
void	connectExternalBuffer (UavBufferPacked *buffer, size_t inChannelA)
	Connects (injects) an external buffer into the given channel.
void	connectExternalRT (TextureGpu *externalTexture, size_t inChannelA)
	Connects (injects) an external RT into the given channel.
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 (texture version)
void	createPasses ()
	Creates all passes based on our definition.
void	destroyAllPasses ()
virtual void	finalTargetResized01 (const TextureGpu *finalTarget)
	Called by CompositorManager2 when (i.e.) the RenderWindow was resized, thus our RTs that depend on their resolution need to be recreated.
virtual void	finalTargetResized02 (const TextureGpu *finalTarget)
UavBufferPacked *	getDefinedBuffer (IdString bufferName) const
	Returns the buffer pointer of a buffer based on it's name.
UavBufferPacked *	getDefinedBufferNoThrow (IdString bufferName) const
TextureGpu *	getDefinedTexture (IdString textureName) const
	Returns the texture pointer of a texture based on it's name & mrt index.
const CompositorNodeDef *	getDefinition () const
bool	getEnabled () const
	Returns if this instance is enabled.
const CompositorChannelVec &	getInputChannel () const
const CompositorChannelVec &	getLocalTextures () const
IdString	getName () const
size_t	getPassNumber (CompositorPass *pass) const
	See CompositorNodeDef::getPassNumber.
RenderSystem *	getRenderSystem () const
CompositorWorkspace *	getWorkspace ()
	Returns our parent workspace.
const CompositorWorkspace *	getWorkspace () const
	Returns our parent workspace.
void	notifyDestroyed (const UavBufferPacked *buffer)
void	notifyDestroyed (TextureGpu *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.
void	notifyRecreated (const UavBufferPacked *oldBuffer, UavBufferPacked *newBuffer)
void	notifyRecreated (TextureGpu *channel)
	Call this function when you're replacing the textures from oldChannel with the ones in newChannel.
void	resetAllNumPassesLeft ()
	Resets the number of passes left for every pass (see CompositorPassDef::mNumInitialPasses) Useful when you have a few starting 'initialization' passes and you want to reset them.
void	setEnabled (bool bEnabled)
	Enables or disables all instances of this node.
Public Member Functions inherited from Ogre::IdObject
	IdObject (IdType id)
	We don't call generateNewId() here, to prevent objects in the stack (i.e.
IdType	getId () const
	Get the unique id of this object.
bool	operator() (const IdObject &left, const IdObject &right)
bool	operator() (const IdObject *left, const IdObject *right)

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

Constructor & Destructor Documentation

CompositorNode()

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

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

The name is only unique across the workspace

~CompositorNode()

virtual Ogre::CompositorNode::~CompositorNode ( )

virtual

Member Function Documentation

_getPasses()

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

inline

_notifyCleared()

void Ogre::CompositorNode::_notifyCleared

(

)

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 CompositorNode::mConnectedNodes nodes. Failing to clear them too may leave dangling pointers or graphical glitches

Remarks

Destroys all of our passes.

_update()

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

lodCamera

LOD 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).

areAllInputsConnected()

bool Ogre::CompositorNode::areAllInputsConnected

(

)

const

connectBufferTo()

void Ogre::CompositorNode::connectBufferTo	(	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 (buffer version)

Parameters

outChannelA	Output to use from node A.
inChannelB	Input to connect the output from A.

connectExternalBuffer()

void Ogre::CompositorNode::connectExternalBuffer	(	UavBufferPacked *	buffer,
		size_t	inChannelA
	)

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

Usually used for the 'connect_buffer_external' directive.

Parameters

buffer	The buffer.
inChannelA	In which channel number to inject to.

connectExternalRT()

void Ogre::CompositorNode::connectExternalRT	(	TextureGpu *	externalTexture,
		size_t	inChannelA
	)

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

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

Parameters

rt	The RenderTarget.
textures	The Textures associated with the RT. Can be empty (eg. RenderWindow) but could cause crashes/exceptions if tried to use in PASS_QUAD passes.
inChannelA	In which channel number to inject to.

connectTo()

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 (texture version)

Parameters

outChannelA	Output to use from node A.
inChannelB	Input to connect the output from A.

createPasses()

void Ogre::CompositorNode::createPasses

(

)

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) See connectTo() and connectFinalRT().

destroyAllPasses()

void Ogre::CompositorNode::destroyAllPasses

(

)

finalTargetResized01()

virtual void Ogre::CompositorNode::finalTargetResized01 ( const TextureGpu *  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).

This is divided in two steps: recreateResizableTextures01 & recreateResizableTextures02 since in some cases in RenderPassDescriptor, setting up MRT and depth textures requires all textures to be up to date, otherwise validation errors would occur since we'll have partial data (e.g. MRT 0 is 1024x768 while MRT 1 is 800x600)

Parameters

finalTarget

The Final Target (i.e. RenderWindow) from which we'll base our local textures' resolution.

Reimplemented in Ogre::CompositorShadowNode.

finalTargetResized02()

virtual void Ogre::CompositorNode::finalTargetResized02 ( const TextureGpu *  finalTarget )

virtual

getDefinedBuffer()

UavBufferPacked * Ogre::CompositorNode::getDefinedBuffer

(

IdString

bufferName

)

const

Returns the buffer pointer of a buffer based on it's name.

Remarks

The buffer may come from a local buffer, an input buffer, or global (workspace).

Parameters

bufferName

The name of the buffer. This name may only be valid at node scope. It can refer to an input buffer, a local buffer, or a global one. If a local or input buffer has the same name as a global one, the global one is ignored.

Returns

Regular: The buffer. Throws if buffer wasn't found. No throw version: Null if not found. The buffer otherwise

getDefinedBufferNoThrow()

UavBufferPacked * Ogre::CompositorNode::getDefinedBufferNoThrow

(

IdString

bufferName

)

const

getDefinedTexture()

TextureGpu * Ogre::CompositorNode::getDefinedTexture

(

IdString

textureName

)

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

textureName

The 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.

Returns

Null if not found (or global texture not registered). The texture otherwise

getDefinition()

const CompositorNodeDef * Ogre::CompositorNode::getDefinition ( ) const

inline

getEnabled()

bool Ogre::CompositorNode::getEnabled ( ) const

inline

Returns if this instance is enabled.

See also

setEnabled

getInputChannel()

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

inline

getLocalTextures()

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

inline

getName()

IdString Ogre::CompositorNode::getName ( ) const

inline

getPassNumber()

size_t Ogre::CompositorNode::getPassNumber

(

CompositorPass *

pass

)

const

See CompositorNodeDef::getPassNumber.

getRenderSystem()

RenderSystem * Ogre::CompositorNode::getRenderSystem ( ) const

inline

getWorkspace() [1/2]

CompositorWorkspace * Ogre::CompositorNode::getWorkspace ( )

inline

Returns our parent workspace.

getWorkspace() [2/2]

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

inline

Returns our parent workspace.

notifyDestroyed() [1/2]

void Ogre::CompositorNode::notifyDestroyed

(

const UavBufferPacked *

buffer

)

notifyDestroyed() [2/2]

void Ogre::CompositorNode::notifyDestroyed

(

TextureGpu *

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

channel

Channel containing the pointer about to be destroyed (must still be valid)

notifyRecreated() [1/2]

void Ogre::CompositorNode::notifyRecreated	(	const UavBufferPacked *	oldBuffer,
		UavBufferPacked *	newBuffer
	)

notifyRecreated() [2/2]

void Ogre::CompositorNode::notifyRecreated

(

TextureGpu *

channel

)

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

oldChannel	The old textures that are going to be removed. Pointers in it must be still valid
newChannel	The new replacement textures

resetAllNumPassesLeft()

void Ogre::CompositorNode::resetAllNumPassesLeft

(

)

Resets the number of passes left for every pass (see CompositorPassDef::mNumInitialPasses) Useful when you have a few starting 'initialization' passes and you want to reset them.

setEnabled()

void Ogre::CompositorNode::setEnabled

(

bool

bEnabled

)

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).

---

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

• OgreCompositorNode.h