Compression Support

2023-01-03T00:42:23Z

ShivanSpS: /* Compression Function Example */

== '''Compression Support''' ==

The major problem in supporting compressed files is random access, FSO needs to be able to do all operations on a compressed file as it would normally do with any file; fopen(), fseek(), fread(), fclose(). Whiout having to decompress the entire file and store it in ram to do those operations. .pof parsing specially uses a lot of fseeks() and small freads(). Generally, file compression algos are intended to decompress the entire file from start to finish in one go and thus random access its non standart for the compression format.

In FSO 21.2.0 the first compression support was merged into the code, the first implementation uses LZ4/LZ4-HC and it is called internally as "LZ41". The LZ41 implementation is mainly intended for loose files but adding those inside VPs is also supported.

== LZ41 ==
The LZ41 design is similar to the lz4 random access example, it uses the lz4 stream compression, a int table to store the offsets that indicate at what compressed block the original file position is, a int to indicate the number of these offsets, the original filesize and blocksize. The major diference being that instead of using a dictionary, the stream is resetted at each block, making them independient from each other, and thus you can pick any block you want and uncompress that block at will.
Resetting the stream rather than use a dictionary may be less efficient (this is untested as the time of writting this article), but it was the only way to do it for individual files whiout having to embed the dictionary too.
The LZ41 implementation is non-LZ4 format standard, just like the official example for random access is, as the LZ4 data format does not seems to consider what is needed for random access.
FSO checks for the file header on fopen() and if the file is compressed then the logic for compressed files is used.

