Deprecating Maya API

Updated deprecation marking system

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

OPENMAYA_DEPRECATED(version, "message")

The 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

Backwards compatibility for deprecated methods

In the following example, a function call to both getMatrix() and getMatrix(const MDGContext&) work by default (Except calling API from its overridden methods. See Overriding deprecated methods below for details.

class MPxTransform { 
    public: 
        virtual MMatrix getMatrix(); // New api, default to redirect the call to the old method 
    obsolete_2018:  
    OPENMAYA_DEPRECATED(2018, "Call getMatrix(MStatus*) instead.”) 
        virtual MMatrix getMatrix(const MDGContext&); 
}

Overriding deprecated methods

When overriding new and deprecated API, you can override either of them, but not both. You should not call deprecated API from new API’s override or the vice versa.

See the following examples:

To override the new API:

class UserTransform : public MPxTransform {
    MMatrix getMatrix() override;
};

To override deprecated API:

class UserTransform: public MPxTransform {
    MMatrix getMatrix(const MDGContext&) override; // deprecated
};

DO NOT override both API in one inheritance hierarchy :

class UserTransform: public MPxTransform { 
    MMatrix getMatrix() override; // new 
    MMatrix getMatrix(const MDGContext&) override; // deprecated 
}; // Error, override both API in one class 

class UserTransformBase: public MPxTransform { 
    MMatrix getMatrix(const MDGContext&) override; // deprecated 
}; // Ok 
class UserTransformDerived: public UserTransformBase {  
    MMatrix getMatrix() override; // new 
}; // Error, override both API in one inheritance hierarchy

DO NOT call deprecated API from new API’s override (or call new API from deprecated API override):

class UserTransform: public MPxTransform { 
     MMatrix getMatrix() override { 
       return MPxTransform::getMatrix(); // OK 

       //return MPxTransform::getMatrix(MDGContext::current()); // Error, calling deprecated API from new API overridden 
       } 
};