OGRE-Next  4.0.0unstable
Object-Oriented Graphics Rendering Engine
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. 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)
 
UavBufferPackedgetDefinedBuffer (IdString bufferName) const
 Returns the buffer pointer of a buffer based on it's name. More...
 
UavBufferPackedgetDefinedBufferNoThrow (IdString bufferName) const
 
TextureGpugetDefinedTexture (IdString textureName) const
 Returns the texture pointer of a texture based on it's name & mrt index. More...
 
const CompositorNodeDefgetDefinition () const
 
bool getEnabled () const
 Returns if this instance is enabled. More...
 
const CompositorChannelVecgetInputChannel () const
 
const CompositorChannelVecgetLocalTextures () const
 
IdString getName () const
 
size_t getPassNumber (CompositorPass *pass) const
 See CompositorNodeDef::getPassNumber. More...
 
RenderSystemgetRenderSystem () const
 
CompositorWorkspacegetWorkspace ()
 Returns our parent workspace. More...
 
const CompositorWorkspacegetWorkspace () 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
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).

◆ 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
outChannelAOutput to use from node A.
inChannelBInput 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
bufferThe buffer.
inChannelAIn 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
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.

◆ 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
outChannelAOutput to use from node A.
inChannelBInput 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
finalTargetThe 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
bufferNameThe 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
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.
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

◆ 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
channelChannel 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
oldChannelThe old textures that are going to be removed. Pointers in it must be still valid
newChannelThe 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: