What's New in API in Maya 2016 Extension 2

Selection

• MPxSubSceneOverride::getInstancedSelectionPath() has been added that enables you to select the correct render item instance when the viewport is in GPU acceleration mode. See the gpuCache example in the Maya Developer Kit for more information.
• A handlesConsolidatedGeometry semantic has been added that, when set to False, specifies that the Consolidate World feature should be disabled on the geometry to which the glslShader is applied.

  See Semantics and annotations supported by the dx11Shader and glslShader plug-ins in Viewport 2.0 and Shader semantics supported by Viewport 2.0.

Drawing

M3dView

• M3dView::readDepthMap() can now be used with Viewport 2.0, and allows you to read depth values directly from the depth map of Viewport 2.0.

  See the pointManip developer kit example. When dragging the pointManip, the selected objects are moved to the closest intersection point between the mouse ray and opaque objects, which is calculated from the screen-space position and the corresponding depth value.

MDrawContext

• The update frequency of MDrawContext::getFrameStamp() has been modified to update the stamp less frequently within a single frame.

  See the rawfootPrintNode andglslShader plug-in examples for usage of getFrameStamp().

MFrameContext

• Added new method MFrameContext::getEnvironmentParameters().

  This method returns the environment parameters set for the current viewport. Can be used in the draw phase for a plug-in hardware shader to check if an environment map is set for the current viewport (the method is accessed on the MDrawContext given to the shader). If an environment is enabled, the path to the environment image file is given. The image is always in latlong format. Note that this information is set per viewport and therefore may change between successive draw calls if multiple viewports are displayed at the same time.

  Currently, environments are only used by the Material Viewer in the Hypershade. For all other viewports, the environment is always set to disabled.

• Added object type exclusion statics to MFrameContext.

  Note that a MUint64 value is returned to allow for a complete set of exclusions to be accessed.

  MUint64 objectTypeExclusions() const;

  Exclusion by classification string has been newly added:

  void classificationExclusions(MStringArray &classification) const;

  The statics on MFrameContext should be instead of the enum MSceneRender::MObjectTypeExclusions, which has a subset of the new enum list.

  MSceneRender::getObjectTypeExclusions() has been added to return a MUint64 type. The objectTypeExclusions() method that returns MObjectTypeExclusions is considered to be obsolete, but will still work unless MSceneRender::getObjectTypeExclusions() is overridden.

  The viewImageBlitOverride and pyViewRenderOverride.py plug-in examples have been updated to use the new MFrameContext statics.

• A number of additions have been made to MFrameContext to enable querying of state information without having to access M3dView. These include:

  • Additional display styles (enum MFrameContext::DisplayStyle) : shaded active objects (kShadeActiveOnly), x-ray active components (kXrayActiveComponents), backface culling enabled (kBackfaceCulling), and smooth wireframe (kSmoothWireframe).
  • Additional object exclusion types, including: plug-in shapes (MFrameContext::kExcludePluginShapes), heads up display (MFrameContext::kExcludeHUD), animation clip ghosts (MFrameContext::kExcludeClipGhosts), and grease pencil draw items (MFrameContext::kExcludeGreasePencils).
  • Querying of background color / gradient (MFrameContext::getBackgroundParameters())
  • Querying of parameters used for the depth of field pass (MFrameContext::getDOFParameters())
  • Querying of render override name (MFrameContext::getRenderOverrideInformation())

  The example plug-in rawfootPrintNode in the Maya Developer Kit has been modified to include debugging code to perform these queries.

• Added MFrameContext::worldToViewport() and MFrameContext::viewportToWorld() methods that convert co-ordinates.

  This method converts the co-ordinates in world space to co-ordinates in the viewport:

  void worldToViewport(const MPoint &inPoint, double &xPos, double &yPos) const;

  This method converts co-ordinates in the viewport to the near clipping plane co-ordinates in world space:

  void viewportToWorld(double xPos, double yPos, MPoint &worldNearPt, MPoint &worldFarPt) const;

  The example plug-in uiDrawManager demonstrates the use of these methods when drawing 2d text and 3d text.

MPassContext

• MPassContext::shaderOverrideInstance() has been added that returns the shader instance for the current shader override. It allows you to use the shader program and parameters that Maya normally uses when drawing.

  See the rawFootPrintnode example plug-in in the Developer Kit for more information.

