OGRE-Next  4.0.0unstable
Object-Oriented Graphics Rendering Engine
Ogre::CompositorWorkspace Class Reference

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:

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 ResourceStatusMap *initialLayouts)
 
virtual ~CompositorWorkspace ()
 
void _beginUpdate (bool forceBeginFrame, const bool bInsideAutoreleasePool=false)
 Call before _update() unless the final render target is not a render window. More...
 
void _endUpdate (bool forceEndFrame, const bool bInsideAutoreleasePool=false)
 Call after _update() unless the final render target is not a render window. More...
 
void _notifyBarriersDirty ()
 
void _swapFinalTarget (vector< TextureGpu * >::type &swappedTargets)
 In the case of RenderWindows, swaps/copies/flips the front with the back buffer. More...
 
void _update (const bool bInsideAutoreleasePool=false)
 Updates the workspace's nodes. More...
 
void _validateFinalTarget ()
 For compatibility with D3D9, forces a device lost check on the RenderWindow, so that BeginScene doesn't fail. More...
 
void addListener (CompositorWorkspaceListener *listener)
 
void fillPassesUsingRenderWindows (PassesByRenderWindowMap &passesUsingRenderWindows)
 Fills the input map + vector with all the passes that use a window, classified per window. More...
 
CamerafindCamera (IdString cameraName) const
 Finds a camera in the scene manager we have. More...
 
CompositorNodefindNode (IdString aliasName, bool includeShadowNodes=false) const
 Finds a node instance with the given aliased name. More...
 
CompositorNodefindNodeNoThrow (IdString aliasName, bool includeShadowNodes=false) const
 
CompositorShadowNodefindOrCreateShadowNode (IdString nodeDefName, bool &bCreated)
 Finds a shadow node given its definition name. More...
 
CompositorShadowNodefindShadowNode (IdString nodeDefName) const
 Finds a shadow node instance with a given name. More...
 
bool getAmalgamatedProfiling () const
 
CompositorManager2getCompositorManager ()
 Gets the compositor manager (non const) More...
 
const CompositorManager2getCompositorManager () const
 Gets the compositor manager (const version) More...
 
CameragetDefaultCamera () const
 Gets the default camera passed through mDefaultViewport. More...
 
const CompositorWorkspaceDefgetDefinition ()
 
bool getEnabled () const
 
uint8 getExecutionMask () const
 
const CompositorChannelVecgetExternalRenderTargets () const
 Usually by convention the RenderTarget[0] is the one we're rendering to. May be empty. More...
 
TextureGpugetFinalTarget () const
 Returns the RenderTarget we're rendering to. More...
 
size_t getFrameCount () const
 
const CompositorNamedBufferVecgetGlobalBuffers () const
 
const CompositorChannelgetGlobalTexture (IdString name) const
 
CompositorWorkspaceListenergetListener () const
 
const CompositorWorkspaceListenerVecgetListeners () const
 
const CompositorNodeVecgetNodeSequence () const
 
SceneManagergetSceneManager () const
 
const Vector4getViewportModifier () const
 
uint8 getViewportModifierMask () const
 
bool isValid () const
 Only valid workspaces can update without crashing. More...
 
void reconnectAllNodes ()
 Reconnects all nodes. More...
 
void recreateAllNodes ()
 Destroys and recreates all nodes. More...
 
void removeListener (CompositorWorkspaceListener *listener)
 
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 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 setExecutionMask (uint8 executionMask)
 
void setListener (CompositorWorkspaceListener *listener)
 
void setViewportModifier (const Vector4 &modifier)
 
void setViewportModifierMask (uint8 mask)
 
- 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

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 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 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 ResourceStatusMap initialLayouts 
)

◆ ~CompositorWorkspace()

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

Member Function Documentation

◆ _beginUpdate()

void Ogre::CompositorWorkspace::_beginUpdate ( bool  forceBeginFrame,
const bool  bInsideAutoreleasePool = false 
)

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

Parameters
forceBeginFrameForces 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)
bInsideAutoreleasePool

If manually updating the workspace, leave this to default.

Relevant only in Metal: If we're not inside an autorelease pool, we automatically wrap the call into one. Otherwise we will leak

◆ _endUpdate()

void Ogre::CompositorWorkspace::_endUpdate ( bool  forceEndFrame,
const bool  bInsideAutoreleasePool = false 
)

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

If manually updating the workspace, leave this to default.

Relevant only in Metal: If we're not inside an autorelease pool, we automatically wrap the call into one. Otherwise we will leak.

◆ _notifyBarriersDirty()

void Ogre::CompositorWorkspace::_notifyBarriersDirty ( )

◆ _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 ( const bool  bInsideAutoreleasePool = false)

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.
Parameters
bInsideAutoreleasePool

If manually updating the workspace, leave this to default.

Relevant only in Metal: If we're not inside an autorelease pool, we automatically wrap the call into one. Otherwise we will leak

◆ _validateFinalTarget()

void Ogre::CompositorWorkspace::_validateFinalTarget ( )

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)

◆ fillPassesUsingRenderWindows()

void Ogre::CompositorWorkspace::fillPassesUsingRenderWindows ( PassesByRenderWindowMap passesUsingRenderWindows)

Fills the input map + vector with all the passes that use a window, classified per window.

Remarks
We do not support passes that write to more than one render window at once (this should not be supported by APIs anyway)

◆ 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
aliasNameName of the node instance (they're unique)
includeShadowNodesWhen 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 its 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
nodeDefNameName 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
nodeDefNameName of the definition.
Returns
ShadowNode pointer. Null if not found.

◆ getAmalgamatedProfiling()

bool Ogre::CompositorWorkspace::getAmalgamatedProfiling ( ) 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 ( )
inline

◆ getEnabled()

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

◆ getExecutionMask()

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

◆ getExternalRenderTargets()

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

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

◆ getFinalTarget()

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

Returns the RenderTarget we're rendering to.

May be null.

See also
getExternalRenderTargets

◆ getFrameCount()

size_t Ogre::CompositorWorkspace::getFrameCount ( ) const

◆ getGlobalBuffers()

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

◆ getGlobalTexture()

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

◆ getListener()

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

◆ getListeners()

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

◆ getNodeSequence()

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

◆ getSceneManager()

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

◆ getViewportModifier()

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

◆ getViewportModifierMask()

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

◆ isValid()

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

Only valid workspaces can update without crashing.

◆ reconnectAllNodes()

void Ogre::CompositorWorkspace::reconnectAllNodes ( )

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

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

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.

◆ 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
bEnabledTrue to collapse all per-pass info into a global one. Default is false.

◆ setEnabled()

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

◆ setExecutionMask()

void Ogre::CompositorWorkspace::setExecutionMask ( uint8  executionMask)
inline

◆ setListener()

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

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