OGRE: Ogre::CompositorWorkspace Class Reference

| OGRE 2.2.4 Object-Oriented Graphics Rendering Engine

Public Member Functions | List of all members
Ogre::CompositorWorkspace Class Reference
Core » Effects

A compositor workspace is the main interface to render into an RT, be it a RenderWindow or an RTT (Render Texture Target). More...

`#include <OgreCompositorWorkspace.h>`

Inheritance diagram for Ogre::CompositorWorkspace:
[legend]

## Public Member Functions
| CompositorWorkspace (IdType id, const CompositorWorkspaceDef *definition, const CompositorChannelVec &externalRenderTargets, SceneManager *sceneManager, Camera *defaultCam, RenderSystem *renderSys, bool bEnabled, uint8 executionMask, uint8 viewportModifierMask, const Vector4 &vpOffsetScale, const UavBufferPackedVec *uavBuffers, const ResourceLayoutMap *initialLayouts, const ResourceAccessMap *initialUavAccess)
virtual | ~CompositorWorkspace ()
void | _beginUpdate (bool forceBeginFrame)
| Call before _update unless the final render target is not a render window. More...
void | _endUpdate (bool forceEndFrame)
| Call after _update unless the final render target is not a render window. More...
void | _notifyBarriersDirty (void)
void | _swapFinalTarget (vector< TextureGpu * >::type &swappedTargets)
| In the case of RenderWindows, swaps/copies/flips the front with the back buffer. More...
void | _update (void)
| Updates the workspace's nodes. More...
void | _validateFinalTarget (void)
| For compatibility with D3D9, forces a device lost check on the RenderWindow, so that BeginScene doesn't fail. More...
void | addListener (CompositorWorkspaceListener *listener)
void | fillUavDependenciesForNextWorkspace (ResourceLayoutMap &outInitialLayouts, ResourceAccessMap &outInitialUavAccess) const
| When two workspaces work on the same channels/textures, to avoid race conditions in Compute Shaders each workspace needs to know what the the previous workspace did; and that information must be supplied during workspace creation. More...
Camera * | findCamera (IdString cameraName) const
| Finds a camera in the scene manager we have. More...
CompositorNode * | findNode (IdString aliasName, bool includeShadowNodes=false) const
| Finds a node instance with the given aliased name. More...
CompositorNode * | findNodeNoThrow (IdString aliasName, bool includeShadowNodes=false) const
CompositorShadowNode * | findOrCreateShadowNode (IdString nodeDefName, bool &bCreated)
| Finds a shadow node given it's definition name. More...
CompositorShadowNode * | findShadowNode (IdString nodeDefName) const
| Finds a shadow node instance with a given name. More...
bool | getAmalgamatedProfiling (void) const
CompositorManager2 * | getCompositorManager ()
| Gets the compositor manager (non const) More...
const CompositorManager2 * | getCompositorManager () const
| Gets the compositor manager (const version) More...
Camera * | getDefaultCamera () const
| Gets the default camera passed through mDefaultViewport. More...
const CompositorWorkspaceDef * | getDefinition (void)
bool | getEnabled () const
uint8 | getExecutionMask (void) const
const CompositorChannelVec & | getExternalRenderTargets (void) const
| Usually by convention the RenderTarget[0] is the one we're rendering to. May be empty. More...
TextureGpu * | getFinalTarget (void) const
| Returns the RenderTarget we're rendering to. More...
size_t | getFrameCount (void) const
const CompositorNamedBufferVec & | getGlobalBuffers (void) const
const CompositorChannel & | getGlobalTexture (IdString name) const
IdType | getId () const
| Get the unique id of this object. More...
CompositorWorkspaceListener * | getListener (void) const
const CompositorWorkspaceListenerVec & | getListeners (void) const
const CompositorNodeVec & | getNodeSequence (void) const
const ResourceLayoutMap & | getResourcesLayout (void) const
SceneManager * | getSceneManager () const
const ResourceAccessMap & | getUavsAccess (void) const
const Vector4 & | getViewportModifier (void) const
uint8 | getViewportModifierMask (void) const
bool | isValid (void) const
| Only valid workspaces can update without crashing. More...
void | operator delete (void *ptr)
void | operator delete (void *ptr, const char *, int, const char *)
void | operator delete (void *ptr, void *)
void | operator delete[] (void *ptr)
void | operator delete[] (void *ptr, const char *, int, const char *)
void * | operator new (size_t sz)
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 *ptr)
| placement operator new More...
void * | operator new[] (size_t sz)
void * | operator new[] (size_t sz, const char *file, int line, const char *func)
| array operator new, with debug line info More...
bool | operator() (const IdObject &left, const IdObject &right)
bool | operator() (const IdObject *left, const IdObject *right)
void | reconnectAllNodes (void)
| Reconnects all nodes. More...
void | recreateAllNodes (void)
| Destroys and recreates all nodes. More...
void | removeListener (CompositorWorkspaceListener *listener)
void | resetAllNumPassesLeft (void)
| Resets the number of passes left for every pass (. More...
void | setAmalgamatedProfiling (bool bEnabled)
| When building with OGRE_PROFILING enabled, setting this option to true will cause the profiler to collapse all per-pass profiling information into one group. More...
void | setEnabled (bool bEnabled)
void | setListener (CompositorWorkspaceListener *listener)
void | setViewportModifier (const Vector4 &modifier)
void | setViewportModifierMask (uint8 mask)

## Detailed Description

A compositor workspace is the main interface to render into an RT, be it a RenderWindow or an RTT (Render Texture Target).

Whereas Ogre 1.x needed you to set a Viewport in order to render to an RTT or RW and then call renderTarget->update, now you need to set a workspace definition instead and call workspace->_update().

  Compositors are not just a "fancy effects" system anymore, they tell Ogre how you want to render the scene. You can't render to an RT without setting a compositor!

  A workspace may be instantiated multiple times for different RTs, or using different cameras (i.e. multiple monitors, stereo 3D, etc), while they all will share the same definition. A workspace definition (

See also
  CompositorWorkspaceDef) contains all the information needed by this CompositorWorkspace to instantiate and know which nodes to create and how to connect them. @See CompositorNodeDef A workspace may define global textures that are visible to all of its Node instances.

  If you want to have (e.g.) two monitors rendering the same but with different compositor effects, you will also have to create two different definitions (CompositorWorkspaceDefs)

  The intention of Ogre 2.0's compositor is to ideally have one Workspace per monitor (or per eye) while handling all RTTs inside that workspace with compositor nodes, local and global textures (including manually updated stuff like procedural textures, terrain's auto generated normal maps, etc); but it is also possible to do things the 1.x way: use additional Workspaces for manually rendering and controlling RTTs.

  Users with basic needs (no advanced effects) can

