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

virtual	~CompositorNode ()

const CompositorPassVec &	_getPasses () const

void	_notifyCleared ()
	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	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) More...

void	connectExternalBuffer (UavBufferPacked *buffer, size_t inChannelA)
	Connects (injects) an external buffer into the given channel. More...

void	connectExternalRT (TextureGpu *externalTexture, 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 (texture version) More...

void	createPasses ()
	Creates all passes based on our definition. More...

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

virtual void	finalTargetResized02 (const TextureGpu *finalTarget)

UavBufferPacked *	getDefinedBuffer (IdString bufferName) const
	Returns the buffer pointer of a buffer based on it's name. More...

UavBufferPacked *	getDefinedBufferNoThrow (IdString bufferName) const

TextureGpu *	getDefinedTexture (IdString textureName) const
	Returns the texture pointer of a texture based on it's name & mrt index. More...

const CompositorNodeDef *	getDefinition () const

bool	getEnabled () const
	Returns if this instance is enabled. More...

const CompositorChannelVec &	getInputChannel () const

const CompositorChannelVec &	getLocalTextures () const

IdString	getName () const

size_t	getPassNumber (CompositorPass *pass) const
	See CompositorNodeDef::getPassNumber. More...

RenderSystem *	getRenderSystem () const

CompositorWorkspace *	getWorkspace ()
	Returns our parent workspace. More...

const CompositorWorkspace *	getWorkspace () const
	Returns our parent workspace. More...

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

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

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

void	setEnabled (bool bEnabled)
	Enables or disables all instances of this node. More...

Public Member Functions inherited from Ogre::IdObject
	IdObject (IdType id)
	We don't call generateNewId() here, to prevent objects in the stack (i.e. More...

IdType	getId () const
	Get the unique id of this object. More...

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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ CompositorNode()

◆ ~CompositorNode()

Member Function Documentation

◆ _getPasses()

◆ _notifyCleared()

◆ _update()

◆ areAllInputsConnected()

◆ connectBufferTo()

◆ connectExternalBuffer()

◆ connectExternalRT()

◆ connectTo()

◆ createPasses()

◆ destroyAllPasses()

◆ finalTargetResized01()

◆ finalTargetResized02()

◆ getDefinedBuffer()

◆ getDefinedBufferNoThrow()

◆ getDefinedTexture()

◆ getDefinition()

◆ getEnabled()

◆ getInputChannel()

◆ getLocalTextures()

◆ getName()

◆ getPassNumber()

◆ getRenderSystem()

◆ getWorkspace() [1/2]

◆ getWorkspace() [2/2]

◆ notifyDestroyed() [1/2]

◆ notifyDestroyed() [2/2]

◆ notifyRecreated() [1/2]

◆ notifyRecreated() [2/2]

◆ resetAllNumPassesLeft()

◆ setEnabled()