== LZ41 Data Format ==
4 byte header (0x31345A4C // "14ZL" -> "LZ41", inverted) 
N Blocks 
N offsets 
int num_offsets 
int original_filesize 
int blocksize 

[[File:lz41_structure.png|200px]]

== LZ41 Tests ==
'''Uncompressed MVP 4.4.1''' 
12.9GB - Space used on Disk 
 
'''Compressed MVP 4.4.1 Block Size: 65536 LZ4-HC L6''' 
7.01GB - Space used on disk 
Compression time: 5 minutes (1 thread) 
 
'''MVP 4.4.1 - All FS2 Models mission load time''' 
0:50 - NVME Uncompressed 
0:50 - NVME Compressed LZ4-HC L6, 7.01GB, BS: 65536 
1:01 - SSD Compressed LZ4-HC L6, 7.01GB, BS: 65536 
1:02 - SSD Uncompressed 
1:49 - HDD Compressed LZ4-HC L6, 7.01GB, BS: 65536 
2:30 - HDD Uncompressed 
 
== LZ41 Compressor Guidelines ==
'''Block Size''' 
Block size is set by the compressor 8192, 16384, 65536 block sizes were all tested, higher values are untested and may work or not, a higher block size will make the large compressed files smaller, higher block size will also make FSO to use more RAM but not by much. 
 
'''Ignore text based file formats''' 
Text files should be ignored, they do work fine, but there is no much is to be gained and the only thing it does is to make the file unreadeable by text editors: .fc2, .fs2, .tbl, .tbm, .eff. 
 
'''Movies are already compressed''' 
.mp4,.ogg,.mve,.webm: the ratio will be negative most of the time, and when is not, you are just saving a few kb, maybe a mb or two. 
 
'''Audio files''' 
.ogg, .wav: .wav may give you some little gains but it is just not worth to try, with ogg its the same problem as with the movies, these files are already compressed. 
 
'''pngs'''
pngs are already compressed and 99% of the time end up with a negative ratio, and since mods use apngs, you are going to waste time trying to compress them. PNG that arent compressed are going to go down in size, considerably, but this is uncommon, maybe check the png header for the compression value they already have before trying to compress. 
 
'''Do not keep files that end up with negative ratios'''
No matter if those files are inside a vp or they are loose files, if a compressed file end up being bigger than the original one, it must be discarded. 
 

== Compression Function Example==

[[Media:lz41_example.png]]
 
Source: VPC Compressor tool

== LZ41 Design Choices ==
A non standart format was used since the official random access example was already breaking the lz4 frame format. 
Additional data were added trailing to each file, the offset table, the num offsets, the block size, the original filesize, normaly those would be on a container and cached on container load, but it is not possible for loose files. 
Due to the 31 chars filename limit, the idea of adding a extra extension to the files was dropped, as changing the filename lenght was just not an option, and since loose files were getting no extra extension, a uncompressed .pof would be named the same as a compressed .pof, as a result of this, no need to store compressed files on a diferent container rather than plain .VP was seen as needed as there were already no difference for loose files. This will later been prove to be a mistake because it could cause user confunsion.

== Future Improvements ==
At some point in 23.X.X versions a new guideline for compressing files will be requiered. 
- The extra extension ".lz41" will be added to loose files. Since recent improvements in FSO code allows for loose files to use more than 31 characters. FSO will ignore this extra extension after load and thus "ship.pof.lz41" will be considered as "ship.pof". 
- New VP container: .VPC 
The VPC container format is identical to a .VP container in structure and limits, with one key difference: It may contain uncompressed files just like any normal VP, but it has to contain at least 1 compressed file.
Compressed files stored inside a .vpc container must not have the .lz41 extension or its name changed in any way. 
While .VP can still tecnically be used to store compressed files, it is recomended not to.
 
None of these changes break compatibility with files compressed prior to these changes, but just as with any new feature or major changes, older versions of FSO can not use compressed files in this new way.

== Versioning System ==
In order to avoid compatibility issues with future changes or additions, the file header is used in all fopen(), fseek(), fread() operations, the header tells FSO what to do in those operations, so in the future a new and better way to support compression is found, or a better algo, a different header must be used, lets assume "LZ42", this means FSO can handle "LZ41" files in a way and "LZ42" files in a totally different way whiout breaking any compatibility.

Compression Support

2023-01-03T00:36:27Z

ShivanSpS:

== '''Compression Support''' ==

The major problem in supporting compressed files is random access, FSO needs to be able to do all operations on a compressed file as it would normally do with any file; fopen(), fseek(), fread(), fclose(). Whiout having to decompress the entire file and store it in ram to do those operations. .pof parsing specially uses a lot of fseeks() and small freads(). Generally, file compression algos are intended to decompress the entire file from start to finish in one go and thus random access its non standart for the compression format.

In FSO 21.2.0 the first compression support was merged into the code, the first implementation uses LZ4/LZ4-HC and it is called internally as "LZ41". The LZ41 implementation is mainly intended for loose files but adding those inside VPs is also supported.

== LZ41 ==
The LZ41 design is similar to the lz4 random access example, it uses the lz4 stream compression, a int table to store the offsets that indicate at what compressed block the original file position is, a int to indicate the number of these offsets, the original filesize and blocksize. The major diference being that instead of using a dictionary, the stream is resetted at each block, making them independient from each other, and thus you can pick any block you want and uncompress that block at will.
Resetting the stream rather than use a dictionary may be less efficient (this is untested as the time of writting this article), but it was the only way to do it for individual files whiout having to embed the dictionary too.
The LZ41 implementation is non-LZ4 format standard, just like the official example for random access is, as the LZ4 data format does not seems to consider what is needed for random access.
FSO checks for the file header on fopen() and if the file is compressed then the logic for compressed files is used.

== LZ41 Data Format ==
4 byte header (0x31345A4C // "14ZL" -> "LZ41", inverted) 
N Blocks 
N offsets 
int num_offsets 
int original_filesize 
int blocksize 

[[File:lz41_structure.png|200px]]

== LZ41 Tests ==
'''Uncompressed MVP 4.4.1''' 
12.9GB - Space used on Disk 
 
'''Compressed MVP 4.4.1 Block Size: 65536 LZ4-HC L6''' 
7.01GB - Space used on disk 
Compression time: 5 minutes (1 thread) 
 
'''MVP 4.4.1 - All FS2 Models mission load time''' 
0:50 - NVME Uncompressed 
0:50 - NVME Compressed LZ4-HC L6, 7.01GB, BS: 65536 
1:01 - SSD Compressed LZ4-HC L6, 7.01GB, BS: 65536 
1:02 - SSD Uncompressed 
1:49 - HDD Compressed LZ4-HC L6, 7.01GB, BS: 65536 
2:30 - HDD Uncompressed 
 
== LZ41 Compressor Guidelines ==
'''Block Size''' 
Block size is set by the compressor 8192, 16384, 65536 block sizes were all tested, higher values are untested and may work or not, a higher block size will make the large compressed files smaller, higher block size will also make FSO to use more RAM but not by much. 
 
'''Ignore text based file formats''' 
Text files should be ignored, they do work fine, but there is no much is to be gained and the only thing it does is to make the file unreadeable by text editors: .fc2, .fs2, .tbl, .tbm, .eff. 
 
'''Movies are already compressed''' 
.mp4,.ogg,.mve,.webm: the ratio will be negative most of the time, and when is not, you are just saving a few kb, maybe a mb or two. 
 
'''Audio files''' 
.ogg, .wav: .wav may give you some little gains but it is just not worth to try, with ogg its the same problem as with the movies, these files are already compressed. 
 
'''pngs'''
pngs are already compressed and 99% of the time end up with a negative ratio, and since mods use apngs, you are going to waste time trying to compress them. PNG that arent compressed are going to go down in size, considerably, but this is uncommon, maybe check the png header for the compression value they already have before trying to compress. 
 
'''Do not keep files that end up with negative ratios'''
No matter if those files are inside a vp or they are loose files, if a compressed file end up being bigger than the original one, it must be discarded. 
 

== Compression Function Example==

[[Media:lz41_example.cpp]]
 
Source: VPC Compressor tool

== LZ41 Design Choices ==
A non standart format was used since the official random access example was already breaking the lz4 frame format. 
Additional data were added trailing to each file, the offset table, the num offsets, the block size, the original filesize, normaly those would be on a container and cached on container load, but it is not possible for loose files. 
Due to the 31 chars filename limit, the idea of adding a extra extension to the files was dropped, as changing the filename lenght was just not an option, and since loose files were getting no extra extension, a uncompressed .pof would be named the same as a compressed .pof, as a result of this, no need to store compressed files on a diferent container rather than plain .VP was seen as needed as there were already no difference for loose files. This will later been prove to be a mistake because it could cause user confunsion.

== Future Improvements ==
At some point in 23.X.X versions a new guideline for compressing files will be requiered. 
- The extra extension ".lz41" will be added to loose files. Since recent improvements in FSO code allows for loose files to use more than 31 characters. FSO will ignore this extra extension after load and thus "ship.pof.lz41" will be considered as "ship.pof". 
- New VP container: .VPC 
The VPC container format is identical to a .VP container in structure and limits, with one key difference: It may contain uncompressed files just like any normal VP, but it has to contain at least 1 compressed file.
Compressed files stored inside a .vpc container must not have the .lz41 extension or its name changed in any way. 
While .VP can still tecnically be used to store compressed files, it is recomended not to.
 
None of these changes break compatibility with files compressed prior to these changes, but just as with any new feature or major changes, older versions of FSO can not use compressed files in this new way.

== Versioning System ==
In order to avoid compatibility issues with future changes or additions, the file header is used in all fopen(), fseek(), fread() operations, the header tells FSO what to do in those operations, so in the future a new and better way to support compression is found, or a better algo, a different header must be used, lets assume "LZ42", this means FSO can handle "LZ41" files in a way and "LZ42" files in a totally different way whiout breaking any compatibility.

File:Lz41 structure.png

2023-01-02T23:52:49Z

ShivanSpS:

Compression Support

2023-01-02T23:52:29Z

ShivanSpS: Created page with "== '''Compression Support''' == The major problem in supporting compressed files is random access, FSO needs to be able to do all operations on a compressed file as it would..."

BSP data structure

POF data structure

2019-12-06T01:20:54Z

ShivanSpS: /* Chunk specs */

The following information is copied from the Descent Developer's Network [http://web.archive.org/web/20010619182804/descent-freespace.com/ddn/specs/pof/ pof specs page].

==Introduction==
These files are used to hold the ship model data. The data for the ship is basically a BSP tree that doesn't split polygons across the planes (since we're using zbuffering) and the planes are created by halving the largest dimension of each bounding box recursively. Due to the vastness of some of our models, this recursively split structure allows our collision detection and dynamic lighting to do quick out's on the model. For example, to check if a vector interects the model, I check against the bounding box. If it hits, I then check each of the two boxes it is split into. Then I recursively check each subdivided box as long as the vector is still interesecting.

We create the POF file by exporting a 3DS Max file with a special plugin tool to generate a ".P3D" file, which is essentially a 3d studio file only with texture uv's stored for each face vertex rather than for each vertex. We then run the .P3D file through an in-house Win32 program called 'BSPGEN' which creates the POF file. Depending on the model size, BSPGEN takes a few minutes or so.

Each ship is made up of a lot of subobjects where a subobject is a collection of polygons. For instance, each detail level of a hull of a ship is a subobject. A radar dish is a subobject. A piece of debris that the ship explodes into is a subobject. Each subobject can then have children subobjects. To draw the highest detail model of a ship, draw the subobject identified as detail level 0 and draw all it's children.

This document was written by John Slagel from Volition Inc., with revisions and bugfixing from Garry Knudson. FreeSpace 2 additions were made by Dave Baranec (Volition Inc.), Garry Knudson and Francis "Pastel" Avila.

[[POF_Order_FS2|POF block order list for retail FS2 models]]

==Data types==
This uses standard Intel data types.
<pre>
(int) == 4 bytes, signed
(uint) == 4 bytes, unsigned
(short) == 2 bytes, signed
(ushort) == 2 bytes, unsigned
(char) == 1 byte, signed
(ubyte) == 1 byte, unsigned
(float) == 4 bytes, signed
(vector) == 3 floats, 12 bytes total
(string) == an int specifying length of string and char[length] for the string itself
(note: it is NOT null-terminated)
</pre>

==Basic file structure==
The file format is a binary file using standard Intel data types. The header consists of a signature and the file version number:

<pre>
char[4] file_id // must be 'PSPO'
int version // Major*100+Minor
</pre>

Notes:

*PSPO stood for Parallax Software Polygon Object at one time. Conflict, Descent: FreeSpace shipped at POF version 20.14, so version would be equal to 2014 in most POF files (not all). FreeSpace 2 shipped at POF version 21.17, some files are 21.16.

*The rest of the file is a bunch of chunks. Each chunk is:

<pre>char[4] chunk_id // see below for available chunk types
int length // length of the chunk.
</pre>

Note: Contrary to BSP_Data structure, in pof data structure "Length" does not considers the first 8 bytes of the chunk (chunk id+length), so in order to go from the begining of the chunk to the next one you need to do lenght+8.
[[Media:Pof_chunk.png]]

==Chunk specs==
Here is a breakdown of each of the chunk types:

*'OHDR' (FreeSpace 1) and 'HDR2' (FreeSpace 2) - Object header info

<pre>
#ifdef version2116orhigher
// FreeSpace 2
float max_radius // maximum radius of entire ship
int obj_flags // object flags. Bit 1 = Textures contain tiling
int num_subobjects // number of subobjects
#else
// FreeSpace 1
int num_subobjects // number of subobjects
float max_radius // maximum radius of entire ship
int obj_flags // object flags. Bit 1 = Textures contain tiling
#endif

vector min_bounding // min bounding box point
vector max_bounding // max bounding box point

int num_detaillevels // number of detail levels
for each detail_level, i {
int sobj_detailevels[i] // subobject number for detail level I, 0 being highest.
}

int num_debris // number of debris pieces that model explodes into
for each debris piece, i
int sobj_debris[i] // subobject number for debris piece i

#ifdef version1903orhigher
float mass // see notes below
vector mass_center // center of mass
float[3][3] moment_inertia // moment of inertia
#endif

#ifdef version2014orhigher
int num_cross_sections // number of cross sections (used for exploding ship) (*)
for each cross_section, i {
float depth[i]
float radius[i]
}
#endif

#ifdef version2007orhigher
int num_lights // number of precalculated muzzle flash lights
for each light {
vector location
int light_type // type of light
}
#endif
</pre>

**Notes:

for version<2009, mass is a volume mass
for version>=2009, mass is an area mass
conversion: area_mass=4.65*(vol_mass^2/3); also scale moment_inertia by vol_mass/area_mass
(*) if there is no cross_section data, num_cross_sections is -1 instead of 0, as one would expect.

*'TXTR' - A list of textures used on this ship. The order they appear here is the number that a face uses to reference a particular texture.

<pre>
int num_textures
for each texture,i
int tex_filename_length[i]
string tex_filename[i] // texture filename
</pre>

*'PINF' - Miscellaneous info about the POF file, command line, etc.

Contains a block of NULL-terminated strings. Just read chunk size bytes and stuff it into a string.

*'PATH' - Paths for docking and AI ships to follow

<pre>
int num_paths
for each path, p {
string name[p] // name
string parent[p] // parent's name
int num_verts[p]
for each vert, v {
vector pos[p,v]
float radius[p,v]
int num_turrets[p,v]
for each turret, t {
int sobj_number[p,v,t] // subobject number
}
}
}
</pre>

*'SPCL' - Data for special points

<pre>
int num_special_points
for each special_point, p {
int name_length[p]
string name[p]
int properties_length[p]
string properties[p]
vector point[p]
float radius[p]
}
</pre>

*'SHLD' - Data for the shield mesh

<pre>
int num_vertices
for each vertex, v {
vector position[v]
}

int num faces
for each face, f {
vector face_normal[f]
int[3] face_vertices // indexed into vertex list
int[3] neighbors // indexed into face list
}
</pre>

*' EYE' - Data for eye points (Where pilot looks in 1st person views). Note the space in front of EYE.

<pre>
int num_eye_positions
for each eye_position, e {
int sobj_number[e] // subobject number this eye is attached to
vector sobj_offset[e] // offset from subobject
vector normal[e]
}
</pre>

*'GPNT' and 'MPNT' - Gun and Missile firing points

<pre>
int num_slots
for each slot, s {
int num_guns[s]
for each gun, g {
vector point[g,s]
vector norm[g,s]
}
}
</pre>

** Notes:

A "slot" is what you see in the loadout screen. Primaries have a max of 2 and secondaries of 3 for player-flyable ships.
"Guns" are the actual number of barrels and hence projectiles you'll get when you press the trigger. There is likely no practical max.

*'TGUN' and 'TMIS' - Turret Gun and Turret Missile firing points.

<pre>
int num_banks

for each bank, b {
int sobj_parent[b] // parent subobject (the subobject with which this turret is associated) (*)
int sobj_par_phys[b] // physical parent subobject (the subobject to which the turret rotates) (*)

vector turret_normal[b]
int num_firing_points[b]
for each firing_point {
vector position[b,f]
}
}
</pre>

** Notes:

For multipart turrets, sobj_parent is the "barrel" of a turret, and the firing points will be in this sobj's axial frame. sobj_par_phys is the "base" of a turret, which the barrel will rotate with.
For single-part turrets, sobj_parent == sobj_parent_phys.

*'DOCK' - Data for docking points

<pre>
int num_docks

for each dock, d {
string properties[d] // see notes below
int num_spline_paths[d]
for each spline_path, p {
int path_number[d,p]
}

int num_points
for each point, d {
vector position
vector normal
}
}
</pre>

** Note: Properties… if $name= found, then this is name. If name is cargo then this is a cargo bay.

*'FUEL' - Data for engine thruster glows

<pre>
int num_thrusters
for each thruster,t {
int num glows[t]

#ifdef version2117orhigher // FreeSpace 2 change
string properties
#endif

for each glow {
vector pos[t,g]
vector norm[t,g] // used to tell if behind glow
float radius[t,g]
}
}
</pre>

*'SOBJ' (FreeSpace 1) and 'OBJ2' (FreeSpace 2) - Data for a subobject. Contains some info and a bunch of vertices and polygons in the form of a BSP tree or Octree depending on how you look at it.

<pre>
int submodel_number // What submodel number this is.

#ifdef version2116orhigher
// FreeSpace 2
float radius // radius of this subobject
int submodel_parent // What submodel is this model's parent. Equal to -1 if none.
vector offset // Offset to from parent object <- Added 09/10/98
#else
// FreeSpace 1
int submodel_parent // What submodel is this model's parent. Equal to -1 if none.
vector offset // Offset to from parent object <- Added 09/10/98
float radius // radius of this subobject
#endif

vector geometric_center
vector bounding_box_min_point
vector bounding_box_max_point

string submodel_name
string properites
int movement_type
int movement_axis

int reserved // must be 0
int bsp_data_size // number of bytes now following
char[bsp_data_size] bsp_data // contains actual polygons, etc.
</pre>
** Note: bsp_data is explained [[bsp_data_structure|here]]

*'INSG' - Squad logo/Insignia data chunk (FreeSpace 2 only)

<pre>
int num_insignias
for each insignia, i {
int detail_level // ship detail level
int num_faces
int num_vertices
for each vertice, j {
vector vertex_position
}

vector offset // offset of the insignia in model coords
for each face, j {
for 0 to 2, k {
int vertex_index // vertex index for this face
float u_texture_coordinate
float v_texture_coordinate
}
}
}
</pre>

*'ACEN' - Auto-Centering info (FreeSpace 2 only)

<pre>
vector point // autocentering point for the entire model
</pre>

** The autocentering point was basically just a little convenient extra data we stuck in models where the pivot point of the model wasn't at the center. Since we rotate ships in the tech room by rotating around the pivot point, it looked dumb when the colossus' rear end was in the middle of the screen and it was spinning on it. So the autocenter point was just a point pretty much near the model we could use to push an extra matrix onto our transform stack and have it show up centered around it. The point itself is in model coordinates.

*'GLOW' - Glowpoint info (FS2_Open only)

<pre>
int num_glowbanks
for each glowbank, g {
int disp_time // displacement time for blinking (e.g. for Orion runway lights)
int on_time
int off_time
int obj_parent // parent subobject number
int LOD // Should be 0
int type // Should also be 0
int num_glowpoints // Number of glowpoints in this bank
string properties // Texture name, no file path or extension, like: "$glow_texture=..."
for each glowpoint, p {
vector point // location vector
vector norm // (0,0,0) is omnidirectional
float radius
}
}
</pre>

*'SLDC' - Shield mesh collision tree info (FS2_Open only)

<pre>
uint tree_size
for each node, n {
ubyte type // 0 = SPLIT, 1 = LEAF/polylist
uint size
if !type { // SPLIT
vector bound_min
vector bound_max
uint front_offset
uint back_offset
}
else { // LEAF
vector bound_min
vector bound_max
uint num_polygons
for each polygon, p {
uint polygon_addr // indexed into shield mesh face list?
}
}
}
</pre>

** The shield mesh collision tree speeds up collision calculation by adding bounding boxes around each polygon in the shield mesh. It works basically like a [[bsp_data_structure|BSP tree]].
** The first byte of each node is a size 1 char, this makes all the following data to be in unaligned memory access positions, thus making the SLDC system, as it is, incompatible with ARM arch.

[[Category:File Types]]

POF data structure

2019-12-06T01:14:32Z

ShivanSpS: /* Basic file structure */

The following information is copied from the Descent Developer's Network [http://web.archive.org/web/20010619182804/descent-freespace.com/ddn/specs/pof/ pof specs page].

==Introduction==
These files are used to hold the ship model data. The data for the ship is basically a BSP tree that doesn't split polygons across the planes (since we're using zbuffering) and the planes are created by halving the largest dimension of each bounding box recursively. Due to the vastness of some of our models, this recursively split structure allows our collision detection and dynamic lighting to do quick out's on the model. For example, to check if a vector interects the model, I check against the bounding box. If it hits, I then check each of the two boxes it is split into. Then I recursively check each subdivided box as long as the vector is still interesecting.