MPxPrimitiveGenerator and MRenderItem

• The following primitive types are now supported in Viewport 2.0:
  • MGeometry::kAdjacentLines
  • MGeometry::kAdjacentLineStrip
  • MGeometry::kAdjacentTriangles
  • MGeometry::kAdjacentTriangleStrip

  These primitive types can now be used everywhere that a primitive is set in Viewport 2.0, including a new triangle adjacency MPxPrimitiveGenerator in the GLSL shader plug-in (see adjacentTrianglesPrimitiveGenerator.cpp in the glslShader plug-in folder in the Developer Kit). Refer to SilhouetteEdge.ogsfx for an example of how this new generator enables the drawing of silhouette edges (see the presets\GLSL\examples folder of the Maya installation directory).

MPxDrawOverride

• MPxDrawOverride::isTransparent() has been added to indicate that the object needs to be drawn as transparent.

  If /isTransparent is added to the geometry classification drawdb/geometry/myNode/isTransparent/, then the plug-in will be called during transparent passes.

  You must consider post effects also. The classification drawdb/geometry/includePostEffects/ ensures that post effects are called for your draw override. To ensure that both isTransparent and includePostEffects take effect, set the classification as drawdb/geometry/rawfootPrint/isTransparent/includePostEffects.

  See the rawfootPrintNode plug-in example.

Post effects enhancements

MPxDrawOverride can opt-in to being called from post-effects passes by specifying a classification of drawdb/geometry/includePostEffects. By default, draw overrides are not called for additional post-effect passes such as: depth-of-field, screen space ambient occlusion, and motion-blur.

MPxDrawOverride::excludedFromPostEffects() can be used to exclude a draw override from being called for post-effects passes. See the rawfootPrintNode plug-in example.

New pass semantics have been added to MPassContext - MPassContext::kDOFPassSemantic, and MPassContext::kMotionVectorPassSemantic. These are equivalent to checking for the strings dofPass and motionVectorPass in previous releases. MPassContext::kPEPatternPassSemantic and MPassContext::kNonPEPatternPassSemantic have been added to indicate a post effect pattern pass and a non post effect pattern pass, respectively.

The ProjectionZSense semantic has been added that denotes whether the projection matrix flips the Z component of a point when transformed: if so, its value is -1.0; otherwise 1.0. See Shader semantics supported by Viewport 2.0.

For more information regarding these passes, see Effects interfaces.

Shaders

MShaderInstance

• The MShaderInstance::requiredVertexBuffers() method allows you to query a list of vertex buffer descriptors for a given shader instance (MVertexBufferDescriptorList).

  Subscene overrides, in particular, can make use of this method when using shader instances for custom render items, although this method can be called outside of the context of this override.

  This method is used in the GLSL shader plug-in. Refer to glslShader in the developer kit. See configureGeometryRequirements() on the GLSLShaderNode class where the results are examined to configure MVaryingParameters.

• The MShaderManager::getShaderFromNode() and MRenderItem::setShaderFromNode() interfaces have a new boolean argument nonTextured added that allows users to use a non-textured effect instance.

  See MPxPrimitiveGenerator and MRenderItem in the Drawing section above.

• The MShaderInstance::techniqueNames() method has been added that returns the list of techniques from a shader instance. This method is also available in Python API 2.0.

  A similar method MShaderManager::getEffectsTechniques() currently exists that loads an effects file and extracts the names of the defined techniques. However, this function can only be used when loading effects from files and cannot be used when loading effects from string buffers. You can now use the new MShaderInstance::techniqueNames() once the effect is loaded.

MShaderManager

• When acquiring a shader via any one of the various interfaces on MShaderManager, such as MShaderManager::getEffectsFileShader() or MShaderManager::getEffectsBufferShader(), if a shader compilation failure occurs, then errors will be output to the Output Window on Windows and Linux, and to the console on Mac. This aids in the debugging process for shader writers.

  When a shader cannot be returned, a NULL value will be returned.

  In particular, this is now true if the string buffer method MShaderManager::getEffectsBufferShader() is used. Previously, an error shader was returned, making it difficult to recognize if a failure had occurred.

