Difference between revisions of "IFP"

From GTAMods Wiki
Jump to navigation Jump to search
m
 
(17 intermediate revisions by 6 users not shown)
Line 1: Line 1:
IFP is the animation format of the Grand Theft Auto series since [[Category:GTA_3|GTA III]]. With [[Category:GTA_SA|GTA San Andreas]] there came a new version of the file format, but it still supports animations with the old version. IFP files can contain several single animations which are split up to objects and linked to the animated object or actor in that way. Each object contains a certain number of frames including a time key. Two frames are interpolated by the game.
+
{{File-stub}}
 +
'''IFP''' is the animation format of the Grand Theft Auto series since [[GTA 3|GTA III]]. With [[GTA San Andreas]] there came a new version of the file format but it still supports animations of the old version. IFP files can contain several single animations which are split up to objects and linked to the animated object or actor in that way. Each object contains a certain number of frames including a time key. Two frames are interpolated by the game.
  
==File Specification==
+
== File Specification ==
  
===Version 1===
+
Animation packages are building a simple hierarchy which is constant over all versions. Basicly each ''animation file'' consists of an header storing general file information. This header is followed by the ''animations'' themselves. In this way one animation file stores animations just like [[IMG|archive]] files holds different data as a flat list.
Version 1 packages are split up as usual into several data structures. The values of those structures are identified by 4 byte information markers. Those are 4 characters describing the following value(s). Note that the only markers which are realy used are "DGAN" and "NAME". All others are simply waste of space. Do not search for them in your code, because not all animations got information markers where they are expected. Sometimes they are also simply zero.
 
  
Offsets are always relative to the current file position. To convert a relative offset to an absolute one just add the number of read bytes.
+
Each animation consists of multiple ''objects'' representing a bone of the [[Model File|model]] the animation gets linked to. Each object holds a list of ''frames''. Those define information about the mathmatical description of the object in the world like [[wikipedia:Translation_(geometry)|translation]], [[wikipedia:Scaling_(geometry)|scaling]] and [[wikipedia:Rotation_(geometry)|rotation]].
Strings are always padded to 4 byte bounds. The "AnimNameLength" string after the "NAME" information marker descripes the string including the terminating zero-byte. You have to round up this value until the number is able to be divided by 4 without any rest, to get the number of bytes you have to write.
 
  
 +
The following structure shows an abstract animation tree:
  
====Header====
+
IFP File
4b   - FourCC  - "ANPK" (Animation Package, Version identifier)
+
  |
4b   - Int32   - Offset to the end of the file
+
   +-- Animation
4b   - FourCC   - "INFO"
+
   |    |
4b   - Int32   - Offset to end of header
+
  |    +-- Object
4b   - Int32   - Number of animations
+
  |    |   |
Xb  - Char[X] - Null-terminated string (internal file name used in the script)
+
  |    |    +-- Frame
 +
   |    |    +-- Frame
 +
   |    |    +-- ...
 +
  |    |
 +
  |    +-- Object
 +
  |    |    |
 +
   |    |    +-- Frame
 +
  |   |    +-- Frame
 +
   |    |    +-- ...
 +
  |   |
 +
  |    +-- ...
 +
  |
 +
  +-- Animation
 +
  |    |
 +
  |    +-- ...
 +
  |
 +
  +-- ...
 +
 
 +
