MRenderer Class Reference

#include <MViewport2Renderer.h>

Class Description

Main interface class to the Viewport 2.0 renderer.

+ Examples:

Public Types

enum  MGPUMemType { kMemTexture, kMemAll }
 GPU memory type. More...
 
typedef void(* NotificationCallback) (MDrawContext &context, void *clientData)
 Definition for callback function for addNotification()
 

Public Member Functions

MHWRender::DrawAPI drawAPI () const
 Returns the current drawing API. More...
 
bool drawAPIIsOpenGL () const
 Method will indicate whether the current drawing API is OpenGL or not. More...
 
unsigned int drawAPIVersion () const
 Method will return the version of drawing API. More...
 
void * GPUDeviceHandle () const
 Method will return a pointer to the GPU "device". More...
 
unsigned int GPUmaximumVertexBufferSize () const
 Method to return the maximum number of vertices allowed in a vertex buffer by the GPU device. More...
 
unsigned int GPUmaximumPrimitiveCount () const
 Method to return the maximum number of primitives that can be drawn per draw call by the GPU device. More...
 
void GPUmaximumOutputTargetSize (unsigned int &w, unsigned int &h) const
 Retrieve the maximum allowable dimensions for output target by the GPU device. More...
 
MInt64 GPUtotalMemorySize () const
 Retrieve the total amount of memory on the GPU device in bytes. More...
 
MInt64 GPUUsedMemorySize (MGPUMemType type) const
 Retrieve the amount of Maya occupied GPU memory in bytes. More...
 
MFragmentManagergetFragmentManager () const
 Access the fragment manager. More...
 
const MShaderManagergetShaderManager () const
 Access the shader manager. More...
 
const MRenderTargetManagergetRenderTargetManager () const
 Access the render target manager. More...
 
bool copyTargetToScreen (const MRenderTarget *renderTarget)
 Copy a render target to the screen. More...
 
MTextureManagergetTextureManager () const
 Access the texture manager. More...
 
MStatus registerOverride (const MRenderOverride *roverride)
 Register the override as being usable by the renderer. More...
 
MStatus deregisterOverride (const MRenderOverride *roverride)
 Deregister an existing render override on the renderer. More...
 
const MRenderOverridefindRenderOverride (const MString &name)
 Return a reference to an existing render override registered with the renderer. More...
 
const MString activeRenderOverride () const
 Get the name of the active override. More...
 
unsigned int renderOverrideCount ()
 Get the number of registered render overrides. More...
 
MStatus setRenderOverrideName (const MString &name)
 Set the name of a render override (MHWRender::MRenderOverride) for batch rendering. More...
 
MString renderOverrideName (MStatus *ReturnStatus=NULL) const
 Get the current render override name used for batch rendering. More...
 
MStatus registerScriptCallback (MRenderScriptCallback *callback)
 Register a MRenderScriptCallback that can be then from a script fragment. More...
 
MStatus deregisterScriptCallback (MRenderScriptCallback *callback)
 Deregister a MRenderScriptCallback and delete the registered instance. More...
 
MStatus holdGPUMemory (MInt64 sizeInBytes, MInt64 *evictedGPUMemSize=NULL)
 Inform Maya that the total amount of GPU memory allocated by a plug-in is increasing by sizeInBytes. More...
 
MStatus releaseGPUMemory (MInt64 sizeInBytes)
 Inform Maya that the total amount of GPU memory allocated by a plug-in is decreasing by sizeInBytes. More...
 
void getStandardViewportOperations (MRenderOperationList &operations) const
 Return a list of new MRenderOperations representing the standard viewport pipeline. More...
 
void setOutputTargetOverrideSize (unsigned int w, unsigned int h)
 This method allows rendering to occur to an offscreen target which differs from the interactive 3d viewport size. More...
 
void getOutputTargetOverrideSize (int &w, int &h)
 Get the override dimensions set for the final output target. More...
 
void unsetOutputTargetOverrideSize ()
 Will unset any override dimensions set fot the final output target. More...
 
MStatus outputTargetSize (unsigned int &w, unsigned int &h) const
 Return the current dimensions for the output target. More...
 
bool setLightRequiresShadows (MObject obj, bool flag)
 The Viewport 2.0 renderer has a light limit option which is used to determine the number of lights used for computing illumination. More...
 
MStatus addNotification (NotificationCallback notification, const MString &name, const MString semanticLocation, void *clientData)
 Add a notification callback to the rendering pipeline. More...
 
