Extension for Autodesk Maya 2013

Viewport 2.0 API Guide

Most of the changes in the Maya 2013 extension are related to the API changes for Viewport 2.0. For more information, you can refer to the Maya Viewport 2.0 API Guide in the Viewport 2.0 API section.

OpenMaya Render

Draw Mode Enhancements

• MDrawContext - Enhanced support for querying of display styles and lighting modes (DisplayStyles, LightingMode enum).
• MHWGeometry - Enhanced support for marking render items as textured versus shaded (DrawMode enum).

Lighting Information

• Added the lightType(), lightPath(), and other methods to MLightParameterInformation class for working with StockParameterSemantics.

Geometry Enhancements

• Introduction of mutators and enhancements to data generators:
  • MPxVertexBufferMutator - New class that allows for the modification (mutation) of existing streams (vertex buffers) or the creation of custom streams for custom packing of data, such as for swizzling.
  • MDrawRegistry - Registration changes to accept mutators and generators.
  • MHWGeometry - Added MVertexBufferArray description (for MPxVertexBufferGenerator class).
  • MPxVertexBufferGenerator - Enhanced to create new streams by combining or using already created streams (which might be custom). The getSourceStreams() function lists the name of streams to be used as sources. Based on the list of names, a list of vertex buffers is provided as a parameter (sourceStreams) for createVertexStreams() function. Observe that the createVertexStreams() signature has changed.
• Index and Vertex Buffers
  • Added the map() and unmap() methods to the MIndexBuffer and MVertexBuffer classes to provide read-only access to the buffer contents.
  • Added resourceHandle() methods to the MIndexBuffer and MVertexBuffer classes to set and retrieve graphics device dependent handles to hardware buffers. The hasCustomResourceHandle() method can be used to determine if a custom resource handle is set.
• EXT_frame_buffer_object support
  • EXT_frame_buffer_object support is added to MGLdefinitions.
• Flexible data format changes:
  • MVaryingParameter - Type restrictions are loosened for varying parameter declarations, for example, integer and double types are now supported.
  • MGeometryRequirements - Element size is less restrictive for various streams, such as position, normal, tangent, and bitangent. For example, UV coordinates represented using three floats are now supported.
• Introduction of custom indexing for data streams:
  • MPxPrimitiveGenerator - Allows the plug-in to generate custom index buffers.
  • MComponentDataIndexing - A support class to describe indexing for a component.
  • MPxIndexBufferMutator - New class that allows for the modification (mutation) of existing index buffers to allow custom packing of index data, for example, in Crack-Free Point-Normal Triangles using Adjacent Edge Normals (PN AEN) patch list generation.

• New primitive types
  • MPxPrimitiveGenerator - Allows the creation of new primitive types that can be used by MPxShaderOverride class or by a custom renderer.

Shader Override Enhancements

• MPxShaderOverride - Added the boundingBoxExtraScale() method to allow shaders that do displacement to scale the bounding box of objects. The handlesDraw() method is also added to allow plug-in shaders to override drawing based on pass context information.

Shader Instance Enhancements

• MShaderInstance - Added specification and setting of transparency flag.
• MShaderManager - Added new stock shaders.
• Shader instances can now be bound and unbound independently of MRenderItems with new bind, pass activation, and unbind interfaces. The ability to update parameters within binds and unbind for efficiency is also provided.
• A MShaderInstance can be acquired by using a buffer stored in the memory (device-specific source code (char*), or a device-specific pre-compiled effect (FXO)).
• Shader instances can no longer be deleted directly. The MShaderManager::releaseShader() method must be used to delete shaders. This resolves the memory boundary problems that occur when a plug-in is compiled with a compiler configuration that is different from Maya.
• MShaderInstance now allows explicit control over the binding of shader effects (for example, cgfx or fx files) through its new bind() and unbind() methods. You can use getPassCount() and activatePass() to determine which passes are enabled in the effect and updateParameters() can be used to update parameters with the overhead of rebinding.
• getEffectsBufferShader() has been added to the MShaderManager class. It performs the same function as getEffectsFileShader() except that the source code for the effect is contained in a memory buffer instead of a file.

Texturing Enhancements

• MTexture - Added specification and setting of transparency flag. Also, included additional query functions for the alpha channel of textures.
• MTexture::rawData() - Allows for raw pixel data to be retrieved to system memory.
• Added MTextureManager::saveTexture() for saving texture to a disk.
• Textures can no longer be deleted directly. The MTextureManager::releaseTexture() method must be used to delete textures. This resolves the memory boundary problems that occur when a plug-in is compiled with a compiler configuration that is different from Maya.