• The MRenderItem::setShaderFromNode() and MShaderManager::getShaderFromNode() interfaces have a new boolean argument nonTextured added that allows users to use a non-textured effect instance.

  MRenderItem::setShaderFromNode() is the recommended interface because it does not expose internal effect instances. Its use is demonstrated in the apiMeshShape plug-in example (apiMeshSubSceneOverride.cpp) in the Developer Kit.

  Previously, this sample plug-in created only one render item for both its shaded mode and textured mode. In the new version, two render items are created: one for shaded mode, the other for the textured mode. Their effect instances are both assigned with MRenderItem::setShaderFromNode(), but the boolean argument nonTextured is set true for the shaded render item and false for the textured one.

MPxShaderOverride

• Viewport 2.0 does not, by default, return completely unshared data. A new interface has been added to specify this requirement:

  bool MPxShaderOverride::requiresUnsharedGeometricStreams()

  A plug-in can override this method to return true in order to force geometric streams to be expanded.

• To request face ids, vertex ids, and local UV coordinates when updating the geometry requirements for the shading effect, the following semantics are now supported. See MPxShaderOverride::addGeometryRequirement() for more information:
  • vertexid : When set, will return a vertex id buffer
  • faceid : When set, will return a face id buffer
  • uvcoord: When set, will return local UV coordinates
  NOTE:

  See Geometry remapping for hardware rendering.

• The hwPhongShader plug-in example in the Developer Kit demonstrates the following:
  • Set the environment variable MAYA_HWPHONG_TEST_VERTEXID_AND_FACEID to any value, and this example will print the vertex ids and the face ids to the output window for both the Legacy Default Viewport and Viewport 2.0.
  • Set the environment variable MAYA_HWPHONG_TEST_LOCALUVCOORD to any value, and this example will print the local UV coordinates to the output window for the Legacy Default Viewport and Viewport 2.0.
  • Set the environment variable MAYA_HWPHONG_TEST_INDEXING to any value, and the index that accesses the id and UV coordinates will print out the local triangle indexing to the output window for both the Legacy Default Viewport and Viewport 2.0.
  • The MPxShaderOverride::requiresUnsharedGeometricStreams() method is overridden to return true for hwPhongShaderOverride.
  • The initialize() method of hwPhongShaderOverride specifies extra stream requirements: vertexid, faceid and uvcoord.
  • The draw() method of hwPhongShaderOverride extracts the vertexid, faceid, and uvcoord vertex buffers and prints their data.
  NOTE:

  See also the animCubeNode example, which, when the MAYA_TEST_VERTEXID_AND_FACEID environment variable is set, produces a cube the topology of which changes every 4 frames. When the hwPhongShader is assigned to this shape, the shader receives vertex ids and face ids that are generated from the animCubeNode plug-in.

MPxHwShaderNode

• The Legacy Default Viewport, by default, returns unshared data.

  Previously, vertex ids could be queried using the MPxHwShaderNode::provideVertexIDs() method. Face ids can now be queried using the new MPxHwShaderNode::provideFaceIDs() method. Local UV coordinates can now be queried using the new MPxHwShaderNode::provideLocalUVCoord() method.

  There are new methods that return the data with this signature:

  MStatus    MPxHwShaderNode::geometry( const MDrawRequest& request,
          M3dView& view,
          int prim,
          unsigned int writable,
          int indexCount,
          const unsigned int * indexArray,
          int vertexCount,
          const int * vertexIDs,
          const float * vertexArray,
          int normalCount,
          const float ** normalArrays,
          int colorCount,
          const float ** colorArrays,
          int texCoordCount,
          const float ** texCoordArrays,
          const int *faceIDs,
          const float * localUVCoord)

  Mstatus MPxHwShaderNode::glGeometry( const MDagPath& shapePath,
          int prim,
          unsigned int writable,
          int indexCount,
          const unsigned int * indexArray,
          int vertexCount,
          const int * vertexIDs,
          const float* vertexArray,
          int normalCount,
          floatArrayPtr normalArrays,
          int colorCount,
          floatArrayPtr colorArrays,
          int texCoordCount,
          floatArrayPtr texCoordArrays,
          const int * faceIDs,
          const float * localUVCoord)

  The blindDataShader and hwPhongShader plug-in examples both demonstrate the use of this interface to retrieve vertex and face ids.

  The blindDataShader example displays a grey-scale value for the corresponding face ids returned.

  Note that the UV co-ordinates, face and vertex ids returned will be equivalent for both the Viewport 1 and Viewport 2.0 MPxShaderOverride interface (provided that the Viewport 2.0 interface asks for unshared data).

  When a mesh is using smooth mesh preview, then the face ids returned are those of the original unsmoothed mesh while the vertex ids are those of the smoothed mesh.

