- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Member Functions

# MRenderer Class Reference
OpenMayaRender - API module for rendering

This reference page is linked to from the following overview topics: Autodesk Maya 2014, Extension for Autodesk Maya 2013, Devkit Samples, 3.2 The Renderer, 3.3 Geometry Overrides, 3.8 Render Loop Overrides, 4.2 Lighting Interfaces.

Search for all occurrences

## Detailed Description

Main interface class to the Viewport 2.0 renderer.

Examples:

  brickShader.cpp, checkerShader.cpp, contrastShader.cpp, depthShader.cpp, footPrintNode.cpp, gammaShader.cpp, hwPhongShader.cpp, and mixtureShader.cpp.

`#include <MViewport2Renderer.h>`

List of all members.

## Public Member Functions
MHWRender::DrawAPI | drawAPI () const
| Returns the current drawing API.
bool | drawAPIIsOpenGL () const
| Method will indicate whether the current drawing API is OpenGL or not.
unsigned int | drawAPIVersion () const
| Method will return the version of drawing API.
void * | GPUDeviceHandle () const
| Method will return a pointer to the GPU "device".
MFragmentManager * | getFragmentManager () const
| Access the fragment manager.
const MShaderManager * | getShaderManager () const
| Access the shader manager.
const MRenderTargetManager * | getRenderTargetManager () const
| Access the render target manager.
bool | copyTargetToScreen (const MRenderTarget *renderTarget)
| Copy a render target to the screen.
MTextureManager * | getTextureManager () const
| Access the texture manager.
MStatus | registerOverride (const MRenderOverride *roverride)
| Register the override as being usable by the renderer.
MStatus | deregisterOverride (const MRenderOverride *roverride)
| Deregister an existing render override on the renderer.
const MRenderOverride * | findRenderOverride (const MString &name)
| Return a reference to an existing render override registered with the renderer.
const MString | activeRenderOverride () const
| Get the name of the active override.
unsigned int | renderOverrideCount ()
| Get the number of registered render overrides.
MStatus | setRenderOverrideName (const MString &name)
| Set the name of a render override (MHWRender::MRenderOverride) for batch rendering.
MString | renderOverrideName (MStatus *ReturnStatus=NULL) const
| Get the current render override name used for batch rendering.
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.
## Static Public Member Functions
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.
static void | setGeometryDrawDirty (MObject obj, bool topologyChanged=true)
| Notify the Viewport 2.0 renderer that something about obj has changed, causing the object to be updated in the viewport.
static void | setLightsAndShadowsDirty ()
| Notify the Viewport 2.0 renderer that something has changed which requires re-evaluation of lighting and shadows.

## Member Function Documentation

MHWRender::DrawAPI drawAPI | ( |  | ) | const

Search for all occurrences

Returns the current drawing API.

Returns 'kNone' if the renderer is not initialized.

Returns:
  The current drawing API

Examples:
  depthShader.cpp.

bool drawAPIIsOpenGL | ( |  | ) | const

Search for all occurrences

Method will indicate whether the current drawing API is OpenGL or not.

Returns:
  True if the API is OpenGL.

Examples:
  footPrintNode.cpp, and hwPhongShader.cpp.

unsigned int drawAPIVersion | ( |  | ) | const

Search for all occurrences

Method will return the version of drawing API.

Returns:
  Draw API version, or 0 if the renderer is not initialized properly.

void * GPUDeviceHandle | ( |  | ) | const

Search for all occurrences

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:
  footPrintNode.cpp.

MFragmentManager * getFragmentManager | ( |  | ) | const

Search for all occurrences

Access the fragment manager.

Returns:
  A pointer to the fragment manager or NULL if the renderer is not initialized properly.

Examples:
  brickShader.cpp, checkerShader.cpp, contrastShader.cpp, depthShader.cpp, gammaShader.cpp, and mixtureShader.cpp.

const MShaderManager * getShaderManager | ( |  | ) | const

