What's New in Maya API in 2018

Important updates to the Maya API

Maya 2018 includes a number of API updates and additions that require you to recompile your plug-ins as well new ways to make plug-in development more efficient. The updates include:

New OpenMaya namespace

Maya 2018 introduces a new OpenMaya namespace. This is part of the effort to deliver an API that minimizes disruptions to Maya plug-in development and extend binary compatibility of the Maya API over multiple updates. The OpenMaya namespace covers all of the Open Maya API modules (OpenMaya, OpenMayaUI, OpenMayaRender, OpenMayaFx, OpenMayaAnim).

To adopt the OpenMaya namespace:

• All plug-ins built against previous versions of the Maya API need to be recompiled under the new Autodesk::Maya::OpenMaya20180000 namespace to update the API symbols.

  In most cases, this does not require any action for plug-ins. The compiler will resolve symbols to the namespaced symbols automatically.

• Remove all forward declarations of the OpenMaya classes. All of these classes get automatically forward declared by MApiNamespace.h to resolve to the correct version of the class.
• If you have modified the buildconfig file or Xcode project file to promote the symbols below to global scope, you must remove them:

  LFLAGS += -Wl,-exported_symbol,__Z16initializePlugin7MObject
  \
  

  -Wl,-exported_symbol,__Z18uninitializePlugin7MObject

Support for C++11 Keywords

To support the VFX Reference Platform, the Maya 2018 API now supports C++11 features. This includes C++11 new keywords in the header files such as nullptr, final, and override. When compiling plug-ins against this API using previous versions of C++, you may get errors such as:

error: ?nullptr? was not declared in this scope

In most cases, the error appears due to the absence of nullptr in C++ 98.

Updated deprecation marking system

Starting with Maya 2018, deprecated methods are marked using the OPENMAYA_DEPRECATED C++ attribute. For example:

OPENMAYA_DEPRECATED(version, "message")

The new marking system generates compiler warnings when marked methods got called. This allows you to remove deprecated methods from plug-ins at your convenience. An example of such warning:

warning C4996: 'MPxTransform::validateAndSetValue': Override validateAndSetValue(const MPlug&, const MDataHandle&) instead. If needed, useMDGContext::current() to get the context.

If you enabled treat warning as error on your compiler and experienced a related build error during your migration, you can disable the deprecation warnings.

To silence the deprecation warnings, you can

• Define a preprocessor macro:
  • _OPENMAYA_DEPRECATION_DISABLE_WARNING
• Use the following compiler switches:

  MSVC	/Wd"4996"
  ICC	-diag-disable 1786
  Clang	-Wno-error=deprecated-declarations
  GCC	-Wno-error=deprecated-declarations

To treat deprecation as an error, your can:

• Define the following preprocessor macro:
  • _OPENMAYA_DEPRECATION_ERROR_2018
  • _OPENMAYA_DEPRECATION_ERROR_ALL
• Or, use the following compiler switches:

  MSVC	/We"4996" (/D_CRT_NONSTDC_NO_DEPRECATE)
  ICC	-diag-error 1786
  Clang	-Werror=deprecated-declarations
  GCC	-Werror=deprecated-declarations

For information about backwards compatibility for deprecated methods and overriding deprecated methods, see Deprecating Maya API.

Evaluation using current context

Maya 2018 introduces the concept of current evaluation context to the Maya API. New methods and a new evaluation schema provide a more efficient way to code context evaluation.

In previous versions of Maya, if you want to evaluate something at a context other than the normal one, you pass in the context to the method. For example:

MPxTransform::getTranslation( MSpace::Space, const
MDGContext&, MStatus* );

Doing this often creates long chains of methods that pass the context in for no other reason than to pass it on to the next method. The concept of current evaluation context, along with new utilities, no longer makes this necessary. You can now :

• Get the current context using MDGContext::current().
• Set the current context using MDGContext::makeCurrent().
• Temporarily set the current context in a scoped code block using MDGContextGuard guard(temporaryCurrentContext);.

You can continue using existing methods that have a context parameter, but a context-free variation is recommended. For example:

return myTransform.getTranslation(MSpace::kTransform, myNewContext, &status);

is now functionally equivalent to:

                {
                                MDGContextGuard ctxGuard( myNewContext );
                                return myTransform.getTranslation( MSpace::kTransform, &status );
                }

In most cases, myNewContext is unnecessary as most code should evaluate in the current context. Exceptions include things like time-based caching and ghosting, where you would deliberately want to evaluate at an alternate context.

If you have a long sequence of calls in a different context to make, then you can use a scoped change of the current context. For example:

                {
											MDGContextGuard tempContext( myDifferentContext );
                                firstPlug.getValue( value1 );
                                secondPlug.getValue( value2 );
                                thirdPlug.getValue( value3 );
                …
}

Avoid passing the context around through different methods. Always use the current context to keep your code safe for multi-threaded evaluation.

Workspace controls

Use workspace controls to create custom UI that can be dragged, docked and saved within Maya's workspaces system. You can create workspace controls using the workspaceControl command. Workspace controls replace the dockControl command previously used to create dockable UI. The dockControl functionality is no longer supported. This means you should not create a window with internal UI and then attach it to a dockControl command call via the content flag.

You can create workspace controls using MEL, Python, and C++. For more information, see Writing Workspace controls.

For a Python example, see the dockableWorkspaceWidget.py example in the pythonScripts directory of the Maya devkit.

For a C++ example, see the workspaceControlCmd.cpp example in the Maya API

Updated Maya Viewport 2.0 whitepapers

The Maya Viewport 2.0 API Porting Guide has been updated to include changes to the Maya 2018 API. The updated whitepapers also analyze the choices for porting plug-in locators (MPxLocatorNode) to Viewport 2.0.

The Maya Viewport 2.0 whitepapers can be found at http://www.autodesk.com/developmaya.

API version and binary compatibility

Maya's API version has been updated (MAYA_API_VERSION is now 20180000). Note that all plug-ins compiled against Maya 2018, including Maya 2017 Update 1, 2, 3 or 4, must be re-compiled against Maya 2018 in order to be recognized by this version of Maya.