→Binary structure: write down the docs so someone else doesn't loose their sanity like I did |
add some corrections |
||
| (One intermediate revision by the same user not shown) | |||
| Line 31: | Line 31: | ||
=== LZMA Decoding === | === LZMA Decoding === | ||
In the case of LZMA encoding, the block is first started by 5 bytes of flags for encoding filters, then a pair of 8 byte Ulongs that describe the beginning and the end of the streams that encoded the binary stream. These must be written/read before starting the LZMA data, or the programming language will throw a corrupted data error. The LMZA data does not have an EOF or end of file marker, so some LZMA decoders can hit errors due to such. The LZMA encoded must not | In the case of LZMA encoding, the block is first started by 5 bytes of flags for encoding filters, then a pair of 8 byte Ulongs that describe the beginning and the end of the streams that encoded the binary stream. These must be written/read before starting the LZMA data, or the programming language will throw a corrupted data error. The LMZA data does not have an EOF or end of file marker, so some LZMA decoders can hit errors due to such. The LZMA encoded must not write an EOF marker. | ||
=== File Version 0 === | === File Version 0 === | ||
| Line 119: | Line 119: | ||
| KeyFrames || List of Frames || list of Frames that first starts with a binary encoded <code>Value Type</code> from [[#Decoding Tracks Binary structure]], then followed by a binary encoded float for the time position. this repeats for <code>Amount Of Frames</code>. || | | KeyFrames || List of Frames || list of Frames that first starts with a binary encoded <code>Value Type</code> from [[#Decoding Tracks Binary structure]], then followed by a binary encoded float for the time position. this repeats for <code>Amount Of Frames</code>. || | ||
|- | |- | ||
| Tangents || List of Tangent pairs || List of tangent pairs that starts with a binary encoded <code>Value Type</code> from [[#Decoding Tracks Binary structure]] for the right, followed by a binary encoded <code>Value Type</code> from [[#Decoding Tracks Binary structure]] for the left. this repeats for <code>Amount Of Frames</code>. || | | Tangents || List of Tangent pairs || List of tangent pairs that starts with a binary encoded <code>Value Type</code> from [[#Decoding Tracks Binary structure]] for the right, followed by a binary encoded <code>Value Type</code> from [[#Decoding Tracks Binary structure]] for the left. this repeats for <code>Amount Of Frames</code>. || Note: Only written if Tangents is true | ||
|- | |- | ||
|} | |} | ||
Latest revision as of 17:24, 15 December 2024
Please see AnimJ for an explaination on what an Animation file actually does and what this does.
Binary structure
An Animx is encoded in raw binary, and as such is a little difficult to decode.
The format is as follows in order as of version 1. (All is written and read by the System.IO.BinaryReader object):
| Name | Type | Summary | Notes | ||||
|---|---|---|---|---|---|---|---|
| Magic Word | String | "AnimX" to specify this file is Animx | |||||
| File Version | Byte | 0 to most recent for Version of file. | |||||
| Track Amount | 7 bit int | A number that says how many tracks are in the animation | |||||
| Global Duration | Single | How long the animation is in seconds | |||||
| Name | String | The name of the animation file | Encoding | Byte | The encoding of the rest of the file | 0 means read as normal default binary reader, 1 means LZ4 stream, and 2 means LZMA memory stream. | |
| Track Array | Track Array | The track types and their data | See Decoding Tracks |
Decoding Tracks Binary structure
When the decoder is decoding tracks, it uses the Activator class to create a new object of the track it is trying to decode.
LZMA Decoding
In the case of LZMA encoding, the block is first started by 5 bytes of flags for encoding filters, then a pair of 8 byte Ulongs that describe the beginning and the end of the streams that encoded the binary stream. These must be written/read before starting the LZMA data, or the programming language will throw a corrupted data error. The LMZA data does not have an EOF or end of file marker, so some LZMA decoders can hit errors due to such. The LZMA encoded must not write an EOF marker.
File Version 0
| Name | Type | Summary | Notes |
|---|---|---|---|
| Track Type | Byte | If TYPE is equal to 1, it is a Curve track type, if it is 0 it is a Raw track type. see Type:TrackType. | |
| Value Type | NONE SEE NOTES | is equal to Track Type >> 1 (a bitshift) |
This doesn't read a byte for this file version strangely. just sets the variable for Value Type for what is explained in summary.
|
File Version 1
| Name | Type | Summary | Notes |
|---|---|---|---|
| Track Type | Byte | converts the number directly based on the enum values of Type:TrackType | |
| Value Type | Byte | Uses #ElementTypesTable to convert to the proper type |
ElementTypesTable
all bytes are in Little Endian
| Name | Value | Description |
|---|---|---|
bool
|
0 | Byte with starting 1 bits being the value |
bool2
|
1 | Byte with starting 2 bits being the value |
bool3
|
2 | Byte with starting 3 bits being the value |
bool4
|
3 | Byte with starting 4 bits being the value |
byte
|
4 | Byte |
ushort
|
5 | 2 Bytes |
uint
|
6 | 4 Bytes |
ulong
|
7 | 8 Bytes |
sbyte
|
8 | 1 Byte |
short
|
9 | 2 Bytes |
int
|
10 | 4 Bytes |
long
|
11 | 8 Bytes |
int2
|
12 | 8 Bytes |
int3
|
13 | 12 Bytes |
int4
|
14 | 16 bytes |
uint2
|
15 | 8 Bytes |
uint3
|
16 | 12 Bytes |
uint4
|
17 | 16 Bytes |
long2
|
18 | 16 Bytes |
long3
|
19 | 24 Bytes |
long4
|
20 | 32 Bytes |
float
|
21 | 4 Bytes |
float2
|
22 | 8 Bytes |
float3
|
23 | 12 Bytes |
float4
|
24 | 16 Bytes |
floatQ
|
25 | 16 Bytes (x,y,z,w) |
float2x2
|
26 | 16 bytes arranged by rows starting at top left down to bottom right. |
float3x3
|
27 | 36 bytes arranged by rows starting at top left down to bottom right. |
float4x4
|
28 | 64 bytes arranged by rows starting at top left down to bottom right. |
double
|
29 | 8 Bytes |
double2
|
30 | 16 Bytes |
double3
|
31 | 24 Bytes |
double4
|
32 | 32 Bytes |
doubleQ
|
33 | 40 Bytes |
double2x2
|
34 | 32 Bytes arranged by rows starting at top left down to bottom right. |
double3x3
|
35 | 72 Bytes arranged by rows starting at top left down to bottom right. |
double4x4
|
36 | 128 Bytes arranged by rows starting at top left down to bottom right. |
color
|
37 | 16 Bytes which is 4 floats for RGBA |
color32
|
38 | 4 bytes which is 4 bytes for RGBA |
string
|
39 | starts with a 7 bit encoded int with the amount of string bytes. each char is 1 byte also known as UTF-8. NOTE: This begins with a nullable 1 byte boolean if being written as part of a string animation track value. (aka Discrete or Raw string animation track) |
Tracks
It then decodes the track data based on one of the TrackTypes.
Raw
| Name | Type | Summary | Notes |
|---|---|---|---|
| Node | String | See AnimJ | |
| Property | String | See AnimJ | |
| Amount Of Frames | 7 bit integer | See AnimJ on what frames are. these are encoded with no empty frames between. | |
| Interval | Float | See AnimJ | |
| Elements | Array of Value Type from #Decoding Tracks Binary structure |
A list of encoded binary values stacked on each other Amount Of Frames times. |
See #ElementTypesTable on how to decode each value type |
Discrete
| Name | Type | Summary | Notes |
|---|---|---|---|
| Node | String | See AnimJ | |
| Property | String | See AnimJ | |
| Amount Of Frames | 7 bit integer | See AnimJ on what frames are. these are encoded with no empty frames between. | |
| Frames | Array of Frames | list of Frames that first starts with a binary encoded float for the time position, then followed by a binary encoded Value Type from #Decoding Tracks Binary structure. this repeats for Amount Of Frames. |
Curve
| Name | Type | Summary | Notes |
|---|---|---|---|
| Node | String | See AnimJ | |
| Property | String | See AnimJ | |
| Amount Of Frames | 7 bit integer | See AnimJ on what frames are. these are encoded with no empty frames between. | |
| Separate Interpolations && Tangents | Byte | See AnimJ for what these do | Starting bit represents if it has different interpolations per frame, second bit represents if it has tangents |
| Interpolations | Byte array | Has a length of Amount Of Frames and the numerical value of the Type:KeyframeInterpolation enum. |
NOTE!!! ONLY IF: Shared Interpolations is true this will be written!!!
|
| Shared Interpolation Type | Byte | A byte representing the numerical value of the Type:KeyframeInterpolation enum. | NOTE!!! ONLY IF: Shared Interpolations is false this will be written!!!
|
| KeyFrames | List of Frames | list of Frames that first starts with a binary encoded Value Type from #Decoding Tracks Binary structure, then followed by a binary encoded float for the time position. this repeats for Amount Of Frames. |
|
| Tangents | List of Tangent pairs | List of tangent pairs that starts with a binary encoded Value Type from #Decoding Tracks Binary structure for the right, followed by a binary encoded Value Type from #Decoding Tracks Binary structure for the left. this repeats for Amount Of Frames. |
Note: Only written if Tangents is true |
Bezier
NOT SUPPORTED YET.
Using the data or encoding the data
Using the data or encoding the data can be done by using Python's struct library or a programming language with the binary reader of your choice.
Make sure to use LittleEndian when reading and writing the binary.
Tools that can decode and write AnimX easier
- TODO