Render Item Enhancements

• MRenderItem - When multiple objects are compatible, their geometry can be consolidated into a single MRenderItem to provide better performance by concatenating their index and vertex buffers. The isConsolidated() function returns true if the MRenderItem contains multiple objects and sourceIndexMapping() returns a MGeometryIndexMapping instance that describes how they are consolidated into the buffers.
• You can specify whether a MRenderItem can cast or receive shadows. The castsShadows() method is added to MRenderItem to modify and query whether the render item is casting shadows. The receivesShadows() method is added to provide the same functionality for receiving shadows.

Render Target Enhancements

• MRenderUtilities::blitTargetToImage() - Allows to render a MRenderTarget to a MImage.
• MRenderUtilities::blitTargetToGL() - Allows to render a MRenderTarget to a region of the current context.
• MRenderTarget::rawData() - Allows for raw pixel data to be retrieved to system memory.
• Added the MRenderTargetManager::formatSupportsSRGBWrite() to determine if a given format for a render target can support built in hardware gamma correction (also known as sRGB write). This is available for DirectX only. MRenderOperation::enableSRGBWrite() enables it for a given operation.
• MRenderTargetDescription - Added the setAllowsUnorderedAccess() and allowsUnorderedAccess() functions to set and query whether a target supports simultaneous read/write access to its data by multiple threads.
• Ability to acquire a new render target from the current on-screen buffer.
• Fix for swapped first and second color setting on color overrides.
• Render targets can no longer be deleted directly. The MRenderTargetManager::releaseRenderTarget() method must be used to delete render targets. This resolves the memory boundary problems that occur when a plug-in is compiled with a compiler configuration that is different from Maya.

State Enhancements

• State objects can no longer be deleted directly. Four new methods (one for each state object type) are added to MStateManager for handling deletion: MStateManager::releaseBlendState(), MStateManager::releaseDepthStencilState(), MStateManager::releaseRasterizerState(), and MStateManager::releaseSamplerState(). This resolves the memory boundary problems that occur when a plug-in is compiled with a compiler configuration that is different from Maya.

Pass Context Information

• MPassContext - Allows querying of pass context information. Several of the example plug-ins, including footPrintNode and hwPhongShader have been updated to make use of this information.
• Added MDrawContext::getPassContext() to return information about the current render pass. It returns an instance of the new MPassContext class.

Render Override Enhancements

• MViewportRenderer - Enhancements to render override scene operations for additional display mode and lighting mode overrides.
• MSceneRender - Provides more object type filtering options. Opaque and transparent objects can now be split for separate drawing.
• Support for render overrides in the modelEditor command. Overrides now support UI names and appear in the Renderer menu in the 3d viewport panels.
• Fix for swapped first and second color setting on color overrides.
• A render operation can indicate whether the sRGB write (hardware based 2.2 gamma correction) is enabled for the render target specified for an operation. This applies to scene, quad, and user operations. You can derive from MRenderOperation::enableSRGBWrite() to indicate the enabled status. This is available for DirectX only.
• Support for multiple render targets (MRT) for scene and quad render operations. The MRenderTargetDescription::compatibleWithDescription() utility method can be used to check for compatible target descriptions.
• The HUD operation now works properly with the render target overrides and follows the order of operations. The HUD operation is no longer rendered last and to the final target. The HUD operation is also no longer incorrectly rendered as part of a scene operation. See changes to the stereo plug-in for an example.

Geometry Utilities

• Added MGeometryUtilities::acquireReferenceGeometry() to retrieve a MGeometry of a specified shape (sphere, cube, or plane) for the given requirements (vertex and index buffers).
• Added MGeometryUtilities::releaseReferenceGeometry() to release the geometry memory. The caller is responsible for using MGeometryUtilities::releaseReferenceGeometry() to release the geometry when done.

Render Utilities

• MRenderUtilities - A new class that provides various utility functions for viewport rendering such as setting the swatch background color, retrieving the draw contexts for swatches and the texture editor, and blitting a target to OpenGL or a MImage.

DirectX 11 General

• DX11 resources are exposed similarly to GL resources.
• There is a new DX11 draw API. Plug-ins can now support either GL or DX or both API's.
• Added kDirectX11 to the DrawAPI enum. MRenderer::drawAPI() returns kDirectX11 if the current renderer supports DX 11. If the drawing API is kDirectX11, the MRenderer::GPUDeviceHandle() returns a pointer to the DirectX device. Custom overrides derived from MPxDrawOverride, MPxGeometryOverride, MPxShaderOverride, and MRenderOverride can indicate whether they support DX11 by including kDirectX11 in the bitmap returned by their supportedDrawAPIs() methods.