We create the POF file by exporting a 3DS Max file with a special plugin tool to generate a ".P3D" file, which is essentially a 3d studio file only with texture uv's stored for each face vertex rather than for each vertex. We then run the .P3D file through an in-house Win32 program called 'BSPGEN' which creates the POF file. Depending on the model size, BSPGEN takes a few minutes or so.

Each ship is made up of a lot of subobjects where a subobject is a collection of polygons. For instance, each detail level of a hull of a ship is a subobject. A radar dish is a subobject. A piece of debris that the ship explodes into is a subobject. Each subobject can then have children subobjects. To draw the highest detail model of a ship, draw the subobject identified as detail level 0 and draw all it's children.

This document was written by John Slagel from Volition Inc., with revisions and bugfixing from Garry Knudson. FreeSpace 2 additions were made by Dave Baranec (Volition Inc.), Garry Knudson and Francis "Pastel" Avila.

[[POF_Order_FS2|POF block order list for retail FS2 models]]

==Data types==
This uses standard Intel data types.
<pre>
(int) == 4 bytes, signed
(uint) == 4 bytes, unsigned
(short) == 2 bytes, signed
(ushort) == 2 bytes, unsigned
(char) == 1 byte, signed
(ubyte) == 1 byte, unsigned
(float) == 4 bytes, signed
(vector) == 3 floats, 12 bytes total
(string) == an int specifying length of string and char[length] for the string itself
(note: it is NOT null-terminated)
</pre>