MStatus removeNotification (const MString &name, const MString &semanticLocation)
 Remove a notification operation from the rendering pipeline. More...
 
unsigned int notificationCount (const MString &semanticLocation) const
 Returns the number of notifications that have been set for a given semantic location. More...
 
bool presentOnScreen () const
 Returns whether the contents rendered by VP2 will be presented to on-screen buffers when running Maya in interactive mode. More...
 
void setPresentOnScreen (bool val)
 Set whether the contents rendered by VP2 will be presented to on-screen buffers when running Maya in interactive mode. More...
 
bool useGradient () const
 Returns whether a gradient is being used to clear the background color. More...
 
MColor clearColor () const
 Returns the first clear color. More...
 
MColor clearColor2 () const
 Return the second clear color. More...
 

Static Public Member Functions

static MRenderertheRenderer (bool initializeRenderer=true)
 Returns a static pointer to the renderer. More...
 
static void disableChangeManagementUntilNextRefresh ()
 Calling this method will cause Viewport 2.0 to stop processing all changes to the Maya scene until the next viewport refresh. More...
 
static void setGeometryDrawDirty (MObject obj, bool topologyChanged=true)
 Notify the Viewport 2.0 renderer that the geometry (size, shape, etc.) of obj has changed, causing the object to be updated in the viewport. More...
 
static void needEvaluateAllLights ()
 Notify the Viewport 2.0 renderer that it should evaluate all lights marked dirty, regardless of the light limit. More...
 
static void setLightsAndShadowsDirty ()
 Notify the Viewport 2.0 renderer that something has changed which requires re-evaluation of lighting and shadows. More...
 

Member Enumeration Documentation

GPU memory type.

Enumerator
kMemTexture 

GPU texture used memory.

kMemAll 

GPU total used memory.

Member Function Documentation

MRenderer * theRenderer ( bool  initializeRenderer = true)
static

Returns a static pointer to the renderer.

Parameters
[in]initializeRendererFully initialize the renderer.

When requesting the renderer to fully initialize, the internal renderer will be created and initialized. In some cases, a plugin may only want to access the renderer without having to initialize it. This can be useful for plugins that are auto-loaded when Maya start, and only need an access to the renderer to register their render overrides.

Returns
Pointer to the renderer.
+ Examples:
MHWRender::DrawAPI drawAPI ( ) const
bool drawAPIIsOpenGL ( ) const
unsigned int drawAPIVersion ( ) const

Method will return the version of drawing API.

Returns
Draw API version, or 0 if the renderer is not initialized properly.
void * GPUDeviceHandle ( ) const

Method will return a pointer to the GPU "device".

In the case that the drawing API is OpenGL then the "device" is a handle to an OpenGL context. In the case that the drawing API is DirectX then the "device" is a pointer to a DirectX device.

It is imperative that when a programmer makes any modifications to the device or context that the pre-modified state always be restored after the changes are no longer required. If this is not done then Maya's internal state tracking system will become inconsistent. This can result in unpredictable rendering behaviour.

Returns
A void pointer to the device or context. The pointer must be cast to the correct data type depending on the draw API. For example a cast to an HGLRC would be required to get an OpenGL context on Windows platforms.

If the renderer has not been initialized a NULL pointer will be returned.

+ Examples:
unsigned int GPUmaximumVertexBufferSize ( ) const

Method to return the maximum number of vertices allowed in a vertex buffer by the GPU device.

Returns
Maximum value. 0 if device has not been initialized.
unsigned int GPUmaximumPrimitiveCount ( ) const

Method to return the maximum number of primitives that can be drawn per draw call by the GPU device.

Returns
Maximum value. 0 if device has not been initialized.
void GPUmaximumOutputTargetSize ( unsigned int &  w,
unsigned int &  h 
) const

Retrieve the maximum allowable dimensions for output target by the GPU device.

These dimensions are not directly tied to the on-screen display resolution.

Parameters
[out]wMaximum width
[out]hMaximum height
MInt64 GPUtotalMemorySize ( ) const

Retrieve the total amount of memory on the GPU device in bytes.

Returns
The total amount of memory on the GPU device in bytes.
MInt64 GPUUsedMemorySize ( MGPUMemType  type) const

Retrieve the amount of Maya occupied GPU memory in bytes.

This size is not the accurate gpu memory current in use queried from system, but the number that tracked and used by Maya.

Parameters
[in]typeThe type of GPU memory for query.