Plug-in Exclusion Filtering

• MPxSurfaceShape - Type filtering for plug-in shapes is supported.
• Added type exclusion support for plug-in types during registration. You can add in a filter by providing appropriate classification.
• Plug-in nodes with classification string drawdb/geometry/lights are filtered when lights are filtered.

Custom Display Filters

• Added MFnPlugin::registerDisplayFilter() to create new object filters that appear in the viewport's Show menu. Added setPluginDisplay() and pluginObjectDisplay() to the M3dView class to control and query the state of these filters. Added MDrawInfo::pluginObjectDisplayStatus() to provide information to plug-in shapes.

New API for Reference Edits

• MItEdits - Allows you to iterate through a scene's reference edits. MEdit, MAddRemoveAttrEdit, MConnectDisconnectAttrEdit, MFcurveEdit, MParentingEdit, and MSetAttrEdit provide methods for querying about specific types of edits.
• MFnReference - Allows you to query individual file references.
• MFnDependencyNode::isTrackingEdits() - Allows you to determine if a reference node or assembly is tracking edits.

• Added new edit-related message types : MSceneMessage:kBeforeLoadReferenceAndRecordEdits, MSceneMessage:kAfterLoadReferenceAndRecordEdits, MSceneMessage:kBeforeCreateReferenceAndRecordEdits, and MSceneMessage:kAfterCreateReferenceAndRecordEdits.

New API for Scene Assemblies

• MFnAssembly - Allows you to query and modify assembly nodes that are used to manage the various representations of a scene asset.
• MPxAssembly - Allows you to create custom assembly types.
• MPxRepresentation - Allows you to create custom representations.

New API for Generic Metadata (Blind Data)

• MPxMayaAsciiFilter - Added the writesMetadata() virtual method.
• MFnDependencyNode - Added the setMetadata(), deleteMetadata(), metadata(), and validateMetadata() methods.
• MDGModifier - Added the setMetadata() and deleteMetadata() methods.
• Added classes to create and operate on streams of generic data. See the API Reference for classes in the adsk::Data namespace, for example, adsk::Data::Stream and adsk::Data::Channel.

New API for Uniform Resource Identifiers (URIs)

• MPxFileResolver - Allows to create custom handlers to resolve specific URI schemes.
• The MURI class can be used to create URIs as well as query and modify various components of a URI.

Miscellaneous

• Added MFnFloatArrayData to complement the set of array data types that can be passed through a connection.
• MLibrary::cleanup() method now takes an optional exitWhenDone parameter. Setting this parameter to false allows control to return to the caller rather than forcing the application to exit.

New/Updated Samples

• dx11shader - New plug-in to support HLSL effects in DX11.
• dx11ShaderNode - Support for multiple stream declarations are improved. Clients can now declare multiple TexCoord, color, tangent, and binormal streams and use the AE to bind them by name with the geometry data.
• vertexBufferGenerator - New plug-in example for custom vertex buffers.
• vertexBufferMutator - New plug-in example of a mutator.
• customPrimitiveGenerator - An example of MPxPrimitiveGenerator.
• crackFreePrimitiveGenerator - An example of MPxIndexBufferMutator.
• gpuCacheDrawOverride - Updated to incorporate changes for display mode, lighting mode exposure, and exclusion filtering.
• footprintNode - Enhanced to perform optimized drawing for shadow passes.
• hwPhong - Updated to perform custom shadow pass and beauty pass rendering using the new stock shaders (MShaderInstance). The plug-in can now render under DX11 or OpenGL.
• squareScaleManip - An example of supporting a custom manip (MPxManipulatorNode) using MPxDrawOverride.
• swissArmyManip - An example of how VP2.0 supports MPxManipContainer without additional code. All that has been added to this plug-in is a MPxDrawOverride to support the custom locator that the manip affects.
• customTextureShader - An example of a custom shader (using MPxShaderOverride) that produces and interprets its own custom texture format. For DX11 only.

Documentation

• Comprehensive Viewport 2.0 API guide added: Maya Viewport 2.0 API Guide.
• DX11 semantics topic added: Semantics and annotations supported by VP2 DX11.
• MShaderInstance Viewport 2.0 Semantics topic added: Semantics supported by Viewport 2.0 to be used with MShaderInstance.
• PyQt and PySide widget best practices topic added: PyQt and PySide Widget Best Practices.