BTG file format: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
Line 326: Line 326:
=== Color List ===
=== Color List ===


TODO
The Color List object contains a list of color definitions to be referenced by other geometry primitives.
 
The properties of a Color List object are ignored.
 
Each element of a Color List object is a list of color definitions.
Each of the colors gets a unique index, starting with 0 for the first color found in the file and incrementing by 1 for each further color.
 
{| border="1"
|-
! Byte offset
! Type
! Description
|-
| align="right"| 0
| unsigned int
| number of bytes in this element
|-
| align="right"| 4
| color definitions
| color definition list
|}
 
Each color definition is a 4-tuple of single precision floating point values:
 
{| border="1"
|-
! Byte offset
! Type
! Description
|-
| align="right"| 0
| float
| red part
|-
| align="right"| 4
| float
| green part
|-
| align="right"| 8
| float
| blue part
|-
| align="right"| 12
| float
| alpha part
|}
 
The number of coordinates in an element is therefore the number of bytes in the element divided by 16.


=== Points ===
=== Points ===

Revision as of 18:02, 30 September 2008

Terrain in FlightGear is currently stored using the Binary Terrain Format, in *.btg or *.btg.gz files. These files contain geometry in the form of points, individual triangles, triangle strips and triangle fans.

The authoritative source for the format definition is the class SGBinObject, which is defined in simgear/io/sg_binobj.{hxx,cxx}.

General Structure

Each BTG-File contains a header followed by a variable number of objects. Each object is introduced by a header indicating the type of object, the number of associated properties and the number of elements contained in the object.

Coordinates

All coordinates in the file are geocentric/cartesian coordinates, with

  • the center of the earth being the origin,
  • the z-axis aligned with the earth axis pointing north,
  • the x-axis going through the Greenwich Meridian at its intersection with the equator, and
  • the y-axis going through the intersection of the meridian at 90 degrees east and the equator.

In order to allow more compact storage, all coordinates are stored as single precision floating point values relative to the center of a bounding sphere, except for the bounding sphere itself, which is stored in double precision format.

All measurements are in meters.

Endianness

The files are stored in Little Endian, i.e. the least-significant byte is stored first.

Header

Byte offset Type Description
0 unsigned short Version (currently 7)
2 unsigned short Magic Number 0x5347 ("SG")
4 unsigned int Creation Time (seconds since the epoch)
8 unsigned short Number of Toplevel Objects

In files before version 7, the number of toplevel objects was interpreted as a signed short, leading to a maximum number of 32767 objects in a single file.

Objects

Each object starts by an object header.

Byte offset Type Description
0 char Object Type (see below)
1 unsigned short Number of Object Properties
3 unsigned short Number of Object Element

The object type can be one of the following:

Code Object Type
0 Bounding Sphere
1 Vertex List
2 Normal List
3 Texture Coordinates List
4 Color List
9 Points
10 Individual Triangles
11 Triangle Strips
12 Triangle Fans

The object header is followed by a list of properties. The number of properties in this list is given by the Number of Object Properties field.

Byte offset Type Description
0 char Property Type (see below)
1 unsigned int Number of Bytes in Property Data
5 bytes Property Data

The property type can be one of the following (see the object type descriptions for more details):

Code Property Type
0 Material
1 Index Types

Similarily, each element starts with a single unsigned integer, giving the number of bytes the element's data occupies.

Bounding Sphere Object

The Bounding Sphere object gives the bounding sphere of the tile, defined by a center and a radius.

The properties of a Bounding Sphere are ignored.

The elements of the Bounding Sphere object are bounding spheres. Even though more than one bounding sphere may be stored in such an object, all except for the last one found in the file are ignored.

Byte offset Type Description
0 unsigned int number of bytes in this element
4 double x-part of the center
12 double y-part of the center
20 double z-part of the center
28 float radius of the bounding sphere

Note that the element may be longer than 32 bytes, but only the first 32 bytes are actually used.

Vertex List

The Vertex List object contains a list of vertices to be referenced by other geometry primitives.

The properties of a Vertex List object are ignored.

Each element of a Vertex List object is a list of vertices. Each of the vertices gets a unique index, starting with 0 for the first vertex found in the file and incrementing by 1 for each further vertex.

Byte offset Type Description
0 unsigned int number of bytes in this element
4 vertices vertex list

Each vertex is a triple of single precision floating point values:

Byte offset Type Description
0 float x-part of the vertex coordinates
4 float y-part of the vertex coordinates
8 float z-part of the vertex coordinates

The number of vertices in an element is therefore the number of bytes in the element divided by 12.

Normal List

The Normal List contains a list of normals to be referenced by other geometry primitives.

The properties of a Normal List object are ignored.

Each element of a Normal List object is a list of normals. Each of the normals gets a unique index, starting with 0 for the first normal found in the file and incrementing by 1 for each further normal.

Byte offset Type Description
0 unsigned int number of bytes in this element
4 normals normal list

Each normal is a triple of signed bytes, interpreted as fixed point values:

Byte offset Type Description
0 byte x-part of the normal coordinates
1 byte y-part of the normal coordinates
2 byte z-part of the normal coordinates

The individual parts are interpreted by dividing each of the parts by 127.5 and subtracting 1.0, leading to a linear mapping from the range of 0...255 to the range of -1.0...1.0.

Texture Coordinates List

The Texture Coordinates List object contains a list of texture coordinates to be referenced by other geometry primitives.

The properties of a Teture Coordinates List object are ignored.

Each element of a Texture Coordinates List object is a list of texture coordinates. Each of the coordinates gets a unique index, starting with 0 for the first coordinate found in the file and incrementing by 1 for each further coordinate.

Byte offset Type Description
0 unsigned int number of bytes in this element
4 texture coordinates texture coordinate list

Each texture coordinate is a pair of single precision floating point values:

Byte offset Type Description
0 float x-part of the texture coordinate
4 float y-part of the texture coordinate

The number of coordinates in an element is therefore the number of bytes in the element divided by 8.

Color List

The Color List object contains a list of color definitions to be referenced by other geometry primitives.

The properties of a Color List object are ignored.

Each element of a Color List object is a list of color definitions. Each of the colors gets a unique index, starting with 0 for the first color found in the file and incrementing by 1 for each further color.

Byte offset Type Description
0 unsigned int number of bytes in this element
4 color definitions color definition list

Each color definition is a 4-tuple of single precision floating point values:

Byte offset Type Description
0 float red part
4 float green part
8 float blue part
12 float alpha part

The number of coordinates in an element is therefore the number of bytes in the element divided by 16.

Points

TODO

Individual Triangles

TODO

Triangle Strips

TODO

Triangle Fans

TODO