Workflows for Setting and Retrieving Data

HumanIK offers you the choice of two high-level approaches when setting and retrieving animation data, described below.

Setting and retrieving data iteratively

HumanIK offers a wide variety of different functions for setting and retrieving the translation, orientation and scaling of a single Node in an HIKCharacterState or a single Effector in an HIKEffectorSetState. In order to set or retrieve data for multiple different Nodes or Effectors, you can iterate through each desired Node or Effector, calling one of these functions once for each Node or each Effector.

This approach is conceptually straightforward, and is particularly suitable for setting or retrieving data for a small number of Nodes or Effectors. For example, if you are writing an IK controller that assigns a goal point to a single limb, you could use one of these functions to set the translation of the corresponding Effector. However, when you need to set or retrieve data for many Nodes or Effectors (for example, when retrieving the results of a solve contained in an HIKCharacterState to apply the pose back to your game engine character) this approach is less efficient than using the data set approach described below.

Setting and retrieving data using a data set

Instead of using separate function calls to set and retrieve data for each Node in an HIKCharacterState or each Effector in an HIKEffectorSetState, you can synchronize the state of multiple Nodes at once through the use of a data set and an accompanying data description.

This approach is typically much faster than using the iterative approach described above, and has the additional advantage of reducing the number of function calls required. However, this approach does require some more advanced setup and memory management in order to get it up and running.

Data sets

A data set is a single continuous block of memory that can contain the translation, orientation and scaling of multiple Nodes or Effectors. The pointer to this data set must be aligned on 16 bytes.

Data blocks

Within a data set, the information for each Node or Effector is contained sequentially in a discrete data block. The first data block contains all the relevant data for one Node or Effector, the next data block contains the same data for the next Node or Effector, then the next Node or Effector, etc. Each data block must be constructed in exactly the same way: the offset of each type of data within the data block and the total size (or stride) of the data block must be exactly the same for all Nodes or Effectors. For example, if the translation data for a Node is located at an offset of 32 bytes for one data block, it must be located at that same offset within all other data blocks as well. All offsets within a data block must be aligned on 16 bytes.

Data blocks may also contain other arbitrary data not used by HumanIK, if it is convenient for you to include such data for your own purposes.

Data descriptions

Accompanying each data set, you must provide a data description. A data description is a structure that defines the memory layout of your data set—i.e. the order in which the Nodes or Effectors are defined (which data blocks apply to which Node IDs or Effector IDs), the offsets of the translation, rotation and scaling data within each data block, and the stride of the data (the total size of each data block).

The structure you must use for your data description depends on whether you are setting and retrieving data in HIKCharacterStates or in HIKEffectorSetStates, and whether you represent your animation data using transform matrices or separate translation, orientation and scaling values.