==Basic file structure==
The file format is a binary file using standard Intel data types. The header consists of a signature and the file version number:

<pre>
char[4] file_id // must be 'PSPO'
int version // Major*100+Minor
</pre>

Notes:

*PSPO stood for Parallax Software Polygon Object at one time. Conflict, Descent: FreeSpace shipped at POF version 20.14, so version would be equal to 2014 in most POF files (not all). FreeSpace 2 shipped at POF version 21.17, some files are 21.16.

*The rest of the file is a bunch of chunks. Each chunk is:

<pre>char[4] chunk_id // see below for available chunk types
int length // length of the chunk.
</pre>

Note: Contrary to BSP_Data structure, in pof data structure "Length" does not considers the first 8 bytes of the chunk (chunk id+length), so in order to go from the begining of the chunk to the next one you need to do lenght+8.
[[Media:Pof_chunk.png]]

==Chunk specs==
Here is a breakdown of each of the chunk types:

*'OHDR' (FreeSpace 1) and 'HDR2' (FreeSpace 2) - Object header info

<pre>
#ifdef version2116orhigher
// FreeSpace 2
float max_radius // maximum radius of entire ship
int obj_flags // object flags. Bit 1 = Textures contain tiling
int num_subobjects // number of subobjects
#else
// FreeSpace 1
int num_subobjects // number of subobjects
float max_radius // maximum radius of entire ship
int obj_flags // object flags. Bit 1 = Textures contain tiling
#endif

vector min_bounding // min bounding box point
vector max_bounding // max bounding box point

int num_detaillevels // number of detail levels
for each detail_level, i {
int sobj_detailevels[i] // subobject number for detail level I, 0 being highest.
}

int num_debris // number of debris pieces that model explodes into
for each debris piece, i
int sobj_debris[i] // subobject number for debris piece i

#ifdef version1903orhigher
float mass // see notes below
vector mass_center // center of mass
float[3][3] moment_inertia // moment of inertia
#endif

#ifdef version2014orhigher
int num_cross_sections // number of cross sections (used for exploding ship) (*)
for each cross_section, i {
float depth[i]
float radius[i]
}
#endif

#ifdef version2007orhigher
int num_lights // number of precalculated muzzle flash lights
for each light {
vector location
int light_type // type of light
}
#endif
</pre>

**Notes:

for version<2009, mass is a volume mass
for version>=2009, mass is an area mass
conversion: area_mass=4.65*(vol_mass^2/3); also scale moment_inertia by vol_mass/area_mass
(*) if there is no cross_section data, num_cross_sections is -1 instead of 0, as one would expect.

*'TXTR' - A list of textures used on this ship. The order they appear here is the number that a face uses to reference a particular texture.

<pre>
int num_textures
for each texture,i
string tex_filename[i] // texture filename
</pre>

*'PINF' - Miscellaneous info about the POF file, command line, etc.

Contains a block of NULL-terminated strings. Just read chunk size bytes and stuff it into a string.

*'PATH' - Paths for docking and AI ships to follow

<pre>
int num_paths
for each path, p {
string name[p] // name
string parent[p] // parent's name
int num_verts[p]
for each vert, v {
vector pos[p,v]
float radius[p,v]
int num_turrets[p,v]
for each turret, t {
int sobj_number[p,v,t] // subobject number
}
}
}
</pre>