This tree is just an indirect result of the simple structure hierarchy of [[IFP#Version_1|version 1]] but parsers may use it for both versions.
 +
 
 +
==== Data types ====
 +
 
 +
By default animation packages are using the following data types:
 +
* '''CHAR''' - [[wikipedia:ASCII|ASCII]] encrypted character ''(1 byte)''
 +
* '''INT32/UINT32''' - signed/unsigned 32 bit integer ''(4 byte)''
 +
* '''FLOAT''' - single precision floating point number ''(4 byte)''
 +
* '''TVector3''' - FLOAT[3] ''(12 byte)''
 +
* '''TVector4''' - FLOAT[4] ''(16 byte)''
 +
 
 +
=== Version 1 ===
 +
 
 +
==== Strings ====
  
====Animation====
+
Even though strings are null terminated they are aligned to a 4 byte padding what means that their length (including the terminating zero byte) must be a multiple of 4. The trailing bytes are usually zero, too. The following part of the article uses '''TString''' for identifying string types. All those strings are following the rule descriped in here.
4b  - FourCC  - "NAME"
 
4b  - Int32    - Length of the name of the animation (X)
 
Xb  - char[X]  - Animation name (null-terminated string)
 
4b  - FourCC  - "DGAN"
 
4b  - Int32    - Offset to the end of the animation (including it's content)
 
4b  - FourCC  - "INFO"
 
4b  - Int32    - Offset to first object (usually 0x08)
 
4b  - Int32    - Number of objects in the animation
 
4b  - Int32    - NULL
 
  
====Object====
+
==== Data structures ====
4b  - FourCC  - "CPAN"
 
4b  - Int32    - Offset to end of object
 
4b  - FourCC  - "ANIM"
 
4b  - Int32    - Offset to the start of frames (usually 0x2C)
 
28b  - Char[28] - Object name (null-terminated string)
 
4b  - Int32    - Number of frames
 
4b  - Int32    - NULL
 
4b  - Int32    - Next sibling
 
4b  - Int32    - Previous sibling
 
  
====Frame Info====
+
Version 1 packages are introducing some additional data structures. Those are always indicated by an 4 byte constant length string. The following table lists the different data structures and their formats. All data structures are inherting from an abstract base data structure. This base data structure must not be used inside the file (also this would not make sense since it does not hold any data except information about identifying itself). The whole file follows this rules so animation package itself can be seen as one section.
4b  - FourCC  - Type
 
4b  - Int32    - End of frame data
 
  
=====Frametypes=====
+
<table width="100%" border="0" cellspacing="8">
Frametypes define the size and the content of a frame. Actually there are 3 known types. Each frametype identifier starts with K which corresponds to "Keyframe". The following 3 bytes define the order and the content of the data. They are ASCII encoded characters
+
<tr><th>Structure and description</th><th>Specification</th></tr>
 +
<tr><td>
 +
;BASE: Abstract base section.<br>''(8 byte)''
 +
</td><td>
 +
identifier  : CHAR[4]
 +
offset      : UINT              // offset to the end of the section
 +
// Note: Offsets are always relative to the current file position.
 +
</td><td>
 +
<tr><td>
 +
;ANPK: Major section of the file.<br>
 +
</td><td>
 +
information : INFO<TAnimation>  // section information data (see [[IFP#Animation|below]])
 +
</td><td>
 +
<tr><td>
 +
;INFO<T>: Collection of multiple sub sections of type T.<br>
 +
</td><td>
 +
entries    : INT32            // (count of encapsuled sections)
 +
name        : TString          // (name of the collection)
 +
sections    : T[entries]        // Subsections
 +
</td><td>
 +
<tr><td>
 +
;NAME: Holds an string.<br>
 +
</td><td>
 +
name        : TString
 +
</td><td>
 +
<tr><td>
 +
;DGAN: Holds data for '''TAnimation'''.<br>
 +
</td><td>
 +
anim. info  : INFO<CPAN>
 +
</td><td>
 +
<tr><td>
 +
;CPAN: Holds data for ''animation objects''.<br>
 +
</td><td>
 +
object info : ANIM
 +
</td><td>
 +
<tr><td>
 +
;ANIM: Holds data for ''animation frames''.<br>
 +
</td><td>
 +
object name : TString          // Also the name of the bone.
 +
// Note: Because of this fact that this string uses '''28 bytes''' by default.
 +
frames      : INT32            // Number of frames
 +
unknown    : INT32            // Usually 0
 +
next        : INT32            // Next sibling
 +
prev        : INT32            // Previous sibling
 +
frame data  : KFRM
 +
</td><td>
 +
<tr><td>
 +
;KFRM: 'Abstract' section inherting from '''BASE''' and representing a frame type.<br>''There are 3 known specialisations of this base structure: '''KR00''', '''KRT0''' and '''KRTS'''.''
 +
</td><td>
 +
time key    : FLOAT            // This value is the last one of the specialised sections.
 +
</td><td>
 +
<tr><td>
 +
;KR00: Inherting from '''KFRM''' and defines an collection of rotated frames.<br>''(Offset - 4) / 16 = X''
 +
</td><td>
 +
rot        : TVector4[X]      // Rotation as [[Wikipedia:Quaternion|quaternion]]
 +
</td><td>
 +
<tr><td>
 +
;KRT0: Inherting from '''KFRM''' and defines an collection of rotated and translated frames.<br>''(Offset - 4) / 28 = X''
 +
</td><td>
 +
{
 +
  rot      : TVector4          // Rotation as quaternion
 +
  pos      : TVector3          // Translation
 +
}[X]                            // Repeated X times.
 +
</td><td>
 +
<tr><td>
 +
;KRTS: Inherting from '''KFRM''' and defines an collection of rotated, translated and scaled frames.<br>''(Offset - 4) / 40 = X''
 +
</td><td>
 +
{
 +
  rot      : TVector4          // Rotation as quaternion
 +
  pos      : TVector3          // Translation
 +
  scale    : TVector3          // Scale
 +
}[X]                            // Repeated X times.
 +
</td><td>
 +
</table>
  
R - Rotation
+
''Note: The sections are listed in the order they appear inside the file for better understanding.''
T - Translation
 
S - Scale
 
0 - None
 
  
Translation is a vector which points to an offset in the world. For [[Cutscene|cutscenes]] it is relative to an offset given in a special file. Usually just the root object contains translated frames.
+
==== Animation ====
  
====Frame Data====
+
The data structures descriped above can be used to define the data structure for animations. Note that TAnimation does ''not'' inherit from '''BASE'''. Offset information are stored inside the encapsuled animation data.
  
Each type has a different structure. They can be combined and are read by the game in the order they are written in the type value.
+
<table width="100%" border="0" cellspacing="8">
 +
<tr><th>Structure and description</th><th>Specification</th></tr>
 +
<tr><td>
 +
;TAnimation: An animation entry of the package.<br>''(8 byte)''
 +
</td><td>
 +
anim. name  : NAME
 +
anim. data  : DGAN
 +
</td><td>
 +
</table>
  
// Rotation
+
==== Exact version 1 hierarchy ====
4b  - Float    - Quarternion X
 
4b  - Float    - Quarternion Y
 
4b  - Float    - Quarternion Z
 
4b  - Float    - Quarternion W
 
  
// Translation
+
The following tree shows an basic hierarchy of an version 1 animation file:
4b  - Float    - Position X
 
4b  - Float    - Position Y
 
4b  - Float    - Position Z
 
  
  // Scale
+
  ANPK
4b  - Float   - Scale X
+
|
4b  - Float   - Scale Y
+
+-- INFO<TAnimation>
4b  - Float    - Scale Z
+
      |
 +
      +-- NAME/DGAN
 +
      |        |
 +
      |        +-- INFO<CPAN>
 +
      |        |    |
 +
      |        |   +-- ANIM
 +
      |        |    +-- ANIM
 +
      |        |   +-- ...
 +
      |        |
 +
      |        +-- ...
 +
      |
 +
      +-- ...
  
Every frame got one last floating value at the end describing the time in seconds.
+
<!---The model can be simplified to fit the version 2 animation packages. This is descriped [[IFP#Abstract_model_of_version_1_animation_packages|below]].--->
  
4b  - Float    - Time
+
<!---==== Abstract model of version 1 animation packages ====
 +
// After finishing the section for version 2 move this into it!
 +
Anyway you can simplify the version 1 model to fit the classes of version 2.--->
  
 
===Version 2===
 
===Version 2===
Version 2 archives got basically the same hierarchy as above, but the structures are a bit different. In version 2 all strings are Null-terminated, but they got a constant size of 24 bytes.
+
Version 2 archives got basically the same hierarchy as above, but the structures are a bit different. In version 2 all strings are null-terminated, but they got a constant size of 24 bytes.
  
 
====Header====
 
====Header====
Line 102: Line 197:
  
 
====Frame====
 
====Frame====
Root frames always follow the following structure:
+
Root frames usually follow the following structure:
  
  2b  - Int16    - Quaterion X
+
  2b  - Int16    - Quaternion X
  2b  - Int16    - Quaterion Y
+
  2b  - Int16    - Quaternion Y
  2b  - Int16    - Quaterion Z
+
  2b  - Int16    - Quaternion Z
  2b  - Int16    - Quaterion W
+
  2b  - Int16    - Quaternion W
 
  2b  - Int16    - Time (in seconds)
 
  2b  - Int16    - Time (in seconds)
 
  2b  - Int16    - Translation X
 
  2b  - Int16    - Translation X
Line 113: Line 208:
 
  2b  - Int16    - Translation Z
 
  2b  - Int16    - Translation Z
  
Child sections have no translation values.
+
Child sections normally have no translation values:
  
  2b  - Int16    - Quaterion X
+
  2b  - Int16    - Quaternion X
  2b  - Int16    - Quaterion Y
+
  2b  - Int16    - Quaternion Y
  2b  - Int16    - Quaterion Z
+
  2b  - Int16    - Quaternion Z
  2b  - Int16    - Quaterion W
+
  2b  - Int16    - Quaternion W
 
  2b  - Int16    - Time (in seconds)
 
  2b  - Int16    - Time (in seconds)
  
To convert quaternion and translation values to floating values divide them by 4096.
+
To convert quaternion and translation values to floating values divide them by 4096 and 1024, respectively.
 +
 
 +
==External links==
 +
* {{GTAF|400901|Creating Custom IFP's}} &ndash; by {{U|goin-god}}
 +
* [http://public.sannybuilder.com/anim/ List of San Andreas' Animations] &ndash; {{U|Seemann|Seemann's}} website
 +
* [http://www.pawfectmedia.com/mods/vc_anim_list.txt List of Vice City's Animations] &ndash; {{U|Ceedj|Ceedj's}} website archived at archive.org
  
==External Link==
+
{{N|SA|VC|3}}
*[http://public.sannybuilder.com/anim/ List of San Andreas' Animations] Seemann's website
+
[[Category:File Formats]][[Category:Pedestrian_Formats]]
*[http://www.pawfectfilms.com/mods/VCSA_AnimList.zip List of Vice CIty's and San Andreas' Animations] Ceedj's website
 

Latest revision as of 19:05, 11 September 2020

IFP is the animation format of the Grand Theft Auto series since GTA III. With GTA San Andreas there came a new version of the file format but it still supports animations of the old version. IFP files can contain several single animations which are split up to objects and linked to the animated object or actor in that way. Each object contains a certain number of frames including a time key. Two frames are interpolated by the game.

File Specification

Animation packages are building a simple hierarchy which is constant over all versions. Basicly each animation file consists of an header storing general file information. This header is followed by the animations themselves. In this way one animation file stores animations just like archive files holds different data as a flat list.

Each animation consists of multiple objects representing a bone of the model the animation gets linked to. Each object holds a list of frames. Those define information about the mathmatical description of the object in the world like translation, scaling and rotation.

The following structure shows an abstract animation tree:

IFP File
 |
 +-- Animation
 |    |
 |    +-- Object
 |    |    |
 |    |    +-- Frame
 |    |    +-- Frame
 |    |    +-- ...
 |    |
 |    +-- Object
 |    |    |
 |    |    +-- Frame
 |    |    +-- Frame
 |    |    +-- ...
 |    |
 |    +-- ...
 |
 +-- Animation
 |    |
 |    +-- ...
 |
 +-- ...

This tree is just an indirect result of the simple structure hierarchy of version 1 but parsers may use it for both versions.

Data types

By default animation packages are using the following data types:

  • CHAR - ASCII encrypted character (1 byte)
  • INT32/UINT32 - signed/unsigned 32 bit integer (4 byte)
  • FLOAT - single precision floating point number (4 byte)
  • TVector3 - FLOAT[3] (12 byte)
  • TVector4 - FLOAT[4] (16 byte)

Version 1

Strings

Even though strings are null terminated they are aligned to a 4 byte padding what means that their length (including the terminating zero byte) must be a multiple of 4. The trailing bytes are usually zero, too. The following part of the article uses TString for identifying string types. All those strings are following the rule descriped in here.

Data structures

Version 1 packages are introducing some additional data structures. Those are always indicated by an 4 byte constant length string. The following table lists the different data structures and their formats. All data structures are inherting from an abstract base data structure. This base data structure must not be used inside the file (also this would not make sense since it does not hold any data except information about identifying itself). The whole file follows this rules so animation package itself can be seen as one section.

Structure and descriptionSpecification
BASE
Abstract base section.
(8 byte)
identifier  : CHAR[4]
offset      : UINT              // offset to the end of the section
// Note: Offsets are always relative to the current file position.
ANPK
Major section of the file.
information : INFO<TAnimation>  // section information data (see below)
INFO<T>
Collection of multiple sub sections of type T.
entries     : INT32             // (count of encapsuled sections)
name        : TString           // (name of the collection)
sections    : T[entries]        // Subsections
NAME
Holds an string.
name        : TString
DGAN
Holds data for TAnimation.
anim. info  : INFO<CPAN>
CPAN
Holds data for animation objects.
object info : ANIM
ANIM
Holds data for animation frames.
object name : TString           // Also the name of the bone.
// Note: Because of this fact that this string uses 28 bytes by default.
frames      : INT32             // Number of frames
unknown     : INT32             // Usually 0
next        : INT32             // Next sibling
prev        : INT32             // Previous sibling
frame data  : KFRM
KFRM
'Abstract' section inherting from BASE and representing a frame type.
There are 3 known specialisations of this base structure: KR00, KRT0 and KRTS.
time key    : FLOAT             // This value is the last one of the specialised sections.
KR00
Inherting from KFRM and defines an collection of rotated frames.
(Offset - 4) / 16 = X
rot         : TVector4[X]       // Rotation as quaternion
KRT0
Inherting from KFRM and defines an collection of rotated and translated frames.
(Offset - 4) / 28 = X
{
  rot       : TVector4          // Rotation as quaternion
  pos       : TVector3          // Translation
}[X]                            // Repeated X times.
KRTS
Inherting from KFRM and defines an collection of rotated, translated and scaled frames.
(Offset - 4) / 40 = X
{
  rot       : TVector4          // Rotation as quaternion
  pos       : TVector3          // Translation
  scale     : TVector3          // Scale
}[X]                            // Repeated X times.

Note: The sections are listed in the order they appear inside the file for better understanding.

Animation

The data structures descriped above can be used to define the data structure for animations. Note that TAnimation does not inherit from BASE. Offset information are stored inside the encapsuled animation data.

Structure and descriptionSpecification
TAnimation
An animation entry of the package.
(8 byte)
anim. name  : NAME
anim. data  : DGAN

Exact version 1 hierarchy

The following tree shows an basic hierarchy of an version 1 animation file:

ANPK
|
+-- INFO<TAnimation>
     |
     +-- NAME/DGAN
     |         |
     |         +-- INFO<CPAN>
     |         |    |
     |         |    +-- ANIM
     |         |    +-- ANIM
     |         |    +-- ...
     |         |
     |         +-- ...
     |
     +-- ...


Version 2

Version 2 archives got basically the same hierarchy as above, but the structures are a bit different. In version 2 all strings are null-terminated, but they got a constant size of 24 bytes.

Header

4b   - FourCC   - 'ANP3' (Animation Package 3, Version identifier. However there is no pack with ANP2)
4b   - Int32    - Offset to end of file
24b  - Char[24] - internal file name used in the script
4b   - Int32    - Number of Animations

Animation

24b  - Char[24] - Animation Name
4b   - Int32    - Number of Objects
4b   - Int32    - Size of frame data
4b   - Int32    - Unknown, always 1

The size of data value is a number of bytes which corresponds to the exact size of the frame's usable data, including the compressed coordinates and rotation info.

Object

24b  - Char[24] - Object Name
4b   - Int32    - Frame type: Child = 3, Root = 4
4b   - Int32    - Number of Frames
4b   - Int32    - Bone ID

Frame

Root frames usually follow the following structure:

2b   - Int16    - Quaternion X
2b   - Int16    - Quaternion Y
2b   - Int16    - Quaternion Z
2b   - Int16    - Quaternion W
2b   - Int16    - Time (in seconds)
2b   - Int16    - Translation X
2b   - Int16    - Translation Y
2b   - Int16    - Translation Z

Child sections normally have no translation values:

2b   - Int16    - Quaternion X
2b   - Int16    - Quaternion Y
2b   - Int16    - Quaternion Z
2b   - Int16    - Quaternion W
2b   - Int16    - Time (in seconds)

To convert quaternion and translation values to floating values divide them by 4096 and 1024, respectively.

External links