MRenderItem

• MRenderItem::sourceDagPath() always returns a dag path even when the item contains consolidated geometry (MRenderItem::isConsolidated()). When consolidated, it will return one dag path out of all dag paths contributing to the geometry. See Documentation updates for more information regarding the extraction of dag paths and geometry from consolidated geometry during draw time.

  The use of MRenderItem::sourceIndexMapping() is preferable since this interface returns an appropriate list of dag paths.

Textures

MTextureManager

• The MTextureManager::acquireTexture() method:

  MTexture* MTextureManager::acquireTexture(const MString& textureName, const MPlug& plug, int width, int height, bool generateMipMaps = true);

  has been modified so that if a plug to a file texture node is specified, then an attempt will be made to read the file texture from disk. Previously, this method would bake the texture using the Maya Software renderer's convert to solid texture functionality. This modification allows for better fidelity and accuracy of the returned texture.

• A new MTextureManager::acquireTexture() method:

  MTexture* MTextureManager::acquireTexture(const MObject& textureNode, bool allowBackgroundLoad = false); 

  loads the file texture from a given texture node, and is the preferred method for file textures (over the previously mentioned plug method), as it provides a simpler interface. It takes a file texture node as an argument, and removes the requirement to specify parameters that are not needed (width, height, name, and generate mipmaps).

  In addition, it exposes the option to indicate whether the Viewport 2.0 texture background loading feature should be used. See Material Loading Mode in the Display preferences section of the Maya User Guide for more information regarding texture background loading.

• The new MTexture::update() method:

  MStatus MTexture::update(const MObject& textureNode);

  allows for update versus acquisition using a file texture node.

  Currently, all file texture based methods have the limitation that they return the first tile if the file texture uses UV tiling.

• See the hwApiTextureTest developer kit example for a demonstration of how to use these methods. This plug-in example includes a -n / -nodeLoad option that attempts to acquire MTexture references from existing file texture nodes in a scene. This option also attempts to create baked textures from selected procedural nodes by sampling its outColor attribute.
• See the viewOverrideTrackTexture developer kit example. This is a plug-in render override which, when active, will try and find the first file texture node in the scene and acquire or update an MTexture. This MTexture is used for a quad render operation which is the main operation used for the render override.

Lighting

In Maya 2016 Extension 2, Viewport 2.0 only evaluates lights up to the light limit. Therefore, if you want to request light information on demand, you must call the new MRenderer::needEvaluateAllLights() method.

If your plug-in calls the following interfaces:

• MDrawContext::getLightInformation(kFilterIgnoreLightLimit)

• MRenderer::setLightsAndShadowsDirty()

• MRenderer::setLightRequiresShadows()

You must first call this method before drawing.

If you do not want to modify your existing plug-in, you can also set an optionVar MAYA_VP2_IGNORE_EVALUATION_LIGHT_LIMIT=1 to ensure that your plug-in continues to work as it did before Extension 2. When this optionVar is set, all lights in your scene are evaluated at all times, regardless of whether you have loaded a plug-in. As a result, this optionVar may decrease the performance of Viewport 2.0 if you have a scene with many lights.

To mitigate this, you can set this optionVar to 0 again when your plug-in no longer needs to evaluate all lights, and Viewport 2.0 will revert back to only evaluating lights up to the light limit.

Geometry

• MGeometryExtractor now supports the following:

  • Multiple UV map sets for texture co-ordinates in plug-in shaders
  • Named map sets for Tangent and Binormal co-ordinates in plug-in shaders

  The geometryReplicator example plug-in demonstrates the support of these new features.