See also
  CompositorManager2::createBasicWorkspaceDef for quickly having a basic definition set for them.

  For more information about Compositors, consult the Ogre 2.0 Porting Manual in the Docs folder.

Author
  Matias N. Goldberg

Version
  1.1

## Constructor & Destructor Documentation

## ◆ CompositorWorkspace()

Ogre::CompositorWorkspace::CompositorWorkspace | ( | IdType | id,
|  | const CompositorWorkspaceDef * | definition,
|  | const CompositorChannelVec & | externalRenderTargets,
|  | SceneManager * | sceneManager,
|  | Camera * | defaultCam,
|  | RenderSystem * | renderSys,
|  | bool | bEnabled,
|  | uint8 | executionMask,
|  | uint8 | viewportModifierMask,
|  | const Vector4 & | vpOffsetScale,
|  | const UavBufferPackedVec * | uavBuffers,
|  | const ResourceLayoutMap * | initialLayouts,
|  | const ResourceAccessMap * | initialUavAccess
| ) |  |

## ◆ ~CompositorWorkspace()

virtual Ogre::CompositorWorkspace::~CompositorWorkspace | ( |  | ) |
| virtual

## Member Function Documentation

## ◆ _beginUpdate()

void Ogre::CompositorWorkspace::_beginUpdate | ( | bool | forceBeginFrame | ) |

Call before _update unless the final render target is not a render window.

Parameters

  forceBeginFrame | Forces a beginFrame call to the D3D9 API, even if the final render target is not a RenderWindow (not recommended). To avoid forcing extra begin/end frame pairs, update your manual workspaces inside @CompositorWorkspaceListener::workspacePreUpdate (performance optimization)

## ◆ _endUpdate()

void Ogre::CompositorWorkspace::_endUpdate | ( | bool | forceEndFrame | ) |

Call after _update unless the final render target is not a render window.