kMemTexture returns the texture gpu memory used by Maya. kMemAll returns the total gpu memory used by Maya.

Returns
The amount of Maya occupied GPU memory in bytes. returns -1 when query failed.
const MRenderTargetManager * getRenderTargetManager ( ) const

Access the render target manager.

The render target manager can be used to produce MRenderTarget objects which may be assigned to MRenderOperation objects as output target overrides.

Returns
A pointer to the manager of NULL if the renderer is not initialized properly.
+ Examples:
bool copyTargetToScreen ( const MRenderTarget renderTarget)

Copy a render target to the screen.

If the target's dimensions are not the same as the active viewport it will be scaled up or down as necessary to fill the entire viewport.

Parameters
[in]renderTargetRender target to copy.
Returns
True if copy was successful.
const MString activeRenderOverride ( ) const

Get the name of the active override.

There can only be one active override at any given time and that override must exist be registered with the renderer.

Returns
Name of active override. If none an empty string will be returned.
+ Examples:
unsigned int renderOverrideCount ( )

Get the number of registered render overrides.

Returns
Number of registered overrides
MStatus setRenderOverrideName ( const MString name)

Set the name of a render override (MHWRender::MRenderOverride) for batch rendering.

Parameters
[in]nameName of the override.
Returns
Status code
Status Codes:
MString renderOverrideName ( MStatus ReturnStatus = NULL) const

Get the current render override name used for batch rendering.

If there is no override then an empty string will be returned

Parameters
[out]ReturnStatusreturn status.
Returns
Override name.
Status Codes: Currently always returns MS::kSuccess.
MStatus registerScriptCallback ( MRenderScriptCallback callback)

Register a MRenderScriptCallback that can be then from a script fragment.

Parameters
[in]callbackAn instance of the callback class to register.
Returns
Status code
Status Codes:
MStatus deregisterScriptCallback ( MRenderScriptCallback callback)

Deregister a MRenderScriptCallback and delete the registered instance.

The callback will no longer be callable from a script fragment once deregistered.

Parameters
[in]callbackAn instance of the callback class to register.
Returns
Status code
Status Codes:
  • MS::kSuccess The script callback was successfully deregistered.
  • MS::kFailure The script callback could not be deregistered.
MStatus holdGPUMemory ( MInt64  sizeInBytes,
MInt64 *  evictedGPUMemSize = NULL 
)

Inform Maya that the total amount of GPU memory allocated by a plug-in is increasing by sizeInBytes.

To avoid running out of GPU memory Maya may move buffers allocated by Maya from GPU memory to system memory. This system relies on Maya accurately tracking the amount of GPU memory being used. User plug-ins can log their memory usage using holdGPUMemory and releaseGPUMemory.

Maya has no ability to move user allocated GPU buffers to system memory, so all user allocated buffers take priority over any Maya allocated buffer. For this reason GPU buffers which are unlikely to be re-used should be deallocated immediately rather than held.

To prevent a GPU buffer allocated by Maya from being moved to system memory see MVertexBuffer::lockResourceHandle().

A call to holdGPUMemory may cause Maya to move buffers allocated by Maya from GPU memory to system memory. This may negatively impact overall performance in two ways. First, the call to holdGPUMemory itself may take a significant amount of time to copy the GPU buffer. Second, future rendering calls which rely on that buffer will be slower because resources must be moved from system memory to GPU memory for rendering.

If a non-null evictedGPUMemSize is given, it will be set to the size of GPU memory moved to system memory during this API call. evictedGPUMemSize of zero does not mean the call failed, it just means that we didn't need to evict any internal buffers from GPU to system.

Parameters
[in]sizeInBytesThe size of the allocation being held in bytes
[out]evictedGPUMemSizeThe size of GPU memory moved to system memory
Returns
Status code
Status Codes:
+ Examples:
MStatus releaseGPUMemory ( MInt64  sizeInBytes)

Inform Maya that the total amount of GPU memory allocated by a plug-in is decreasing by sizeInBytes.

See MRenderer::holdGPUMemory for more information.

Parameters
[in]sizeInBytesThe size of the allocation being released in bytes
Returns
Status code
Status Codes:
+ Examples:
void getStandardViewportOperations ( MRenderOperationList operations) const

Return a list of new MRenderOperations representing the standard viewport pipeline.

The list is not cleared by this method before it is filled. If any operation already exist in the list the standard operations will be appended to the end of the list.