*'SPCL' - Data for special points

<pre>
int num_special_points
for each special_point, p {
string name[p]
string properties[p]
vector point[p]
float radius[p]
}
</pre>

*'SHLD' - Data for the shield mesh

<pre>
int num_vertices
for each vertex, v {
vector position[v]
}

int num faces
for each face, f {
vector face_normal[f]
int[3] face_vertices // indexed into vertex list
int[3] neighbors // indexed into face list
}
</pre>

*' EYE' - Data for eye points (Where pilot looks in 1st person views). Note the space in front of EYE.

<pre>
int num_eye_positions
for each eye_position, e {
int sobj_number[e] // subobject number this eye is attached to
vector sobj_offset[e] // offset from subobject
vector normal[e]
}
</pre>

*'GPNT' and 'MPNT' - Gun and Missile firing points

<pre>
int num_slots
for each slot, s {
int num_guns[s]
for each gun, g {
vector point[g,s]
vector norm[g,s]
}
}
</pre>

** Notes:

A "slot" is what you see in the loadout screen. Primaries have a max of 2 and secondaries of 3 for player-flyable ships.
"Guns" are the actual number of barrels and hence projectiles you'll get when you press the trigger. There is likely no practical max.

*'TGUN' and 'TMIS' - Turret Gun and Turret Missile firing points.

<pre>
int num_banks

for each bank, b {
int sobj_parent[b] // parent subobject (the subobject with which this turret is associated) (*)
int sobj_par_phys[b] // physical parent subobject (the subobject to which the turret rotates) (*)

vector turret_normal[b]
int num_firing_points[b]
for each firing_point {
vector position[b,f]
}
}
</pre>

** Notes:

For multipart turrets, sobj_parent is the "barrel" of a turret, and the firing points will be in this sobj's axial frame. sobj_par_phys is the "base" of a turret, which the barrel will rotate with.
For single-part turrets, sobj_parent == sobj_parent_phys.

*'DOCK' - Data for docking points

<pre>
int num_docks

for each dock, d {
string properties[d] // see notes below
int num_spline_paths[d]
for each spline_path, p {
int path_number[d,p]
}

int num_points
for each point, d {
vector position
vector normal
}
}
</pre>

** Note: Properties… if $name= found, then this is name. If name is cargo then this is a cargo bay.

*'FUEL' - Data for engine thruster glows

<pre>
int num_thrusters
for each thruster,t {
int num glows[t]

#ifdef version2117orhigher // FreeSpace 2 change
string properties
#endif

for each glow {
vector pos[t,g]
vector norm[t,g] // used to tell if behind glow
float radius[t,g]
}
}
</pre>

*'SOBJ' (FreeSpace 1) and 'OBJ2' (FreeSpace 2) - Data for a subobject. Contains some info and a bunch of vertices and polygons in the form of a BSP tree or Octree depending on how you look at it.

<pre>
int submodel_number // What submodel number this is.

#ifdef version2116orhigher
// FreeSpace 2
float radius // radius of this subobject
int submodel_parent // What submodel is this model's parent. Equal to -1 if none.
vector offset // Offset to from parent object <- Added 09/10/98
#else
// FreeSpace 1
int submodel_parent // What submodel is this model's parent. Equal to -1 if none.
vector offset // Offset to from parent object <- Added 09/10/98
float radius // radius of this subobject
#endif

vector geometric_center
vector bounding_box_min_point
vector bounding_box_max_point

string submodel_name
string properites
int movement_type
int movement_axis

int reserved // must be 0
int bsp_data_size // number of bytes now following
char[bsp_data_size] bsp_data // contains actual polygons, etc.
</pre>
** Note: bsp_data is explained [[bsp_data_structure|here]]

*'INSG' - Squad logo/Insignia data chunk (FreeSpace 2 only)

<pre>
int num_insignias
for each insignia, i {
int detail_level // ship detail level
int num_faces
int num_vertices
for each vertice, j {
vector vertex_position
}

vector offset // offset of the insignia in model coords
for each face, j {
for 0 to 2, k {
int vertex_index // vertex index for this face
float u_texture_coordinate
float v_texture_coordinate
}
}
}
</pre>

*'ACEN' - Auto-Centering info (FreeSpace 2 only)

<pre>
vector point // autocentering point for the entire model
</pre>

** The autocentering point was basically just a little convenient extra data we stuck in models where the pivot point of the model wasn't at the center. Since we rotate ships in the tech room by rotating around the pivot point, it looked dumb when the colossus' rear end was in the middle of the screen and it was spinning on it. So the autocenter point was just a point pretty much near the model we could use to push an extra matrix onto our transform stack and have it show up centered around it. The point itself is in model coordinates.

*'GLOW' - Glowpoint info (FS2_Open only)

<pre>
int num_glowbanks
for each glowbank, g {
int disp_time // displacement time for blinking (e.g. for Orion runway lights)
int on_time
int off_time
int obj_parent // parent subobject number
int LOD // Should be 0
int type // Should also be 0
int num_glowpoints // Number of glowpoints in this bank
string properties // Texture name, no file path or extension, like: "$glow_texture=..."
for each glowpoint, p {
vector point // location vector
vector norm // (0,0,0) is omnidirectional
float radius
}
}
</pre>

*'SLDC' - Shield mesh collision tree info (FS2_Open only)

<pre>
uint tree_size
for each node, n {
ubyte type // 0 = SPLIT, 1 = LEAF/polylist
uint size
if !type { // SPLIT
vector bound_min
vector bound_max
uint front_offset
uint back_offset
}
else { // LEAF
vector bound_min
vector bound_max
uint num_polygons
for each polygon, p {
uint polygon_addr // indexed into shield mesh face list?
}
}
}
</pre>

** The shield mesh collision tree speeds up collision calculation by adding bounding boxes around each polygon in the shield mesh. It works basically like a [[bsp_data_structure|BSP tree]].

[[Category:File Types]]

File:Pof chunk.png

2019-12-06T01:12:57Z

ShivanSpS:

POF data structure

2019-12-06T01:10:23Z

ShivanSpS: /* Basic file structure */

The following information is copied from the Descent Developer's Network [http://web.archive.org/web/20010619182804/descent-freespace.com/ddn/specs/pof/ pof specs page].

==Introduction==
These files are used to hold the ship model data. The data for the ship is basically a BSP tree that doesn't split polygons across the planes (since we're using zbuffering) and the planes are created by halving the largest dimension of each bounding box recursively. Due to the vastness of some of our models, this recursively split structure allows our collision detection and dynamic lighting to do quick out's on the model. For example, to check if a vector interects the model, I check against the bounding box. If it hits, I then check each of the two boxes it is split into. Then I recursively check each subdivided box as long as the vector is still interesecting.

We create the POF file by exporting a 3DS Max file with a special plugin tool to generate a ".P3D" file, which is essentially a 3d studio file only with texture uv's stored for each face vertex rather than for each vertex. We then run the .P3D file through an in-house Win32 program called 'BSPGEN' which creates the POF file. Depending on the model size, BSPGEN takes a few minutes or so.