Parameters

  forceEndFrame | @See _beginUpdate !!!WARNING!!! Forcing an end frame can cause API issues w/ D3D9 if Ogre had already issued a begin frame automatically (i.e. if you're calling from inside a RenderTarget or CompositorWorkspace listener). These API issues may not manifest on all HW/Driver combinations, making it hard to detect (if you're on D3D, use the Debug Runtimes)

## ◆ _notifyBarriersDirty()

void Ogre::CompositorWorkspace::_notifyBarriersDirty | ( | void |  | ) |
| inline

## ◆ _swapFinalTarget()

void Ogre::CompositorWorkspace::_swapFinalTarget | ( | vector< TextureGpu * >::type & | swappedTargets | ) |

In the case of RenderWindows, swaps/copies/flips the front with the back buffer.

In the case of RenderTextures, resolves FSAA (unless it's tagged as explicit resolve, or its contents haven't changed since the last resolve)

Remarks
  Call this after _endUpdate

## ◆ _update()

void Ogre::CompositorWorkspace::_update | ( | void |  | ) |

Updates the workspace's nodes.

Remarks
  If you're calling this manually, it may be possible you first need to call RenderSystem::_beginFrameOnce if it wasn't called by OGRE already. You might also need to enclose the _update calls with _beginUpdate( true ) and _endUpdate( true ) if you're having issues.

## ◆ _validateFinalTarget()

void Ogre::CompositorWorkspace::_validateFinalTarget | ( | void |  | ) |

For compatibility with D3D9, forces a device lost check on the RenderWindow, so that BeginScene doesn't fail.

## ◆ addListener()

void Ogre::CompositorWorkspace::addListener | ( | CompositorWorkspaceListener * | listener | ) |

## ◆ fillUavDependenciesForNextWorkspace()

void Ogre::CompositorWorkspace::fillUavDependenciesForNextWorkspace | ( | ResourceLayoutMap & | outInitialLayouts,
|  | ResourceAccessMap & | outInitialUavAccess
| ) |  | const

When two workspaces work on the same channels/textures, to avoid race conditions in Compute Shaders each workspace needs to know what the the previous workspace did; and that information must be supplied during workspace creation.

This function fills outInitialLayouts & outInitialUavAccess with the state in which the UAVs will be when 'this' is done executing; and can be used by the next workspace.

In code:

CompositorWorkspace *first, *next;
first = compositorManager->addWorkspace( sceneManager, channels,
camera, "CompoName_A", true );
ResourceLayoutMap initialLayouts;
ResourceAccessMap initialAccess;
first->fillUavDependenciesForNextWorkspace( initialLayouts, initialAccess );
after = compositorManager->addWorkspace( sceneManager, channels,
camera, "CompoName_B", true, 0,
&initialLayouts, &initialAccess );

Remarks
  Compute shaders are guaranteed to start in order; but they're not guaranteed to be processed in sequence nor finish in order unless explicitly requested. This is why this function exists.

Parameters

  outInitialLayouts | [in/out] Fills outInitialLayouts. Previous content is not removed; but we may overwrite some entries.
  outInitialUavAccess | [in/out] Fills outInitialUavAccess. Previous content is not removed; but we may overwrite some entries.

## ◆ findCamera()

Camera* Ogre::CompositorWorkspace::findCamera | ( | IdString | cameraName | ) | const

Finds a camera in the scene manager we have.

## ◆ findNode()

CompositorNode* Ogre::CompositorWorkspace::findNode | ( | IdString | aliasName,
|  | bool | includeShadowNodes = `false`
| ) |  | const

Finds a node instance with the given aliased name.

Remarks
  Linear search O(N)