Parameters
[out]operationsThe operation list that will be populated with standard operations.
+ Examples:
void setOutputTargetOverrideSize ( unsigned int  w,
unsigned int  h 
)

This method allows rendering to occur to an offscreen target which differs from the interactive 3d viewport size.

The general purpose for this method is usage in conjunction with target read-back used for capturing sequences of images to disk. The key additional option is the ability to explicitly set the output target size as opposed to relying on attempting to resize a viewport to get an appropriate size.

For this purpose, it can be used in conjunction with a post render notification via the MRenderer::addNotification() interface.

For example the following can be done:

Note that when the override is no longer required the method MRenderer::unsetOutputTargetOverrideSize() should be called.

The maximum allowable target dimensions can be queried using the MRenderer::GPUmaximumOutputTargetSize() method.

This override affects neither batch rendering nor playblast which have their own explicit output target size controls.

Parameters
[in]wWidth of the output target
[in]hHeight of the output target
+ Examples:
void getOutputTargetOverrideSize ( int &  w,
int &  h 
)

Get the override dimensions set for the final output target.

If the values have never been set or if MRenderer::unsetOutputTargetOverrideSize() is used to clear the values then the dimensions returned with be (-1,-1) respectively for the width and height values.

Parameters
[out]wWidth of the output target. -1 if not set.
[out]hHeight of the output target. -1 if not set.
void unsetOutputTargetOverrideSize ( )

Will unset any override dimensions set fot the final output target.

The values stored will be set to (-1,-1) respectively for width and height

+ Examples:
MStatus outputTargetSize ( unsigned int &  w,
unsigned int &  h 
) const

Return the current dimensions for the output target.

Parameters
[out]wWidth of the output target
[out]hHeight of the output target
Returns
MStatus::kSuccess method was successful
+ Examples:
void disableChangeManagementUntilNextRefresh ( )
static

Calling this method will cause Viewport 2.0 to stop processing all changes to the Maya scene until the next viewport refresh.

Upon the next viewport refresh, all existing scene information (geometry, textures, shaders, etc.) stored for Viewport 2.0 will be deleted and then rebuilt.

This method can be used to prevent overhead from Viewport 2.0 from affecting the performance of complex scene operations which change large parts of the scene without needing the viewport to update.

This method may only be called from the main thread.

+ Examples:
void setGeometryDrawDirty ( MObject  obj,
bool  topologyChanged = true 
)
static

Notify the Viewport 2.0 renderer that the geometry (size, shape, etc.) of obj has changed, causing the object to be updated in the viewport.

Note that this method does NOT perform any DG evaluation when it is called. This method is an extention of the dirty propagation system. It adds obj to the list of objects which must be updated before the next frame is rendered. The actual evaluation does not occur until the next viewport refresh. This method is threadsafe. The viewport refresh will occur asynchronously. Multiple calls to this method will get merged. It's not necessary to call this method when assigning new material, since Maya automatically tracks material assignment.

Parameters
[in]objDAG object which has been modified.
[in]topologyChangedhas the object topology changed
+ Examples:
void needEvaluateAllLights ( )
static

Notify the Viewport 2.0 renderer that it should evaluate all lights marked dirty, regardless of the light limit.

For example, if there are 8 lights accessible because of the Viewport 2.0 light limit option, Only the first 8 non-ambient lights created will be evaluated. Call this method to instruct Viewport 2.0 to evaluate all dirty lights regardless of the light limit option.

Note that this method does NOT perform any DG evaluation when it is called. The actual evaluation does not occur until the next viewport refresh. This method is threadsafe. The viewport refresh will occur asynchronously. Multiple calls to this method will get merged.

Call this method may decrease performance in Viewport 2.0 during the next viewport refresh. Once this method is called, all unused lights that are marked dirty will be evaluated in the next viewport refresh.

An example application of this method is to obtain light information while ignoring the light limit. If this method is not called, information for unused lights cannot be obtained via MDrawContext, even if LightFilter is set to kFilteredToLightLimit. This is because unused lights are not evaluated automatically by Viewport 2.0 by default.

+ Examples:
void setLightsAndShadowsDirty ( )
static

Notify the Viewport 2.0 renderer that something has changed which requires re-evaluation of lighting and shadows.

This will trigger an update of all active lights in the scene which will also force a recomputation of all active shadow maps.

Note that this method does NOT perform any DG evaluation when it is called. This method is an extention of the dirty propagation system. It simply marks all lights as needing to be updated before the next frame is rendered. The actual evaluation does not occur until the next viewport refresh. This method is threadsafe. The viewport refresh will occur asynchronously. Multiple calls to this method will get merged.