Each ship is made up of a lot of subobjects where a subobject is a collection of polygons. For instance, each detail level of a hull of a ship is a subobject. A radar dish is a subobject. A piece of debris that the ship explodes into is a subobject. Each subobject can then have children subobjects. To draw the highest detail model of a ship, draw the subobject identified as detail level 0 and draw all it's children.

This document was written by John Slagel from Volition Inc., with revisions and bugfixing from Garry Knudson. FreeSpace 2 additions were made by Dave Baranec (Volition Inc.), Garry Knudson and Francis "Pastel" Avila.

[[POF_Order_FS2|POF block order list for retail FS2 models]]

==Data types==
This uses standard Intel data types.
<pre>
(int) == 4 bytes, signed
(uint) == 4 bytes, unsigned
(short) == 2 bytes, signed
(ushort) == 2 bytes, unsigned
(char) == 1 byte, signed
(ubyte) == 1 byte, unsigned
(float) == 4 bytes, signed
(vector) == 3 floats, 12 bytes total
(string) == an int specifying length of string and char[length] for the string itself
(note: it is NOT null-terminated)
</pre>

==Basic file structure==
The file format is a binary file using standard Intel data types. The header consists of a signature and the file version number:

<pre>
char[4] file_id // must be 'PSPO'
int version // Major*100+Minor
</pre>

Notes:

*PSPO stood for Parallax Software Polygon Object at one time. Conflict, Descent: FreeSpace shipped at POF version 20.14, so version would be equal to 2014 in most POF files (not all). FreeSpace 2 shipped at POF version 21.17, some files are 21.16.

*The rest of the file is a bunch of chunks. Each chunk is:

<pre>char[4] chunk_id // see below for available chunk types
int length // length of the chunk.
</pre>

Note: Contrary to BSP_Data structure, in pof data structure "Length" does not considers the first 8 bytes of the chunk (chunk id+length), so in order to go from the begining of the chunk to the next one you need to do lenght+8.
[[Media:pof_chunk]]

==Chunk specs==
Here is a breakdown of each of the chunk types:

*'OHDR' (FreeSpace 1) and 'HDR2' (FreeSpace 2) - Object header info

<pre>
#ifdef version2116orhigher
// FreeSpace 2
float max_radius // maximum radius of entire ship
int obj_flags // object flags. Bit 1 = Textures contain tiling
int num_subobjects // number of subobjects
#else
// FreeSpace 1
int num_subobjects // number of subobjects
float max_radius // maximum radius of entire ship
int obj_flags // object flags. Bit 1 = Textures contain tiling
#endif

vector min_bounding // min bounding box point
vector max_bounding // max bounding box point

int num_detaillevels // number of detail levels
for each detail_level, i {
int sobj_detailevels[i] // subobject number for detail level I, 0 being highest.
}

int num_debris // number of debris pieces that model explodes into
for each debris piece, i
int sobj_debris[i] // subobject number for debris piece i

#ifdef version1903orhigher
float mass // see notes below
vector mass_center // center of mass
float[3][3] moment_inertia // moment of inertia
#endif

#ifdef version2014orhigher
int num_cross_sections // number of cross sections (used for exploding ship) (*)
for each cross_section, i {
float depth[i]
float radius[i]
}
#endif

#ifdef version2007orhigher
int num_lights // number of precalculated muzzle flash lights
for each light {
vector location
int light_type // type of light
}
#endif
</pre>

**Notes:

for version<2009, mass is a volume mass
for version>=2009, mass is an area mass
conversion: area_mass=4.65*(vol_mass^2/3); also scale moment_inertia by vol_mass/area_mass
(*) if there is no cross_section data, num_cross_sections is -1 instead of 0, as one would expect.

*'TXTR' - A list of textures used on this ship. The order they appear here is the number that a face uses to reference a particular texture.

<pre>
int num_textures
for each texture,i
string tex_filename[i] // texture filename
</pre>

*'PINF' - Miscellaneous info about the POF file, command line, etc.

Contains a block of NULL-terminated strings. Just read chunk size bytes and stuff it into a string.

*'PATH' - Paths for docking and AI ships to follow

<pre>
int num_paths
for each path, p {
string name[p] // name
string parent[p] // parent's name
int num_verts[p]
for each vert, v {
vector pos[p,v]
float radius[p,v]
int num_turrets[p,v]
for each turret, t {
int sobj_number[p,v,t] // subobject number
}
}
}
</pre>

*'SPCL' - Data for special points

<pre>
int num_special_points
for each special_point, p {
string name[p]
string properties[p]
vector point[p]
float radius[p]
}
</pre>

*'SHLD' - Data for the shield mesh

<pre>
int num_vertices
for each vertex, v {
vector position[v]
}

int num faces
for each face, f {
vector face_normal[f]
int[3] face_vertices // indexed into vertex list
int[3] neighbors // indexed into face list
}
</pre>

*' EYE' - Data for eye points (Where pilot looks in 1st person views). Note the space in front of EYE.

<pre>
int num_eye_positions
for each eye_position, e {
int sobj_number[e] // subobject number this eye is attached to
vector sobj_offset[e] // offset from subobject
vector normal[e]
}
</pre>

*'GPNT' and 'MPNT' - Gun and Missile firing points

<pre>
int num_slots
for each slot, s {
int num_guns[s]
for each gun, g {
vector point[g,s]
vector norm[g,s]
}
}
</pre>

** Notes:

A "slot" is what you see in the loadout screen. Primaries have a max of 2 and secondaries of 3 for player-flyable ships.
"Guns" are the actual number of barrels and hence projectiles you'll get when you press the trigger. There is likely no practical max.

*'TGUN' and 'TMIS' - Turret Gun and Turret Missile firing points.

<pre>
int num_banks

for each bank, b {
int sobj_parent[b] // parent subobject (the subobject with which this turret is associated) (*)
int sobj_par_phys[b] // physical parent subobject (the subobject to which the turret rotates) (*)

vector turret_normal[b]
int num_firing_points[b]
for each firing_point {
vector position[b,f]
}
}
</pre>

** Notes:

For multipart turrets, sobj_parent is the "barrel" of a turret, and the firing points will be in this sobj's axial frame. sobj_par_phys is the "base" of a turret, which the barrel will rotate with.
For single-part turrets, sobj_parent == sobj_parent_phys.

*'DOCK' - Data for docking points

<pre>
int num_docks

for each dock, d {
string properties[d] // see notes below
int num_spline_paths[d]
for each spline_path, p {
int path_number[d,p]
}

int num_points
for each point, d {
vector position
vector normal
}
}
</pre>

** Note: Properties… if $name= found, then this is name. If name is cargo then this is a cargo bay.

*'FUEL' - Data for engine thruster glows

<pre>
int num_thrusters
for each thruster,t {
int num glows[t]

#ifdef version2117orhigher // FreeSpace 2 change
string properties
#endif

for each glow {
vector pos[t,g]
vector norm[t,g] // used to tell if behind glow
float radius[t,g]
}
}
</pre>

*'SOBJ' (FreeSpace 1) and 'OBJ2' (FreeSpace 2) - Data for a subobject. Contains some info and a bunch of vertices and polygons in the form of a BSP tree or Octree depending on how you look at it.

<pre>
int submodel_number // What submodel number this is.

