The AnimHandle system enhances sorting and searching of 3ds Max scene entities by providing a new type of identifier for Animatable objects. All Animatables have an AnimHandle. It is possible to retrieve any Animatable using its AnimHandle. An Animatable's AnimHandle is unchanging within a 3ds Max session, and the system does not reuse them for newer Animatables during a 3ds Max session. After an Animatable is deleted, attempting to retrieve it from its handle is completely safe, the system indicates the object is deleted by returning NULL.

AnimHandles are ideal as key values when sorting Animatable objects, including ReferenceTargets and other derived types, into a data structure. However, they are not saved to disk, and a given object will not have the same AnimHandle when the file is next loaded from disk.

An AnimHandle is an unsigned integer set to 1 when the application launches, is incremented by 1 for Animatable created, and is never reset, even if you load a scene and reset repeatedly. Thus, each Animatable receives a greater-valued handle than the previous for the duration of the 3ds Max session.

The only possible case of handle re-use is an error condition called wrap-around, when sufficient Animatables have been created to cause the handle counter to wrap around to zero. This requires creating 2^32 Animatables for 32-bit builds, or 2^64 Animatables for 64-bit builds, in one session without shutting down 3ds Max.

Using AnimHandles

Animatables may be fetched from their handle, and the handle may be fetched from an Animatable, using the following two static methods, respectively:

static AnimHandle Animatable::GetHandleByAnim( Animatable* anim );
static Animatable* Animatable::GetAnimByHandle( AnimHandle handle );

If an Animatable has been deleted, then GetAnimByHandle() on that object returns NULL. Also, GetAnimByHandle() performs a binary search lookup, requiring time based on the number of existing Animatables expressed by:

AnimHandles are not pointers to Animatables they remain safe if the Animatable is deleted, and are ideal for use as sorting/hash keys. Since the handles strictly increase in value each time one is assigned, new Animatables can be added to the end of a list Animatables sorted by AnimHandle. Since the handles are not re-used, there will never be a key collision between two different Animatables, even if one or both have been deleted.

A given object in a scene is assigned different handle value each time the scene is loaded. The order of handles could change between loads, an object with a higher handle value on one occasion might have a lower handle value on another occasion.

AnimHandles are not Node Handles

Do not confuse Node Handles with Animatable Handles: they are actually quite different. A node handle is a unique permanent ID, saved with the scene, and pertains to Node objects only. An AnimHandle is an instance count. It is unique within one session of 3ds Max, but not permanent across file loads. Every Animatable has an AnimHandle, not just nodes.

Node handles:

• uniquely define an object within the scene
• are saved with the scene
• usually never change; but, when an object is XRef'd into another scene, it is given a new handle.
• are NOT assigned in the constructor. After a Node is created, the handle is assigned only after its Load() operation, and after it is added to the scene. Any code using them needs extra logic to ensure node handles are valid.

AnimHandles:

• uniquely define an object within a scene.
• are NOT saved with the scene.
• assigned in the Animatable's constructor when they become immediately valid and never change.
• will NOT have the same value for the same Animatable when the file is next loaded.
• strictly increase and never reset until 3ds Max is shut down.
• are ideal for sorting and searching, assuming your data structure does not persist across load/save.