Autodesk Maya 2015



UI Draw Manager Enhancements

  • Depth Priority : It is possible to set the depth priority before queuing a drawable in MUIDrawManager. The depth priority value is used when rendering the drawable.
  • The default depth priority value is 0.
  • Font name and size control:
    • The new setFontName() method controls the font used for text drawing. It takes as input a font string which is case insensitive. By default, Maya uses “helvetica”, which is also used when an invalid font name is provided.
    • setFontSize has been updated to allow for an arbitrary font size (height) in the unit of pixel.
  • Transparent text drawing is now supported. The alpha channel of the text color and text background color are respected.
  • Available fonts: getFontList() is newly added to return a list of available font names on the current system. You can then pass one of the font names to the setFontName() function in order to use that particular font.
  • New functions have been added to support drawing images and textured meshes.
    • setTexture() is used to set the active texture to be applied when drawing a mesh. This remains in effect until the next call to setTexture().
    • setTextureSampler() is used to set the filter and address mode used when applying a texture to a mesh. This remains in effect until the next call to setTextureSampler().
    • setTextureMask() is used to set the channel mask used when applying a texture to a mesh. This remains in effect until the next call to setTextureMask().
  • Optional arguments have been added to the mesh() and mesh2D() functions to supply texture coordinates when drawing a mesh. Use with setTexture(), setTextureSampler() and setTextureMask().

Render Item Enhancements

  • Render Items now have an immutable “type” which indicates to Maya the type of render item that it is and thus how to treat it with regards to various filters and draw modes. The old MRenderItem::Create() method has been deprecated and should not be used. Render items created with the old method are given either the DecorationItem type or the MaterialSceneItem type, depending on the viewport draw modes that the render item was created with. Additionally, new methods were added to MRenderItemList to make it easier to find items in the list.

    The possible types for a render item are as follows:

    • MaterialSceneItem: A render item which represents an object in the scene that should interact with the rest of the scene and viewport settings (for example, a shaded piece of geometry which should be considered for calculations such as shadow computation, viewport effects, and so forth). Inclusion in such processes can also still be controlled through the appropriate methods provided by this class.
    • NonMaterialSceneItem: A render item which represents an object in the scene that should not interact with the rest of the scene and viewport settings, but that is also not part of the viewport UI (for example, a curve or a bounding box that should not be hidden when the viewport UI is hidden, but also that should not participate in shadow computation or viewport effects).
    • DecorationItem: A render item which should be considered to be part of the viewport UI (for example, wireframe, components, and so forth).
    • InternalItem: A render item which was created by Maya for internal purposes (for example, a render item created as the result of a shader being assigned to a DAG node).

Context Enhancements

  • MFrameContext provides two static methods which can be used to test if any user interaction is occurring:
    • static bool inUserInteraction();
    • static bool userChangingViewContext();

    These methods can be used for the same purpose as their equivalent methods, passed via an MDrawInfo in the default viewport API. The example plug-in footPrintNode demonstrates how to use these methods: it switches to display a bounding box when user interaction is detected (for example, when the camera is tumbling).

    MFrameContext has additional static methods that test for display preferences:

    • wireOnShadedMode() can be used to query the current display preferences for wireframe on shaded mode display.
    • shadeTemplates() can be used to query the current display preferences that determine whether template objects should display shaded.

    MFrameContext has an additional member method, getCurrentCameraPath(), which can be used to determine the path to the camera that is being used to render the current frame.

    MFrameContext has a new method renderingDestination() that queries the destination for rendering. This can be used, for instance, to identify the viewport panel that is being rendered to; or, to distinguish between rendering to the render view or to an image on disk.

    //! Rendering destinations
        enum RenderingDestination
            k3dViewport,        //!< Rendering to an interactive 3d viewport
            k2dViewport,        //!< Rendering to an interactive 2d viewport 
                                //!< such as the render view
            kImage              //!< Rendering to an image
        RenderingDestination renderingDestination(MString & destinationName) const;

    MDrawContext allows for a copy of the current color or depth target to be created via these methods, respectively:

    • copyCurrentColorRenderTargetToTexture()
    • copyCurrentDepthRenderTargetToTexture()

    MDrawContext has a new method getInternalTexture() that gets an internal texture as specified by the InternalTexture enumeration. Currently, this allows for getting the current transparent depth layer and the opaque depth layer used in depth-peeling transparency. The dx11Shader effects file AutodeskUberShader.fx demonstrates the usage of this method.

    MPassContext has three new pass semantics, respectively: kTransparentPeelSemantic, kTransparentPeelAndAvgSemantic and kTransparentWeightedAvgSemantic. The dx11Shader effects file AutodeskUberShader.fx demonstrates the usage of these three pass semantics.

    A new plug-in is available that demonstrates the usage of this API for caching scene renders (viewRenderOverrideFrameCache). For more information, see Render target / frame caching.

