What's New in API in Maya 2017

Fragment renderer

A viewRenderOverrideFromFragments example plug-in has been added which demonstrates the use of a set of new APIs that allow you to use scripted fragment and fragment graphs to render the scene and any desired post effects. Script fragments are the building blocks used internally by Maya for standard viewport rendering effects, and are located in a series of .xml files in the bin/ScriptFragment folder of your Maya installation directory.

The following API classes and interfaces have been added to enable you to create a fragment renderer:

• Added a new MSceneRender constructor that allows you to provide the name of the fragment with which you want to render the scene.

  MSceneRender (const MString &name, const MString &fragmentName)

• Added the MRenderParameters class that can be used to read or write render input values.
• Added the MSceneRender::getParameters() method that returns a pointer to the MRenderParameters class, which is a block of render input parameters used to control the renderer.
• Added the MSceneRender::fragmentName() method that returns the name of the script fragment or fragment graph for use when rendering the scene.
• Added the MRenderScriptCallback class.

  Derive from this class to create a callback function that can be registered and called from your script fragment .xml. Implement the execute() function which allows you to obtain the MRenderParameters from the current renderer graph and three optional values coming from the script. Use this method to compute any desired behavior and call MRenderParameters::setParameter() to pass the results back to the script or to other connected fragments in the graph. See the Call command in the Script fragment commands topic for more information.

• Added the MRenderer::registerScriptCallback() and MRenderer::deregisterScriptCallback() interfaces that allow you to register/deregister an MRenderScriptCallback. After registering, this callback can be called using the Call command in your script fragment .xml.
• Register script fragments and fragment graphs to the Fragment Manager through MFragmentManager::addFragmentGraphFromFile(). Although this interface previously existed to support shade fragments and shade fragment graphs, it complements the new classes/ interfaces to provide the new functionality that allows you to create a custom fragment renderer.

See Write fragments and fragment graphs to render to the viewport.

Locators

• A new MPxLocatorNode::getShapeSelectionMask() interface has been added that allows you to set a shape selection mask for locators similar to how it is possible for shapes (MPxSurfaceShape and derived classes).

  See the footPrintNode_GeometryOverride Developer Kit example for more information. See also Selection mask usage.

  This method is also available for Python API 2.0.

• It is now possible to reuse Viewport 1 rendering and picking when using the Viewport 2.0 renderer for plug-in locators. See Use MPxLocatorNode legacy fixed draw code and selection in Viewport 2.0.

Drawing

• Two interfaces have been added to expose view filtering states: M3dView::viewIsFiltered() and M3dView::filteredObjectList().

  See the viewObjectSetOverride plug-in example in the Developer Kit.

• For Python API 2.0, a new parameter isAlwaysDirty has been added as the last parameter to the constructor of MPxDrawOverride in order to align with its C++ counterpart.

  To achieve the best performance, set this parameter to False, and refrain from using the static draw callback.

  See the pyFootPrintNode.py Developer Kit example for more information.

Shading and color management

• When MShaderInstance::createShaderInstanceWithColorManagementFragment() is used to add a color management fragment to an MShaderInstance, any pre or post render callbacks set on the shader instance are no longer lost. Previously they would both be set to null.

• Previously, the fragment mayaTextureShader and its associated stock shader wrapper k3dSolidTextureShader did not include exposure or alphaAsLuminance as parameters. Exposure for these attributes have been added to complete the support for color management parameters. See Color management support for plug-in shaders in Viewport 2.0.
• A new MShaderManager::clearEffectCache() method has been added that allows plug-ins to clear the effect cache. This method allows all relevant effects to be updated when the implementation of a shader fragment or fragment graph has been modified.

Selection

• The MSelectionList::intersect() interface has been added that can be used to modify a selection list to contain the intersection of itself and the given list.
• To clarify the usage of beginDrawable, the following changes were made to MUIDrawManager:
  • The non-parameter version of beginDrawable() was removed
  • The two-parameter version of beginDrawable (unsigned int name, bool nameIsPickable) was marked as deprecated
  • Added a new enum Selectability, and added a new two-parameter version of beginDrawable (Selectability selectability=kAutomatic, unsigned int selectionName=0)
  • The Python API 2.0 version of MUIDrawManager was also updated accordingly

  Refer to the uiDrawManager and lineManipContainer (C++ API) and the pyUiDrawManager.py (Python API 2.0) Developer Kit examples for more information.

Render overrides

• A new method has been added:

  const MFrameContext* MRenderOverride::getFrameContext()

  This method allows access to the current frame render context information which is available between MRenderOverride::setup() and MRenderOverride::cleanup(). Per object / render item information is not available at setup time as the pipeline has not yet been run. Note that this provides information regardless of whether the override is called for viewport, Playblast, Render View or batch rendering.

  See the pyFrameContexTest.py plug-in example which demonstrates the use of MRenderOverride.getFrameContext() to extract various per-frame data.

Lights

It is now possible to combine a custom draw override with internal Viewport 2.0 lighting support by specifying both a "drawdb/light" and a "drawdb/geometry" classification when registering a node.

A sample use case is to draw a custom object in the viewport that performs lighting in Viewport 2.0 as a native Maya light would. See the apiDirectionalLightShape plug-in example and Registration for more information.

Geometry

The access of vertex ids, face ids and local parameterization is now exposed via the MGeometryExtractor interface. To extract completely unshared geometric data from a DAG shape, kPolyGeom_NotSharing needs to be specified when constructing an MGeometryExtractor instance.

Similar to MPxShaderOverride, there is no new interface on MGeometryExtractor that requests vertex ids, face ids or local parameterization. Instead MVertexBufferDescriptor should be specified with the following semantic names to populate these vertex buffers:

• “vertexid” : When set, will return a vertex id buffer
• “faceid” : When set, will return a face id buffer
• “localuvcoord” : When set, will return a local uv coordinate buffer

Refer to the geometryReplicator plug-in example for more information. To execute this plug-in example, first set the following environment variables, then assign a hwPhongShader to the geometryReplicator shape.

• MAYA_HWPHONG_TEST_VERTEXID_AND_FACEID = 1
• MAYA_HWPHONG_TEST_LOCALUVCOORD=1
• MAYA_HWPHONG_TEST_INDEXING=1

See Viewport 2.0: MGeometryExtractor access.

Custom evaluators

New API extensions have been added that let you define custom evaluators. Custom evaluators allow you to override how DG nodes are scheduled and executed by the evaluation manager. See Custom evaluator overview. See also MPxCustomEvaluator and the simpleEvaluator and constraintEvaluator plug-in examples in the Developer Kit.

Threading

• A new MObjectHandle::objectHashCode() interface has been added that allows you to return a hash code for the provided MObject without having to construct or destruct MObjectHandle. You should use this interface instead of MObjectHandle::hashCode() if your plug-in is threaded because the construction and destruction of MObjectHandle are not thread safe.