OGRE-Next: Ogre::CompositorNode Class Reference

| OGRE-Next 3.0.0 Object-Oriented Graphics Rendering Engine

Loading...
Searching...
No Matches
Ogre::CompositorNode Class Reference
Core » Effects

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

`#include <OgreCompositorNode.h>`

Inheritance diagram for Ogre::CompositorNode:
[legend]

## 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

Referenced by connectBufferTo(), and connectTo().

## ◆ ~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.

References CompositorNode().

## ◆ 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.

References CompositorNode().

## ◆ 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