Supporting Save to Previous

The save to previous feature allows a user to save a scene created in one version of 3ds Max (e.g. 3ds Max 2011) into a file version compatible with an earlier version of the product (e.g. 3ds Max 2010).

A plug-in developer does not need to do anything when the same version of the plug-in is used in both the old and new versions of 3ds Max, or when there has been no change to how the plug-in handles parameters and references. If plug-ins change how they handle parameter or references between versions, they should follow the guidelines listed below, and also those mentioned in the Guidelines for Changing the Reference Structure topic in order to properly support save to previous.

Guidelines for Changing Parameter Descriptors

• Use the P_VERSION flag and update the version number when changing the parameter block descriptor.
• Do not change the parameter block descriptor ID or owner reference ID.
• Do not change the type of an existent parameter.
• You may add a new parameter of the desired type at the end of the list of parameters and mark an old one obsolete using P_OBSOLETE .
• Do not change parameter IDs.
• Do not delete or move items in the enum defining the parameter IDs. Instead, add new parameter IDs at the end of the enum.
• Do not change the animatable state of a parameter (i.e. do not add or remove the P_ANIMATABLE flag). Instead, mark the old parameter as obsolete and create a new parameter at the end of the parameter list with the desired animatable state.
• You may add - but not remove or change - any of the following flags: P_NO_REF, P_OWNERS_REF , P_TRANSIENT , P_SUBANIM , P_READ_ONLY , and P_OBSOLETE.
• Non-animatable, and non-reference parameters can be added anywhere in the parameter block descriptor. Reference parameters are: TYPE_MTL, TYPE_TEXMAP, TYPE_INODE, TYPE_REFTARG, TYPE_PBLOCK2, TYPE_OBJECT, and TYPE_CONTROL, along with the corresponding TAB version. Animatable parameters are marked with P_ANIMATABLE.

Guidelines for Saving Plug-ins

• Use ISave::SavingVersion() or ::GetSavingVersion() function to determine which Max file format is used for saving your data.
• Adding a new chunk should be fine if your plug-in ignores unrecognized chunk IDs in its implementation of ReferenceMaker::Load().
• Removing an existent chunk is not acceptable.
• Be prepared to save out the data corresponding to the old chunk ID when 3ds Max signals that it is saving the file to a format compatible with a previous version of 3ds Max. The plug-in must call ISave::SavingVersion() to find this out.
• Changing the contents of an existent chunk is best handled as an addition of a new chunk and deprecation of the current chunk (e.g. ignoring it on load).

Animatable Structure Change Guidelines

You cannot change the sub-animatable structure of a plug-in and support save to previous. There's currently no general way to inform the previous release of what the new mapping is. Therefore, anything that depends on sub-animatable numbering (e.g. expression and wire controllers) will most probsbly crash or at least will not work properly.

Copying a Parameter Block 2 to a Parameter Block 1

When a plug-in is migrated from using parameter block 1 (class IParamBlock) to using parameter block 2 (class IParamBlock2) two responsibilities are particularly important:

The plug-in must support loading parameter block 1 versions of itself. This task is facilitated by the already-existing global function: IParamBlock2* UpdateParameterBlock2(ParamBlockDescID *pdescOld, int oldCount, IParamBlock *oldPB, ParamBlockDesc2* pdescNew, IParamBlock2* newPB);

The plug-in must also support saving parameter block 1 versions of itself (for supporting the save to previous functionality of 3ds Max). This task is facilitated by the following global function: int CopyParamBlock2ToParamBlock(IParamBlock2* pb2, IParamBlock *pb1, ParamBlockDescID *pdescPB1, int pb1Count);

Although parameter block 1 based plug-ins are still supported in 3ds Max, plug-in developers are encouraged to migrate their plug-ins to use the parameter block 2 system.

The Swirl plug-in is an example of a plug-in that uses these APIs to save a parameter block 1 based version of itself to previous versions of 3ds Max, while maintaining support for loading its old parameter block 1 version.