• The MPxSubSceneOverride::setGeometryForRenderItem() interface has been updated so that when geometry is defined for drawing using a vertex buffer, for example by using MGeometry::kPoints, then it is no longer mandatory to also provide an MIndexBuffer. In this case, you can simply provide an empty MIndexBuffer to avoid wasting GPU memory. See the gpuCache Developer Kit plug-in for an example implementation.

Locators

• MPxLocatorNode::draw() will now be passed the appropriate M3dView::DisplayStyle instead of always receiving the set kWireframe.

Cameras

• Added the following functions to obtain un-normalized clip values:
  • The MFnCamera::unnormalizedNearClippingPlane() function returns the distance to the near clipping plane.
  • The MFnCamera::unnormalizedFarClippingPlane() function returns the distance to the far clipping plane.

    Normalized clip planes may be computed for camera sets. This is the value returned by the existing MFnCamera::nearClippingPlane() and MFnCamera::farClippingPlane() methods. These new methods allow access to the original camera's clipping planes.

• New methods to get the clip planes and unnormalized clip planes are now available as part of the draw context for Viewport 2.0.

  The following enums have been added to MFrameContext:

  • MFrameContext::kViewNearClipValue //!< Camera near clip value (single value)

  • MFrameContext::kViewFarClipValue //!< Camera far clip value (single value)

  • MFrameContext::kViewUnnormlizedNearClipValue //!< Unnormalized camera near clip value (single value)

  • MFrameContext::kViewUnnormalizedFarClipValue //!< Unnormalized camera far clip value (single value)

  which can be used from the MDrawContext::getTuple() method.

  These produce the same results as when using MFnCamera::nearClippingPlane(), MFnCamera::farClippingPlane(), MFnCamera::unnormalizedNearClippingPlane(), and MFnCamera::unnormalizedFarClippingPlane() respectively.

  See the rawfootPrintNode example plug-in for more information. See also Camera information.

Render overrides

MQuadRender

• A fix has been made to help prevent memory leaks for shader instances used with quad render operations for MRenderOverrides.
• A fix has been made to ensure that if any MRenderTarget specified in the MRenderOperation::targetOverrideList() method is also specified as an input to the MShaderInstance returned from MQuadRender::shader(), then there will not be any issues with reading and writing from the same target during rendering.

  See the viewRenderOverride and viewRenderOverridePostColor developer kit examples.

• A new plug-in example has been added to show how an MRenderOverride can use an MSceneRender along with a series of MQuadRenders to perform post scene color effects. See viewRenderOverridePostColor in the developer kit and Post scene render color operations.
• Previously, if a scene or quad render operation specifies a render target that is larger than the current output target (for example, the viewport), this resulted in the operation drawing to a subset of pixels in the output target. This has been fixed.

  See the viewRenderOverrideMRT plug-in for sample code that draws to custom output targets that are larger than the active output target size.

Tools and context

MPxContext

• Added a new method MPxContext::doPtrMoved(). This method is called when the mouse moves, so that mouse movements can be used to drive a subsequent action.

  In the case of drawing, plug-ins should override this method when MUIDrawManager is used to perform drawing in Viewport 2.0.

Tracing/sequencing

Debug tracing information has been added for several override classes to help track evaluation order, as well as to the internal pipeline to track renderable list execution.

MPxDrawOverride and MPxGeometryOverride have new tracing methods (such as MPxDrawOverride::traceCallSequence() and MPxDrawOverride::handleTraceMessage(), and the ogs command has a new trace option (-traceRenderPipeline flag).

See Basic Viewport 2.0 Pipeline Sequencing and Basic Viewport 2 Object Sequencing for more information.

Profiling

The Profiler now graphs rendering events that execute within Viewport 2.0. These events include node evaluation and UI drawables list/render list building, as well as draw events such as UV Editor drawing, beauty pass render, and UI drawables rendering (such as manipulator drawing). If you are using a render override plug-in, operations such as the quad render, 3d scene render and HUD render are also presented.

This feature allows you to identify render events or passes that may be performance bottlenecks in your scene

To filter these events, search for the prefix Vp2.

For more information on rendering events in Viewport 2.0, as well as information on what each event represents, see Profile Viewport 2.0 rendering events and Viewport 2.0 rendering events Profiler examples.

Render Setup

A new MRenderSetup class has been added that allows for access to Maya's new render setup functionality.