Texturing Enhancements

  • MTexture supports updating a rectangular sub-region. The MTexture::update() method has an optional region argument which can be used to specify the region to be updated. If no region is specified, then the entire texture is updated.

    The sample plug-in hwApiTextureTest demonstrates sample code which inverts the colors for a sub-region of a texture.

  • The new MTextureManager::acquireTiledTexture() method is a convenience method that packs a series of images on disk into a single texture. This method can accept the result of MRenderUtil::exactFileTextureUvTileData() which can extract the UV tiling filenames and UV positions from file texture nodes. The sample plug-in hwApiTextureTest demonstrates sample code which reads all images in a folder and creates a single tiled texture.
  • MTextureManager has a new method, findTexture(), which can be used to search for a pre-acquired texture by name in the texture cache. This can be used to share hardware textures between different parts of the same plug-in or between completely different plug-ins.
  • MTextureManager::acquireTexture has new arguments.
    • MTexture* acquireTexture(const MString& filePath, const MString& contextNodeFullName, int mipmapLevels = 0, bool useExposureControl = true, const MString& layerName = MString(), int alphaChannelIdx = -1)

    contextNodeFullName is an input argument, expecting the full name of the node that owns the file. The original function without this argument remains, but has been deprecated.

    layerName and alphaChannelIndex are new optional arguments that can be used to load layers and alpha channels from PSD files. These arguments are only used when loading PSD files.

  • MRenderUtil::exactFileTextureName now has a new argument.
    • bool MRenderUtil::exactFileTextureName(const MString& baseName, bool useFrameExt, const MString& currentFrameExt, const MString& contextNodeFullName, MString& exactName, MStatus *ReturnStatus)

    contextNodeFullName is an input argument expecting the full name of the node that owns the file. The original function without this argument remains, but has been deprecated.

MViewportRenderer and MViewport2Renderer changes

MPxSubSceneOverride Enhancements

  • MPxSubSceneOverride now provides an optional functionality to render multiple instances of a render item at the same time. The new methods are as follows:

    The performance gain of rendering many instances via one render item can be substantial compared to creating one render item per instance. Use this feature when the instances of a render item are identical except for their transformation matrix; or, for simple float/float2/float3/float4 parameters on the shader instance. If the shader applied and the video card you are using both support GPU instancing, then Maya will render multiple instances of the render item using this feature.

    Instance transforms can be added one at a time, which allows for efficient individual updates or removals using the returned instance identifier. Alternatively, the transforms of all instances can be set in a single call via a matrix array. Similarly, per-instance float data can be associated with a parameter on the shader instance one instance at a time, or all at once via a float array.

    MPxSubSceneOverride has a new interface that indicates that further update calls are required. The method furtherUpdateRequired() can be overridden in derived classes for this purpose. The plug-in example code for apiMeshSubSceneOverride provides a simple example that uses this interface.

    If the sub-string “/subscene/volume/” is used for the classification of the registration of the override, then transparent render items will bypass the internal transparency algorithms and post effects. During a transparency pass, render items will be called to draw once.

MPxDrawOverride Enhancements

Geometry Enhancements

  • MVertexBuffer and MIndexBuffer now each offer a new method to set or update the geometry data they contain in a single function call. The new functions are:
    • MStatus update(const void* buffer, unsigned int destOffset, unsigned int numVerts, bool truncateIfSmaller);
    • MStatus update(const void* buffer, unsigned int destOffset, unsigned int numIndices, bool truncateIfSmaller);

    Use these functions instead of acquire()/commit() or map()/unmap() if the source data is already in the correct format for a simple memory copy operation into the destination buffer. In this situation, using update() should be more efficient and require fewer copy operations on the data.

    If the internal buffer had not previously been allocated via a call to commit, the buffer will be allocated. If the specified parameters require a larger buffer than had previously been allocated, the buffer will be reallocated to the new size.

    Calling MVertexBuffer or MIndexBuffer::unmap() in OpenGL mode will now reset the OpenGL buffer bindings for both GL_ARRAY_BUFFER_ARB and GL_ELEMENT_ARRAY_BUFFER_ARB to 0. This allows for more reliable readback of Maya hardware buffers while also directly interacting with the native graphics API.

    MVertexBufferDescriptor has a new optional constructor argument for supplying the semantic name at creation time. The semantic name is used to tag and identify different custom texture streams.

