Internal Animation Format
Overview
From a programming perspective, there are several steps to uploading an animation from a BVH (BioVision Hierarchy) file:
- Read and parse the BVH file, creating an LLKeyframeMotion object containing the motion data.
- Gather input from the user (via the upload preview floater) for things like animation priority, facial expression, and looping; these settings are stored in the LLKeyframeMotion object.
- Serialize the LLKeyframeMotion object as LLSD.
- Upload the serialized data to the asset server.
Before other viewers can play an animation, they must:
- Download the serialized data from the asset server.
- Deserialize it to an LLKeyframeMotion object.
Relevant source files:
Note: binary file write is little Endian.
Header
The first part of the animation data is a header describing various details about the animation as a whole. The elements, in order, are:
field name | description | LLSD type | C++ type | Note |
---|---|---|---|---|
version | integer | U16 | ||
sub_version | integer | U16 | ||
base_priority | integer | S32 | ||
duration | real | F32 | ||
emote_name | string | std::string | ||
loop_in_point | real | F32 | ||
loop_out_point | real | F32 | ||
loop | integer | S32 | 0: not looped, 1: looped | |
ease_in_duration | real | F32 | ||
ease_out_duration | real | F32 | ||
hand_pose | integer | U32 | ||
num_joints | integer | U32 |
Joint Data
After the header is data for each joint in the skeleton: Note: Unused bones need not be included in the file.
field name | description | LLSD type | C++ type | Note |
---|---|---|---|---|
joint_name | string | std::string | ||
joint_priority | integer | S32 |
Joint Rotation Keys
At the start of the rotation data for each bone is the total number of rotation keys: If the bone has no rotation based keyframes, this value must be 0.
field name | description | LLSD type | C++ type | Note |
---|---|---|---|---|
num_rot_keys | integer | S32 |
Then, for each rotation key:
Note: These three values X Y Z appear to be the first three values of a truncated quaternion with the W term being calculated afterwards. Since a quaternion is X2 + Y2 + Z2 + W2 = 1 as long as you assume the W term has a consistent sign the X Y Z terms will be accurate.
field name | description | LLSD type | C++ type | Note |
---|---|---|---|---|
time | integer | U16 | 0: first frame, 65535: last frame | |
rot_angle_x | integer | U16 | 0:-1, 32767:0, 65535:+1 | |
rot_angle_y | integer | U16 | ||
rot_angle_z | integer | U16 |
Joint Position Keys
At the start of the position data is the total number of position keys: If the bone has no position based animations, this value must be 0.
field name | description | LLSD type | C++ type | Note |
---|---|---|---|---|
num_pos_keys | integer | S32 |
Then, for each position key, position data is measured from Avatar Center ( mPelvis ), not joint resting position
( IE [0,0,0] is not joint resting position, it'll be the bone's position in parent coordinate space)
with the exception of the mPelvis bone which is stored in world space coordinates.:
field name | description | LLSD type | C++ type | Note |
---|---|---|---|---|
time | integer | U16 | 0: first frame, 65535: last frame | |
pos_x | integer | U16 | 0: -5M, 32767: 0M, 65535: +5M | |
pos_y | integer | U16 | pos measured from AV COG not joint offset | |
pos_z | integer | U16 |
Constraints
After the joint data are a number of entries for joint constraints. Constraints can target an avatar's parts in relation to each other or the ground.
field name | description | LLSD type | C++ type | Note |
---|---|---|---|---|
num_constraints | integer | S32 |
Then, for each joint constraint:
field name | description | LLSD type | C++ type | Note |
---|---|---|---|---|
chain_length | integer | U8 | number of attached joints to include | |
constraint_type | integer | U8 | 0: point, 1: plane | |
source_volume | string | U8[16] array | skeleton collision volume name | |
source_offset | string (?) | LLVector3 | ||
target_volume | string | U8[16] array | skeleton collision volume name | |
target_offset | string (?) | LLVector3 | ||
target_dir | string (?) | LLVector3 | value is currently ignored | |
ease_in_start | real | F32 | ||
ease_in_stop | real | F32 | ||
ease_out_start | real | F32 | ||
ease_out_stop | real | F32 |