HumanIK Objects and Memory Management

Object Memory Requirements

HumanIK objects have the following memory requirements:

HIKCharacters

The size of an HIKCharacter depends on its configuration.

The base size of an HIKCharacter is 9616 bytes.
Each Node used by the HIKCharacter requires an additional 240 bytes.
Each Node configured with Degrees of Freedom requires an additional 192 bytes.
Each Node with a parent offset requires an additional 48 bytes, unless that node also has Degrees of Freedom (the value given for DOF above includes a 48-byte parent offset).

You can determine the current size in memory of an existing HIKCharacter by calling the HIKCharacterSize() function. This function requires one argument: a pointer to the HIKCharacter.

Alternatively, you can determine the expected size in memory of an HIKCharacter before creating it by calling the HIKCharacterDefinitionSize() function. This function requires one argument: the HIKCharacterDefinition that will be used to create the HIKCharacter.

HIKCharacterStates

The size of an HIKCharacterState depends on how many Nodes its HIKCharacter uses.

The base size of an HIKCharacterState is 144 bytes.
Each Node used by the character requires an additional 96 bytes.

You can determine the current size in memory of an existing HIKCharacterState by calling the HIKCharacterStateSize() function. This function requires one argument: a pointer to the HIKCharacterState.

HIKEffectorSetStates

Every HIKEffectorSetState requires 3296 bytes.

HIKPropertySetStates

Every HIKPropertySetState requires 1936 bytes.

Creating objects by allocating and de-allocating memory

All functions within HumanIK that need to allocate memory, such as the functions introduced in the Getting Started with HumanIK chapter for creating HIKCharacters, HIKCharacterStates, HIKEffectorSetStates and HIKPropertySetStates, require a reference to a callback function used to allocate that memory. You can use the standard malloc function, or any other custom memory allocation function that follows the same type definition as malloc.

Similarly, the functions introduced in the Getting Started with HumanIK chapter for destroying these objects require a reference to a callback used for freeing the memory resources allocated for that object. You can use the standard free function, or any other custom memory allocation function that follows the same type definition as free.

For example, the following code creates and destroys an HIKCharacterState using malloc and free.

HIKCharacterState* lcharacterState = HIKCharacterStateCreate(character1, &malloc);
...
HIKCharacterStateDestroy(lcharacterState, &free);

Creating objects in pre-allocated memory

Instead of allocating new memory each time you create an HIKCharacter, HIKCharacterState, HIKEffectorSetState or HIKPropertySetState, you can create new HumanIK objects at specified locations within pre-allocated memory buffers. Pre-allocating a single pool of memory and creating all your related HumanIK objects at specified pointers within that buffer allows you to keep related HumanIK objects within continuous blocks of memory, which can improve performance.

To create objects in this way, call the HIKCharacterCreateInPlace(), HIKCharacterStateCreateInPlace(), HIKEffectorSetCreateInPlace() and HIKPropertySetCreateInPlace() functions. These functions require the same arguments as the object creation functions introduced in the Getting Started with HumanIK chapter, except that instead of requiring a reference to a callback function for allocating memory, they require a void pointer to a valid memory location. This pointer must be 16-byte aligned, and the buffer must be large enough to contain the object created. See HumanIK Objects and Memory Management above.

For example:

HIKCharacterState* lcharacterState = HIKCharacterStateCreateInPlace(character1, bufferAlignedTo16);

In this scenario, the allocation and de-allocation of the memory buffer is most likely handled externally to HumanIK; therefore, when you create an object in this way you typically do not need to destroy the object explicitly through a call to the HumanIK object destruction functions introduced in Cleanup.

Using contiguous memory blocks

For best performance, it is highly recommended that you allocate all related objects in a single, continuous block of memory whenever possible. For example, try to allocate the HIKCharacter object that represents each of your game characters adjacent to all related HIKCharacterState, HIKEffectorSetState and HIKPropertySetState objects used by that character, within a single continuous block of memory. This minimizes the amount of skipping the HumanIK solvers need to perform between different locations in memory when reading and writing data.

Moving objects in memory

You can move HIKCharacters, HIKCharacterStates, HIKEffectorSetStates and HIKPropertySetStates freely between different memory locations. This approach allows you to load the HIK objects into memory using a custom streaming process, and to retrieve the objects directly from your custom stream for use in your game.

Creating objects from files

You can load previously saved HIKCharacters, HIKCharacterStates, HIKEffectorSetStates and HIKPropertySetStates from files. For details, see Saving and Loading HumanIK Objects.