Parameters

  aliasName | Name of the node instance (they're unique)
  includeShadowNodes | When true, also looks for ShadowNodes with that name, if the instance doesn't exists, it will not be created (default: false). @See findShadowNode When a Node has the same name of a Shadow Node, the Node takes precedence.

Returns
  Regular version: Valid pointer. Throws exception if not found. NoThrow version: Null if not found. Valid pointer otherwise.

## ◆ findNodeNoThrow()

CompositorNode* Ogre::CompositorWorkspace::findNodeNoThrow | ( | IdString | aliasName,
|  | bool | includeShadowNodes = `false`
| ) |  | const

## ◆ findOrCreateShadowNode()

CompositorShadowNode* Ogre::CompositorWorkspace::findOrCreateShadowNode | ( | IdString | nodeDefName,
|  | bool & | bCreated
| ) |  |

Finds a shadow node given it's definition name.

If it doesn't exist, creates one. Note that unlike nodes, there can only be one ShadowNode instance per definition (in the same workspace)

Remarks
  Performs a linear search O(N). There aren't many ShadowNodes active in a workspace to justify a better container (plus we mostly iterate through it).

  Throws if the shadow definition doesn't exist.

Parameters

  nodeDefName | Name of the definition.
  bCreated | [out] Set to true if we had to create a new shadow node (it didn't exist)

Returns
  ShadowNode pointer

## ◆ findShadowNode()

CompositorShadowNode* Ogre::CompositorWorkspace::findShadowNode | ( | IdString | nodeDefName | ) | const

Finds a shadow node instance with a given name.

Note that unlike nodes, there can only be one ShadowNode instance per definition (in the same workspace)

Remarks
  Performs a linear search O(N). There aren't many ShadowNodes active in a workspace to justify a better container (plus we mostly iterate through it).

Parameters

  nodeDefName | Name of the definition.

Returns
  ShadowNode pointer. Null if not found.

## ◆ getAmalgamatedProfiling()

bool Ogre::CompositorWorkspace::getAmalgamatedProfiling | ( | void |  | ) | const
| inline

## ◆ getCompositorManager() [1/2]

CompositorManager2* Ogre::CompositorWorkspace::getCompositorManager | ( |  | ) |

Gets the compositor manager (non const)

## ◆ getCompositorManager() [2/2]

const CompositorManager2* Ogre::CompositorWorkspace::getCompositorManager | ( |  | ) | const

Gets the compositor manager (const version)

## ◆ getDefaultCamera()

Camera* Ogre::CompositorWorkspace::getDefaultCamera | ( |  | ) | const
| inline

Gets the default camera passed through mDefaultViewport.

## ◆ getDefinition()

const CompositorWorkspaceDef* Ogre::CompositorWorkspace::getDefinition | ( | void |  | ) |
| inline

## ◆ getEnabled()

bool Ogre::CompositorWorkspace::getEnabled | ( |  | ) | const
| inline

## ◆ getExecutionMask()

uint8 Ogre::CompositorWorkspace::getExecutionMask | ( | void |  | ) | const
| inline

## ◆ getExternalRenderTargets()

const CompositorChannelVec& Ogre::CompositorWorkspace::getExternalRenderTargets | ( | void |  | ) | const
| inline

Usually by convention the RenderTarget[0] is the one we're rendering to. May be empty.

## ◆ getFinalTarget()

TextureGpu* Ogre::CompositorWorkspace::getFinalTarget | ( | void |  | ) | const

Returns the RenderTarget we're rendering to.

May be null.

See also
  getExternalRenderTargets

## ◆ getFrameCount()

size_t Ogre::CompositorWorkspace::getFrameCount | ( | void |  | ) | const

## ◆ getGlobalBuffers()

const CompositorNamedBufferVec& Ogre::CompositorWorkspace::getGlobalBuffers | ( | void |  | ) | const
| inline

## ◆ getGlobalTexture()

const CompositorChannel& Ogre::CompositorWorkspace::getGlobalTexture | ( | IdString | name | ) | const

## ◆ getId()

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

Get the unique id of this object.

## ◆ getListener()

CompositorWorkspaceListener* Ogre::CompositorWorkspace::getListener | ( | void |  | ) | const

Deprecated:
  use getListeners instead

## ◆ getListeners()

const CompositorWorkspaceListenerVec& Ogre::CompositorWorkspace::getListeners | ( | void |  | ) | const
| inline

## ◆ getNodeSequence()

const CompositorNodeVec& Ogre::CompositorWorkspace::getNodeSequence | ( | void |  | ) | const
| inline

## ◆ getResourcesLayout()

const ResourceLayoutMap& Ogre::CompositorWorkspace::getResourcesLayout | ( | void |  | ) | const
| inline

## ◆ getSceneManager()

SceneManager* Ogre::CompositorWorkspace::getSceneManager | ( |  | ) | const
| inline

## ◆ getUavsAccess()

const ResourceAccessMap& Ogre::CompositorWorkspace::getUavsAccess | ( | void |  | ) | const
| inline

## ◆ getViewportModifier()

const Vector4& Ogre::CompositorWorkspace::getViewportModifier | ( | void |  | ) | const
| inline

## ◆ getViewportModifierMask()

uint8 Ogre::CompositorWorkspace::getViewportModifierMask | ( | void |  | ) | const
| inline

## ◆ isValid()

bool Ogre::CompositorWorkspace::isValid | ( | void |  | ) | const
| inline

Only valid workspaces can update without crashing.

## ◆ operator delete() [1/3]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete | ( | void * | ptr | ) |
| inlineinherited

## ◆ operator delete() [2/3]

template<class Alloc >

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

## ◆ operator delete() [3/3]

template<class Alloc >

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

## ◆ operator delete[]() [1/2]

template<class Alloc >

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

## ◆ operator delete[]() [2/2]

template<class Alloc >

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

## ◆ operator new() [1/3]

template<class Alloc >

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

## ◆ operator new() [2/3]

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

## ◆ operator new() [3/3]

template<class Alloc >

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

placement operator new

## ◆ operator new[]() [1/2]

template<class Alloc >

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

## ◆ operator new[]() [2/2]

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

## ◆ operator()() [1/2]

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

## ◆ operator()() [2/2]

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

## ◆ reconnectAllNodes()

void Ogre::CompositorWorkspace::reconnectAllNodes | ( | void |  | ) |

Reconnects all nodes.

Use this function if you only altered the channel connections between nodes, but didn't add new ones or removed existing nodes.

Remarks
  If there is a "loose node" (its inputs are not fully connected), disable it (

See also
  CompositorNode::setEnabled)

## ◆ recreateAllNodes()

void Ogre::CompositorWorkspace::recreateAllNodes | ( | void |  | ) |

Destroys and recreates all nodes.

TODO: Only revalidate nodes adjacent to those that were invalidated, to avoid recreating so many D3D/GL resources (local textures) which is important for GUI editors.

## ◆ removeListener()

void Ogre::CompositorWorkspace::removeListener | ( | CompositorWorkspaceListener * | listener | ) |

## ◆ resetAllNumPassesLeft()

void Ogre::CompositorWorkspace::resetAllNumPassesLeft | ( | void |  | ) |

Resets the number of passes left for every pass (.

See also
  CompositorPassDef::mNumInitialPasses) Useful when you have a few starting 'initialization' passes and you want to reset them.

## ◆ setAmalgamatedProfiling()

void Ogre::CompositorWorkspace::setAmalgamatedProfiling | ( | bool | bEnabled | ) |
| inline

When building with OGRE_PROFILING enabled, setting this option to true will cause the profiler to collapse all per-pass profiling information into one group.

This is useful if you want to know how much (e.g.) frustum culling is taking overall (all passes combined) rather than knowing how much frustum culling is taking for each pass.

Parameters

  bEnabled | True to collapse all per-pass info into a global one. Default is false.

## ◆ setEnabled()

void Ogre::CompositorWorkspace::setEnabled | ( | bool | bEnabled | ) |
| inline

## ◆ setListener()

void Ogre::CompositorWorkspace::setListener | ( | CompositorWorkspaceListener * | listener | ) |

Deprecated:
  use addListener and removeListener instead

## ◆ setViewportModifier()

void Ogre::CompositorWorkspace::setViewportModifier | ( | const Vector4 & | modifier | ) |
| inline

## ◆ setViewportModifierMask()

void Ogre::CompositorWorkspace::setViewportModifierMask | ( | uint8 | mask | ) |
| inline

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

- OgreCompositorWorkspace.h

Ogre::CompositorWorkspace::CompositorWorkspace
CompositorWorkspace(IdType id, const CompositorWorkspaceDef *definition, const CompositorChannelVec &externalRenderTargets, SceneManager *sceneManager, Camera *defaultCam, RenderSystem *renderSys, bool bEnabled, uint8 executionMask, uint8 viewportModifierMask, const Vector4 &vpOffsetScale, const UavBufferPackedVec *uavBuffers, const ResourceLayoutMap *initialLayouts, const ResourceAccessMap *initialUavAccess)
Ogre::ResourceAccessMap
StdMap< GpuTrackedResource *, ResourceAccess::ResourceAccess > ResourceAccessMap
Definition: OgreResourceTransition.h:138
Ogre::ResourceLayoutMap
StdMap< GpuTrackedResource *, ResourceLayout::Layout > ResourceLayoutMap
Definition: OgreResourceTransition.h:137