Geometry Extractor Enhancements

  • The constructor of MGeometryExtractor now provides a new enum parameter MPolyGeomOptions to replace the parameter sharing. The new enum MPolyGeomOptions is a collection of polygonal properties, including:
    • kPolyGeom_Normal: Indicates that the default base geometry is used.
    • kPolyGeom_NotSharing: Indicates that you do not want vertex sharing to be computed by the extractor.
    • kPolyGeom_BaseMesh: Indicates that the base geometry is in smoothCage mode.

    The old constructor function still remains, but as a deprecated method.

Shading Enhancements

  • MShaderManager has a new method:

    MShaderInstance* getShaderFromNode(const MObject& shaderNode, const MDagPath& path, LinkLostCallback linkLostCb = 0, MUserData* linkLostUserData = 0, MShaderInstance::DrawCallback preCb = 0, MShaderInstance::DrawCallback postCb = 0) const;

    Use this method to obtain an MShaderInstance from a particular node as translated by Maya. This method operates in a similar way to getEffectFileShader(), getEffectsBufferShader(), and getFragmentShader(); however, you can additionally supply a LinkLostCallback to get notified when the shader is no longer linked to the node from which it originates. Call this method again to acquire a new shader from the node once the callback has been triggered if you want parameter changes to continue to automatically update the acquired shader instance.

  • MShaderManager::getStockShader now supports four new enum types for acquiring shaders for diagnostic display.
    • k3dIntegerNumericShader can be used to acquire an instance of a stock shader for drawing single integer values per vertex for 3d rendering.
    • k3dFloatNumericShader can be used to acquire an instance of a stock shader for drawing single float values per vertex for 3d rendering.
    • k3dFloat3NumericShader can be used to acquire an instance of a stock shader for drawing 3 float values per vertex for 3d rendering.
    • k3dPointVectorShader can be used to acquire an instance of a stock shader that can be used for 3d rendering of lines based on a point and a vector stream
  • MShaderInstance has two new methods to allow for in-place modification:

    MStatus addInputFragment(const MString& fragmentName, const MString& outputName, const MString& inputName);

    MStatus addOutputFragment(const MString& fragmentName, const MString& inputName);

    Use these methods to modify the run-time code for an existing MShaderInstance by attaching a fragment of code registered with the MFragmentManager. The fragment is added by connecting the output of the new fragment with the input of the existing shader instance. These methods are meant to be used in conjunction with MShaderManager::getShaderFromNode() to alter the shader returned from Maya. This can be used to supply additional pattern inputs, adjust shader output, or supply vertex and geometry shaders to an existing fragment shader.

  • MShaderInstance has a new setParameter() interface that allows the setting of float parameters using an MFloatVector. The existing float pointer can be used to set parameters which are individual float values.
  • MShaderInstance has a new interface that allows the setting of matrix parameters using an MFloatMatrix.
  • A stock shader which can draw fat points, and the colors of which are determined by looking up a 1D ramp texture, is available via MShaderManager::getStockShader(). The new enumeration is : k3dColorLookupFatPointShader.
  • MPxShaderOverride has a new method supportsAdvancedTransparency() that returns information on whether it supports advanced transparency algorithms (such as depth peeling). The dx11Shader effects file AutodeskUberShader.fx demonstrates the usage of the method.
  • MUniformParameter::DataSemantic has two new semantics, respectively kSemanticTranspDepthTexture and kSemanticOpaqueDepthTexture, both of which are used for advanced transparency algorithms. The dx11Shader effects file AutodeskUberShader.fx demonstrates the usage of the two data semantics.