#ifdef version2116orhigher
// FreeSpace 2
float radius // radius of this subobject
int submodel_parent // What submodel is this model's parent. Equal to -1 if none.
vector offset // Offset to from parent object <- Added 09/10/98
#else
// FreeSpace 1
int submodel_parent // What submodel is this model's parent. Equal to -1 if none.
vector offset // Offset to from parent object <- Added 09/10/98
float radius // radius of this subobject
#endif

vector geometric_center
vector bounding_box_min_point
vector bounding_box_max_point

string submodel_name
string properites
int movement_type
int movement_axis

int reserved // must be 0
int bsp_data_size // number of bytes now following
char[bsp_data_size] bsp_data // contains actual polygons, etc.
</pre>
** Note: bsp_data is explained [[bsp_data_structure|here]]

*'INSG' - Squad logo/Insignia data chunk (FreeSpace 2 only)

<pre>
int num_insignias
for each insignia, i {
int detail_level // ship detail level
int num_faces
int num_vertices
for each vertice, j {
vector vertex_position
}

vector offset // offset of the insignia in model coords
for each face, j {
for 0 to 2, k {
int vertex_index // vertex index for this face
float u_texture_coordinate
float v_texture_coordinate
}
}
}
</pre>

*'ACEN' - Auto-Centering info (FreeSpace 2 only)

<pre>
vector point // autocentering point for the entire model
</pre>

** The autocentering point was basically just a little convenient extra data we stuck in models where the pivot point of the model wasn't at the center. Since we rotate ships in the tech room by rotating around the pivot point, it looked dumb when the colossus' rear end was in the middle of the screen and it was spinning on it. So the autocenter point was just a point pretty much near the model we could use to push an extra matrix onto our transform stack and have it show up centered around it. The point itself is in model coordinates.

*'GLOW' - Glowpoint info (FS2_Open only)

<pre>
int num_glowbanks
for each glowbank, g {
int disp_time // displacement time for blinking (e.g. for Orion runway lights)
int on_time
int off_time
int obj_parent // parent subobject number
int LOD // Should be 0
int type // Should also be 0
int num_glowpoints // Number of glowpoints in this bank
string properties // Texture name, no file path or extension, like: "$glow_texture=..."
for each glowpoint, p {
vector point // location vector
vector norm // (0,0,0) is omnidirectional
float radius
}
}
</pre>

*'SLDC' - Shield mesh collision tree info (FS2_Open only)

<pre>
uint tree_size
for each node, n {
ubyte type // 0 = SPLIT, 1 = LEAF/polylist
uint size
if !type { // SPLIT
vector bound_min
vector bound_max
uint front_offset
uint back_offset
}
else { // LEAF
vector bound_min
vector bound_max
uint num_polygons
for each polygon, p {
uint polygon_addr // indexed into shield mesh face list?
}
}
}
</pre>

** The shield mesh collision tree speeds up collision calculation by adding bounding boxes around each polygon in the shield mesh. It works basically like a [[bsp_data_structure|BSP tree]].

[[Category:File Types]]

POF data structure

2019-12-06T01:09:37Z

ShivanSpS: /* Basic file structure */

The following information is copied from the Descent Developer's Network [http://web.archive.org/web/20010619182804/descent-freespace.com/ddn/specs/pof/ pof specs page].

==Introduction==
These files are used to hold the ship model data. The data for the ship is basically a BSP tree that doesn't split polygons across the planes (since we're using zbuffering) and the planes are created by halving the largest dimension of each bounding box recursively. Due to the vastness of some of our models, this recursively split structure allows our collision detection and dynamic lighting to do quick out's on the model. For example, to check if a vector interects the model, I check against the bounding box. If it hits, I then check each of the two boxes it is split into. Then I recursively check each subdivided box as long as the vector is still interesecting.

We create the POF file by exporting a 3DS Max file with a special plugin tool to generate a ".P3D" file, which is essentially a 3d studio file only with texture uv's stored for each face vertex rather than for each vertex. We then run the .P3D file through an in-house Win32 program called 'BSPGEN' which creates the POF file. Depending on the model size, BSPGEN takes a few minutes or so.

Each ship is made up of a lot of subobjects where a subobject is a collection of polygons. For instance, each detail level of a hull of a ship is a subobject. A radar dish is a subobject. A piece of debris that the ship explodes into is a subobject. Each subobject can then have children subobjects. To draw the highest detail model of a ship, draw the subobject identified as detail level 0 and draw all it's children.

This document was written by John Slagel from Volition Inc., with revisions and bugfixing from Garry Knudson. FreeSpace 2 additions were made by Dave Baranec (Volition Inc.), Garry Knudson and Francis "Pastel" Avila.

[[POF_Order_FS2|POF block order list for retail FS2 models]]

==Data types==
This uses standard Intel data types.
<pre>
(int) == 4 bytes, signed
(uint) == 4 bytes, unsigned
(short) == 2 bytes, signed
(ushort) == 2 bytes, unsigned
(char) == 1 byte, signed
(ubyte) == 1 byte, unsigned
(float) == 4 bytes, signed
(vector) == 3 floats, 12 bytes total
(string) == an int specifying length of string and char[length] for the string itself
(note: it is NOT null-terminated)
</pre>

==Basic file structure==
The file format is a binary file using standard Intel data types. The header consists of a signature and the file version number:

<pre>
char[4] file_id // must be 'PSPO'
int version // Major*100+Minor
</pre>

Notes:

*PSPO stood for Parallax Software Polygon Object at one time. Conflict, Descent: FreeSpace shipped at POF version 20.14, so version would be equal to 2014 in most POF files (not all). FreeSpace 2 shipped at POF version 21.17, some files are 21.16.

*The rest of the file is a bunch of chunks. Each chunk is:

<pre>char[4] chunk_id // see below for available chunk types
int length // length of the chunk.
</pre>

