MRenderer Class Reference
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.
Detailed Description
Main interface class to the Viewport 2.0 renderer.
#include <MViewport2Renderer.h>
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 |
Returns the current drawing API.
Returns 'kNone' if the renderer is not initialized.
- Returns:
- The current drawing API
- Examples:
- depthShader.cpp.
| bool drawAPIIsOpenGL | ( | ) | const |
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 |
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:
- footPrintNode.cpp.
| MFragmentManager * getFragmentManager | ( | ) | const |
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 |
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 |
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 | ) |
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 |
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 | ) |
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 | ) |
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 | ) |
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 |
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 | ( | ) |
Get the number of registered render overrides.
- Returns:
- Number of registered overrides
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.
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] |
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] |
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] |
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 | ||
| ) |
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
