What's New in the Rendering and Lighting API

The MUIDrawManager::mesh() interface has been overloaded and a new interface added to support float data types.

void mesh( Primitive mode, 
    const MFloatPointArray& position,
    const MFloatVectorArray* normal = NULL,
    const MColorArray* color = NULL,
    const MUintArray* index = NULL,
    const MFloatPointArray* texcoord = NULL 
    );

The following MPxSelectionContext::doPress(), MPxSelectionContext::doRelease(), MPxSelectionContext::doDrag(), and MPxSelectionContext::doHold() virtual functions have been added to handle mouse events for Viewport 2.0.

Now when you derive a class from MPxSelectionContext, you can override these functions to handle mouse events such as a button press or release:
- virtual MStatus doPress ( MEvent & event, MHWRender::MUIDrawManager& drawMgr, const MHWRender::MFrameContext& context);
- virtual MStatus doRelease( MEvent & event, MHWRender::MUIDrawManager& drawMgr, const MHWRender::MFrameContext& context);
- virtual MStatus doDrag ( MEvent & event, MHWRender::MUIDrawManager& drawMgr, const MHWRender::MFrameContext& context);
- virtual MStatus doHold ( MEvent & event, MHWRender::MUIDrawManager& drawMgr, const MHWRender::MFrameContext& context);
To ensure that your plug-in works correctly in both the Legacy Default Viewport and Viewport 2.0, you can keep the legacy implementation of MPxSelectionContext unchanged, but you must override the Viewport 2.0 implementation.

See the moveTool devkit example for more information.

Shading

The MPxShaderOverride class now supports Maya shading nodes for particle sprite shading in Viewport 2.0. See the customSpriteShader/customSpriteShader.cpp example plug-in for details on creating a custom sprite shader.
Added the MShaderInstance::writeEffectSourceToFile() method for debugging custom shader fragment development. Use this method to see how the final shader fragments are converted to the final effect source on the current drawing API.
You can validate the shader fragments by compiling and binding a shader instance generated from the final effect source. To enable the fragment debugging code path, set the following environment variable: MAYA_CUSTOMSPRITESHADER_DEBUG_FRAGMENTS = 1. Shader compilation errors or warnings can be displayed in the Maya Script Editor. When errors or warnings occur, modify the fragments in XML. After updating, restart Maya and reload the scene the test your fixes.

See the customSpriteShader/customSpriteShader.cpp plug-in example for more information.
A new customSpriteShader/customSpriteShader.cpp example plug-in demonstrates how to connect geometry shader fragments using the C++ API or XML schema. It also includes the use of the MPxShaderOverride class to create custom shaders for particle sprites.
The plug-in connects geometry shader fragments by creating a shader instance from a fragment graph using MShaderInstance::addInputFragment(). The fragment graph connections, properties, values, and outputs are defined by an XML schema.

An implementation of color management on the input texture is also included in the supplied customFileTextureOutputColor.xml file. This file shows how Maya converts texture color from sRGB space or linear space. You can also use the existing MShaderInstance::createShaderInstanceWithColorManagementFragment() interface, or refer to customFileTextureOutputColor.xml for custom implementation of color management depending on your specific needs. The MPxShaderOverride::isTransparent() virtual method handles transparency notifications.

For debugging the shader fragments, the final effect source of the shader instance is written to disk using a new MShaderInstance::writeEffectSourceToFile() interface. Shader compilation errors can be displayed in the Maya Script Editor, during binding, or queried using MShaderManager::getLastError().

The customSpriteShader plug-in supports all Viewport 2.0 OpenGL Core Profile, OpenGL, and DirectX 11 modes.

Query for camera near and far clipping planes from shaders

You can now access and query for camera near and far planes from shaders using uniform or semantic parameters. For effects generated from a file or buffer, new parameters with semantics have been added to the MUniformParameter class DataSemantic enumerators. These uniform parameters provide access to near and far clipping planes in full effects created by the MPxShaderOverride class.

kSemanticNearClipPlane
kSemanticFarClipPlane

For shader fragments, a parameter with semantics nearClipPlane and farClipPlane are automatically updated by Viewport 2.0.