Search for all occurrences

Access the shader manager.

The shader manager can be used to produce MShaderInstance objects which may be assigned to MRenderItem objects by implementations of MPxGeometryOverride.

Returns:
  A pointer to the shader manager or NULL if the renderer is not initialized properly.

Examples:
  hwPhongShader.cpp.

const MRenderTargetManager * getRenderTargetManager | ( |  | ) | const

Search for all occurrences

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.

bool copyTargetToScreen | ( | const MRenderTarget * | renderTarget | ) |

Search for all occurrences

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] | renderTarget | Render target to copy.

Returns:
  True if copy was successful.

MTextureManager * getTextureManager | ( |  | ) | const

Search for all occurrences

Access the texture manager.

The texture manager can be used to acquire texture

Returns:
  A pointer to the texture manager or NULL if the renderer is not initialized properly.

Examples:
  hwPhongShader.cpp.

MStatus registerOverride | ( | const MRenderOverride * | roverride | ) |

Search for all occurrences

Register the override as being usable by the renderer.

If the override is already registered it will not be registered again.

Parameters:

  [in] | roverride | Rendering override to be registered.

Returns:
  Status code

Status Codes:
  - MS::kSuccess Override was registered.
  - MS::kFailure Override failed to register.

MStatus deregisterOverride | ( | const MRenderOverride * | roverride | ) |

Search for all occurrences

Deregister an existing render override on the renderer.

The renderer will remove this override from it's list of registered overrides.

Parameters:

  [in] | roverride | Rendering override to be deregistered.

Returns:
  Status code

Status Codes:
  - MS::kSuccess Override was deregistered
  - MS::kFailure Override failed to be deregistered.

const MRenderOverride * findRenderOverride | ( | const MString & | name | ) |

Search for all occurrences

Return a reference to an existing render override registered with the renderer.

Parameters:

  [in] | name | Name of override to find

Returns:
  Status code

Status Codes:
  - MS::kSuccess Override was found.
  - MS::kFailure Override was not found.

const MString activeRenderOverride | ( |  | ) | const

Search for all occurrences

Get the name of the active override.

There can only be on 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.

unsigned int renderOverrideCount | ( |  | ) |

Search for all occurrences

Get the number of registered render overrides.

Returns:
  Number of registered overrides

MStatus setRenderOverrideName | ( | const MString & | name | ) |

Search for all occurrences

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

Parameters:

  [in] | name | Name of the override.

Returns:
  Status code

Status Codes:
  - MS::kSuccess The override was set.
  - MS::kFailure The override could not be set.

MString renderOverrideName | ( | MStatus * | ReturnStatus = `NULL` | ) | const

Search for all occurrences

Get the current render override name used for batch rendering.

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

Parameters:

  [out] | ReturnStatus | return status.

Returns:
  Override name.

Status Codes: Currently always returns MS::kSuccess.

void disableChangeManagementUntilNextRefresh | ( |  | ) | `[static]`

Search for all occurrences

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.

void setGeometryDrawDirty | ( | MObject | obj,
|  | bool | topologyChanged = `true`
| ) |  | `[static]`

Search for all occurrences

Notify the Viewport 2.0 renderer that something about 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.

Parameters:

  [in] | obj | DAG object which has been modified.
  [in] | topologyChanged | has the object topology changed

Examples:
  apiMeshShape.cpp.

void setLightsAndShadowsDirty | ( |  | ) | `[static]`

Search for all occurrences

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.

bool setLightRequiresShadows | ( | MObject | object,
|  | bool | flag
| ) |  |

Search for all occurrences

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 illuminaton 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, irregardless 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] | object | Light to request shadow update for
  [in] | flag | Indicate 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

MRenderer MRenderer MRenderer MRenderer MRenderer MRenderer MRenderer MRenderer MRenderer MRenderer
MRenderer MRenderer MRenderer MRenderer MRenderer MRenderer MRenderer MRenderer MRenderer MRenderer