Note: Contrary to BSP_Data structure, in pof data structure "Length" does not considers the first 8 bytes of the chunk (chunk id+length), so in order to go from the begining of the chunk to the next one you need to do lenght+8.
[[Media:https://i.imgur.com/oa4GLYB.png]]

==Chunk specs==
Here is a breakdown of each of the chunk types:

*'OHDR' (FreeSpace 1) and 'HDR2' (FreeSpace 2) - Object header info

<pre>
#ifdef version2116orhigher
// FreeSpace 2
float max_radius // maximum radius of entire ship
int obj_flags // object flags. Bit 1 = Textures contain tiling
int num_subobjects // number of subobjects
#else
// FreeSpace 1
int num_subobjects // number of subobjects
float max_radius // maximum radius of entire ship
int obj_flags // object flags. Bit 1 = Textures contain tiling
#endif

vector min_bounding // min bounding box point
vector max_bounding // max bounding box point

int num_detaillevels // number of detail levels
for each detail_level, i {
int sobj_detailevels[i] // subobject number for detail level I, 0 being highest.
}

int num_debris // number of debris pieces that model explodes into
for each debris piece, i
int sobj_debris[i] // subobject number for debris piece i

#ifdef version1903orhigher
float mass // see notes below
vector mass_center // center of mass
float[3][3] moment_inertia // moment of inertia
#endif

#ifdef version2014orhigher
int num_cross_sections // number of cross sections (used for exploding ship) (*)
for each cross_section, i {
float depth[i]
float radius[i]
}
#endif

#ifdef version2007orhigher
int num_lights // number of precalculated muzzle flash lights
for each light {
vector location
int light_type // type of light
}
#endif
</pre>

**Notes:

for version<2009, mass is a volume mass
for version>=2009, mass is an area mass
conversion: area_mass=4.65*(vol_mass^2/3); also scale moment_inertia by vol_mass/area_mass
(*) if there is no cross_section data, num_cross_sections is -1 instead of 0, as one would expect.

*'TXTR' - A list of textures used on this ship. The order they appear here is the number that a face uses to reference a particular texture.

<pre>
int num_textures
for each texture,i
string tex_filename[i] // texture filename
</pre>

*'PINF' - Miscellaneous info about the POF file, command line, etc.

Contains a block of NULL-terminated strings. Just read chunk size bytes and stuff it into a string.

*'PATH' - Paths for docking and AI ships to follow

<pre>
int num_paths
for each path, p {
string name[p] // name
string parent[p] // parent's name
int num_verts[p]
for each vert, v {
vector pos[p,v]
float radius[p,v]
int num_turrets[p,v]
for each turret, t {
int sobj_number[p,v,t] // subobject number
}
}
}
</pre>

*'SPCL' - Data for special points

<pre>
int num_special_points
for each special_point, p {
string name[p]
string properties[p]
vector point[p]
float radius[p]
}
</pre>

*'SHLD' - Data for the shield mesh

<pre>
int num_vertices
for each vertex, v {
vector position[v]
}

int num faces
for each face, f {
vector face_normal[f]
int[3] face_vertices // indexed into vertex list
int[3] neighbors // indexed into face list
}
</pre>

*' EYE' - Data for eye points (Where pilot looks in 1st person views). Note the space in front of EYE.

<pre>
int num_eye_positions
for each eye_position, e {
int sobj_number[e] // subobject number this eye is attached to
vector sobj_offset[e] // offset from subobject
vector normal[e]
}
</pre>

*'GPNT' and 'MPNT' - Gun and Missile firing points

<pre>
int num_slots
for each slot, s {
int num_guns[s]
for each gun, g {
vector point[g,s]
vector norm[g,s]
}
}
</pre>

** Notes:

A "slot" is what you see in the loadout screen. Primaries have a max of 2 and secondaries of 3 for player-flyable ships.
"Guns" are the actual number of barrels and hence projectiles you'll get when you press the trigger. There is likely no practical max.

*'TGUN' and 'TMIS' - Turret Gun and Turret Missile firing points.

<pre>
int num_banks

for each bank, b {
int sobj_parent[b] // parent subobject (the subobject with which this turret is associated) (*)
int sobj_par_phys[b] // physical parent subobject (the subobject to which the turret rotates) (*)

vector turret_normal[b]
int num_firing_points[b]
for each firing_point {
vector position[b,f]
}
}
</pre>

** Notes:

For multipart turrets, sobj_parent is the "barrel" of a turret, and the firing points will be in this sobj's axial frame. sobj_par_phys is the "base" of a turret, which the barrel will rotate with.
For single-part turrets, sobj_parent == sobj_parent_phys.

*'DOCK' - Data for docking points

<pre>
int num_docks

for each dock, d {
string properties[d] // see notes below
int num_spline_paths[d]
for each spline_path, p {
int path_number[d,p]
}

int num_points
for each point, d {
vector position
vector normal
}
}
</pre>

** Note: Properties… if $name= found, then this is name. If name is cargo then this is a cargo bay.

*'FUEL' - Data for engine thruster glows

<pre>
int num_thrusters
for each thruster,t {
int num glows[t]

#ifdef version2117orhigher // FreeSpace 2 change
string properties
#endif

for each glow {
vector pos[t,g]
vector norm[t,g] // used to tell if behind glow
float radius[t,g]
}
}
</pre>

*'SOBJ' (FreeSpace 1) and 'OBJ2' (FreeSpace 2) - Data for a subobject. Contains some info and a bunch of vertices and polygons in the form of a BSP tree or Octree depending on how you look at it.

<pre>
int submodel_number // What submodel number this is.

#ifdef version2116orhigher
// FreeSpace 2
float radius // radius of this subobject
int submodel_parent // What submodel is this model's parent. Equal to -1 if none.
vector offset // Offset to from parent object <- Added 09/10/98
#else
// FreeSpace 1
int submodel_parent // What submodel is this model's parent. Equal to -1 if none.
vector offset // Offset to from parent object <- Added 09/10/98
float radius // radius of this subobject
#endif

vector geometric_center
vector bounding_box_min_point
vector bounding_box_max_point

string submodel_name
string properites
int movement_type
int movement_axis

int reserved // must be 0
int bsp_data_size // number of bytes now following
char[bsp_data_size] bsp_data // contains actual polygons, etc.
</pre>
** Note: bsp_data is explained [[bsp_data_structure|here]]

*'INSG' - Squad logo/Insignia data chunk (FreeSpace 2 only)

<pre>
int num_insignias
for each insignia, i {
int detail_level // ship detail level
int num_faces
int num_vertices
for each vertice, j {
vector vertex_position
}

vector offset // offset of the insignia in model coords
for each face, j {
for 0 to 2, k {
int vertex_index // vertex index for this face
float u_texture_coordinate
float v_texture_coordinate
}
}
}
</pre>

*'ACEN' - Auto-Centering info (FreeSpace 2 only)

<pre>
vector point // autocentering point for the entire model
</pre>

** The autocentering point was basically just a little convenient extra data we stuck in models where the pivot point of the model wasn't at the center. Since we rotate ships in the tech room by rotating around the pivot point, it looked dumb when the colossus' rear end was in the middle of the screen and it was spinning on it. So the autocenter point was just a point pretty much near the model we could use to push an extra matrix onto our transform stack and have it show up centered around it. The point itself is in model coordinates.

*'GLOW' - Glowpoint info (FS2_Open only)

<pre>
int num_glowbanks
for each glowbank, g {
int disp_time // displacement time for blinking (e.g. for Orion runway lights)
int on_time
int off_time
int obj_parent // parent subobject number
int LOD // Should be 0
int type // Should also be 0
int num_glowpoints // Number of glowpoints in this bank
string properties // Texture name, no file path or extension, like: "$glow_texture=..."
for each glowpoint, p {
vector point // location vector
vector norm // (0,0,0) is omnidirectional
float radius
}
}
</pre>

*'SLDC' - Shield mesh collision tree info (FS2_Open only)

<pre>
uint tree_size
for each node, n {
ubyte type // 0 = SPLIT, 1 = LEAF/polylist
uint size
if !type { // SPLIT
vector bound_min
vector bound_max
uint front_offset
uint back_offset
}
else { // LEAF
vector bound_min
vector bound_max
uint num_polygons
for each polygon, p {
uint polygon_addr // indexed into shield mesh face list?
}
}
}
</pre>

** The shield mesh collision tree speeds up collision calculation by adding bounding boxes around each polygon in the shield mesh. It works basically like a [[bsp_data_structure|BSP tree]].

[[Category:File Types]]