Drawing

Added new virtual functions to the MPxDrawOverride class, which let you continue to use MPxLocatorNode class functions to override selection behavior for custom shapes in your plug-ins. The MPxDrawOverride class functions also provide the UI drawing mechanism to supersede the MPxSurfaceShapeUI class.
These updates do not require plug-in source code changes or recompiling.

The new functions include:
- MPxDrawOverride::wantUserSelection(), which when set to true this function gets overridden allowing MPxDrawOverride::userSelect() to be invoked for selection testing. Otherwise, the implementation is based on the rasterization of the drawing method.
- When MPxDrawOverride::userSelect() is invoked by MPxDrawOverride::wantUserSelection(), the MUserData instance is used for the current selection context.
The rawfootPrintNode plug-in example has been updated to demonstrate the use of the new functions.
A new MPxImagePlaneOverride class has been added, which lets you draw custom image planes in Viewport 2.0. Create an MPxImagePlaneOverride class and register the override when you initialize your plug-in. This new class includes the following methods:
- MPxImagePlaneOverride::updateDG(), which is called each time Maya needs to update the parameter used by updateColorTexture().
- MPxImagePlaneOverride::updateColorTexture(), which updates the textures used to draw the image plane. You can set custom raw data for the texture. This method only supports color textures.
A new customImagePlane/customImagePlane.cpp example for C++ and Python demonstrates how to use the new MPxImagePlaneOverride class and includes how to:
- Register the new node.
- Manipulate the color texture in the MPxImagePlaneOverride::updateColorTexture()method.
- Remove color texture updates in MPxImagePlane::loadImageMap().
Note that depth map updates still need to be done using MPxImagePlane::loadImageMap().
A warning message now appears when the device API that is returned does not include the current device API on which Viewport 2.0 is running. For example, if VP2 is running on OpenGL Core Profile mode, but supportedDrawAPIs() does not return MHWRender::kOpenGLCoreProfile, then a warning similar to the following appears:
Error: line 0: Failed to create evaluator for "drawdb/geometry/apiMesh" classification because the current drawing API isn't supported.
The footPrintNode, footPrint_GeometryOverride, and rawFootPrintNode devkit examples have been updated to improve viewport refreshes during animation while running Maya in Parallel Evaluation Mode.

General

Added new methods to the MRenderItem class to indicate whether the MRenderItem is compatible with the Maya instancer.
- MRenderItem::isCompatibleWithMayaInstancer() returns whether or not the MRenderItem can be used as an instance object with the Maya Instancer.
- MRenderItem::setCompatibleWithMayaInstancer() lets you inform Maya whether or not the MRenderItem is compatible with the Maya Instancer when it is created. If this API is not called explicitly, the state defaults to false, which means the object will be ignored by Maya Instancer.
Parameters for the rawData() function (MRenderTarget::rawData(), MTexture::rawData()) have been changed. The data type used with theslicePitch parameter has changed from int& to size_t&.
This update coincides with Maya's internal changes, which allow texture sizes to be greater than the upper limit of int type of 2^31. Note that this change breaks existing code and requires plug-ins to be updated and recompiled.

The following plug-in examples have been updated with this parameter change:
The MPxGeometryOverride class now provides frame contexts. For accessing the up-to-date frame context between setup and cleanup, you can use the following:
```
 const MFrameContext* getFrameContext() const; 
```
The MRenderTargetManager::releaseRenderTarget() function has been modified so that it no longer requires a non constant pointer to release a render target object. The parameter type can now be a constant pointer.
For example, the previous implementation required the following call to release a render target:

targetManager->releaseRenderTarget((MHWRender::MRenderTarget*)colorTarget);

Can now be simplified to the following:

targetManager->releaseRenderTarget(colorTarget);.
As part of the OpenMaya namespace implementation, the following OpenMayaRender classes have be renamed to maintain backwards compatibility:

MGeometry renamed to MGeometryLegacy

MGeometryRequirements renamed to MGeometryRequirementsLegacy

MRenderTarget renamed to MRenderTargetLegacy

For more information about the OpenMaya namespace, see Important updates to the Maya API.