An example use of this method would be for advanced shaders which alter the geometry of objects through displacement and thus would alter the shadowing caused by objects that use the shader. Since the geometry of the object itself is not changing Maya cannot automatically update the lights and shadows. Thus the plug-in must mark them dirty manually.

+ Examples:
bool setLightRequiresShadows ( MObject  object,
bool  flag 
)

The Viewport 2.0 renderer has a light limit option which is used to determine the number of lights used for computing illumination.

If the light is not used for illumination then the associated shadow map contents will not be computed.

This method allows for plug-in writers to indicate that the shadow map contents for a given light are required, regardless of the light limit.

The method does not force a shadow map evaluation, nor does it mark the shadow map contents as being dirty. Instead, the next time that shadow maps require updating, the renderer will only ensure that the shadow maps for the given light are recomputed as necessary.

The contents of the shadow map may not always require an update. For example the light contents may already be up-to-date, or renderer options may indicate to not render with shadows enabled. In cases like this no additional action will be performed.

Parameters
[in]objectLight to request shadow update for
[in]flagIndicate if an update is requested. When set to true a request is added, and when set false any existing request is removed.
Returns
True if the method added or removed the request successfully
+ Examples:
MStatus addNotification ( NotificationCallback  notification,
const MString name,
const MString  semanticLocation,
void *  clientData 
)

Add a notification callback to the rendering pipeline.

If a notification with the same name and location has already been specified then no new notification will be added.

For the common case, when no MRenderOverride is specified, there will be one scene pass per render. The basic order of rendering would be:

  • Begin rendering, and invoke any notifications specified.
  • Begin scene pass rendering, and invoke any notifications specified.
  • End scene pass rendering, and invoke any notifications specified.
  • End rendering, and invoke any notifications specified.

If there are multiple scene passes for a given render then notifications specified using the MPassContext::kBeginRenderSemantic semantic will occur before the execution of the first scene pass. This would occur just before any notifications associated with the MPassContext::kBeginSceneRenderSemantic semantic. The basic order of rendering would be:

  • Begin rendering.
  • Loop for the number of scene passes:
    • If this is the first scene pass then invoke any notifications associated with the beginning of rendering.
    • Begin the current scene pass rendering, and invoke any notifications specified.
    • End the current scene pass rendering, and invoke any notifications specified.
  • End rendering, and invoke any notifications specified.
Parameters
[in]notificationNotification callback
[in]nameUnique name for the notification
[in]semanticLocationLocation in pipeline to invoke callback from. The only valid values are currently:
[in]clientDataOptional client data. The caller is responsible for maintaining this data.
Returns
MStatus::kFailure if addition could not be performed
+ Examples:
MStatus removeNotification ( const MString name,
const MString semanticLocation 
)

Remove a notification operation from the rendering pipeline.

If a notification with the same name and semantic location exists then the notification will be removed.

Parameters
[in]nameName of the notification
[in]semanticLocationLocation in the pipeline that the notification was added to. See addNotification().
Returns
MStatus::kFailure if removal could not be performed
+ Examples:
unsigned int notificationCount ( const MString semanticLocation) const

Returns the number of notifications that have been set for a given semantic location.

Parameters
[in]semanticLocationLocation in the pipeline that the notification was added to. See addNotification().
Returns
Notification count
bool presentOnScreen ( ) const

Returns whether the contents rendered by VP2 will be presented to on-screen buffers when running Maya in interactive mode.

By default Maya will always update on-screen buffers when in interactive mode.

Returns
Whether presentation is enabled.
void setPresentOnScreen ( bool  val)

Set whether the contents rendered by VP2 will be presented to on-screen buffers when running Maya in interactive mode.

This option will take effect on the next refresh of an on-screen buffer.

Parameters
[in]valPresentation option.
+ Examples:
bool useGradient ( ) const

Returns whether a gradient is being used to clear the background color.

Returns
True if using gradient
+ Examples:
MColor clearColor ( ) const

Returns the first clear color.

This will be the color used at the top of the background gradient if a color gradient is specified.

Returns
Clear color
+ Examples:
MColor clearColor2 ( ) const

Return the second clear color.

This will be the color used at the botom of the background gradient if a color gradient is specified.

Returns
Clear color
+ Examples:

The documentation for this class was generated from the following files:
  • MViewport2Renderer.h
  • MViewport2Renderer.cpp