Fragment Enhancements

  • A new method, MFragmentManager::getFragmentXML(const MObject&, MString&, bool, const MDagPath*), has been added that allows the caller to retrieve the XML code for the fragment graph Maya would use to represent the given shading node in Viewport 2.0. This method can be helpful for determining how Maya builds up fragment graphs to render various shading node configurations in the viewport.

Renderer Enhancements

Dashline Pattern Changes

  • When using the mayaDashLineShader (for example, as in the gpuCacheSubSceneOverride example), ensure that the most significant bit of the dashPattern parameter (an unsigned short type integer) is set to 1; otherwise, artifacts may occur if the line becomes very short.

Swatch Rendering Enhancements

  • Several new methods have been added to MSwatchRenderBase to support background rendering of swatches. Derived classes should return true from renderParallel() if they support background rendering, and they must respond to cancel requests appropriately.
    • virtual bool renderParallel()
    • virtual void cancelParallelRendering()
    • void finishParallelRender()
    • static void cancelCurrentSwatchRender()
  • New methods have been added to MSwatchRenderBase to control the quality of the rendered image. Derived classes should increase the quality of the rendering as the render quality increases.
    • void setRenderQuality(int)
    • int renderQuality() const


DAG path Enhancements

  • MDagPath returns an additional new parameter value (fPlaybackVisible) when querying for draw override information. The information is part of the MDAGDrawOverrideInfo structure returned from the method MDagPath::getDrawOverrideInfo().

    fPlaybackVisible indicates if the draw override setting for visibility during playback has been set on the DAG object associated with the DAG path.

  • You can now query the dgtimer sub-metrics on the MFnDependencyNode via the enums kTimerMetric_callbackViaAPI and kTimerMetric_callbackNotViaAPI using the OpenMaya API. Previously these options were available, but always returned zero when queried.

  • The getConnectedSetsAndMembers() and getConnectedShaders() methods, available on MFnMesh, are now also available on MFnNurbsSurface.

  • Two virtual methods MPxAssembly::postApplyEdits() and MPxAssembly::postUnapplyEdits() have been added. The first is called by performActivate() after edits are applied to the current assembly (and all nested assemblies).

    The second is called by performInactivate() after unapplying edits, before any nested assemblies are inactivated, and before the current representation is inactivated with inactivateRep().

    These methods complement the existing preApplyEdits() and preUnapplyEdits() methods.

    You can use these methods to perform additional work after applying or unapplying edits. The default implementations of these two functions do nothing.

  • The following functions have been removed:
    • bool MFnAssembly::handlesApplyEdits(MStatus* status = NULL) const;
    • bool MPxAssembly::handlesApplyEdits() const
    • MStatus MPxAssembly::applyEdits(MObject& target , MItEdits& edits)


M3dView Enhancements

  • M3dView provides two new methods which can be used to obtain the resolution (width and height) of a Playblast:
    • int playblastPortWidth( MStatus * ReturnStatus = NULL );
    • int playblastPortHeight( MStatus * ReturnStatus = NULL );
  • Two new methods have been added to M3dView for scheduling viewport refreshes in a thread-safe manner. scheduleRefreshAllViews() forces all viewports in Maya to refresh the next time that Maya is idle, while scheduleRefresh() forces a specific view to refresh upon the next idle.
  • The Esc key (default abort key) now calls MPxContext::abortAction() when pressed. Override this method for your plug-in to perform specific operations when the Esc key is pressed.




Open Data

File Path Resolution

Standalone Metadata API (adsk::Data)

  • A number of additions have been made to the Accessor class:

    • A new variant of read() allows you to specify structures and associations that should be read, rather than the whole file.
    • The Accessor::isFileSupported() virtual method can be overridden to reject files which have the right extension, but are not supported by the Accessor (for example, the file version is too old).
    • The Accessor::accessorByExtension() static method returns the appropriate Accessor for a given file extension, if there is one.
    • The AccessorMaya derived class provides access to a Maya scene's metadata and also serves as an example of how to implement an Accessor.




Example plug-ins

The devkit/plug-ins/blastCmd and /hlslShader example plug-ins are now obsolete.

PyQt and PySide Widget Best Practices updated

The MayaQWidgetBaseMixin and MayaQWidgetDockableMixin classes in the module simplify the integration of PySide-based widgets by providing methods that: auto-name a widget, parent a widget to the Maya main window, dock a widget and so forth. See PyQt and PySide Widget Best Practices for more information.