2.1. Basics of the File Format
2.2. Supported Record Types

This section explains how to create graphic information files, also called GF files.

1. About GF Files

You can provide "graphic information" to TomTom Navigator in the form of a file consisting of variable-length records describing graphic shapes and elements (e.g. representing dynamic situations such as traffic conditions).

TomTom Navigator will load and maintain such a file as soon as you pass it the path name of the file, using the routine UseGFFile. When this routine returns, TomTom Navigator will have discarded any previous files, and will have loaded the new file into memory. The caller is thus free to delete or change the file after having called this routine.

Calling UseGFFile with an empty name, or with the name of a non-existent or empty file, in effect "clears" any previously loaded data.

For any change in the situation (e.g. the traffic situation) either call EnableGFRecord with the unique id of some record you want enabled or disabled, or call UseGFFile with the name of a new or adjusted file (or with the empty string as filename, which effectively deletes all the current records).

On general principles, it is recommended that you "refresh" files relating to traffic information every 15 minutes even if there are no changes. On the other hand, there are obvious disadvantages to refreshing files too often, e.g. every few seconds, in terms of power drain, application speed degradation etc.

For some applications, it may be useful to switch between a limited set of pre-defined, fixed files. For some applications, it may be useful to use a single pre-defined file, of which records are "enabled" or "disabled" by the simple action of stamping them with an "end-of-validity" in the past resp. the future.

2. GF File Format

2.1. Basics of the File Format

The following rules apply to all the records of a GF file.

• Multi-byte values are stored least-significant-byte first.
• Timestamps are specified as (4-byte) unsigned longs, representing seconds since midnight 1/1/1970.
• Coordinates are stored as (4-byte) signed longs, representing WGS84-coordinates in degrees multiplied by 100,000. The coordinates of a point are stored in the order: x, y.
• Strings (including filenames) are stored in ASCII format, are zero-terminated, and contain at most 254 non-zero characters.
• Rectangles must be "normalized", i.e. the four co-ordinates are in the following sequence: minimum-x, minimum-y, maximum-x, maximum-y.
• Every record must have the same 8-byte "header" and must be a multiple of 4 bytes in length.

The "header" must be as follows:

1 byte     Type of this record, which is a value between 0 and 127.
           When the most significant bit of this byte is set (>=128),
           it indicates that the record is disabled
3 bytes    Length of this record as a number of 4-byte words,
           Including the 8-byte header
4 bytes    Record ID (for future unique manipulation of this record)

2.2. Supported Record Types

8 BYTES    HEADER
4 bytes    End-of-validity timestamp
4 bytes    Number of bytes (EXcluding this record itself) that can be
           skipped immediately when end-of-validity is in the past
           (note: this value can be set to 0 if you're lazy)

NOTE: Records NOT preceded by an end-of-validity are "permanently valid." Even so, it is highly recommended that you consider the issue of validity periods, and always make sure that the very first record of the file specifies the end-of-validity for the whole file.

8 BYTES    HEADER
16 bytes   Normalized coordinate rectangle of the area
4 bytes    Number of bytes (EXcluding this record itself) that can be
           skipped if rectangle doesn't overlap the current screen

NOTE: It is highly recommended, in the interest of processing speed, that you always provide a skipper record that specifies the surrounding-rectangle for all the rectangle-dependent records in the whole file together.

8 BYTES	   HEADER
X bytes    Ignored content

NOTE: Uses of this type of record range from permanent deletion (rather than de-activation) of records to watermarking copyright information into your files. However, please be aware that these records still consume memory, and also cost a (very small) amount of time to ignore.

8 BYTES    HEADER
8 bytes    Start coordinates of the line
8 bytes    End coordinates of the line
4 bytes    Line type (0=default)
4 bytes    Red/Green/Blue color code of line

NOTE: The line type is the combination of a line thickness and a line pattern. The line thickness codes are:

• 0 - width of motorway 2
• 1 - width of motorway 1
• 2 - width of major road 4
• 3 - width of major road 2
• 4 - width of major road 1
• 5 - width of secondary road 4
• 6 - width of secondary road 2
• 7 - width of secondary road 1
• 8 - width of local road 4
• 9 - width of local road 3
• 10 - width of local road 2
• 11 - width of local road 1
• 12 - width of other road 4
• 13 - width of other road 3
• 14 - width of other road 2
• 15 - width of other road 1

The line pattern codes are:

• 0 - solid
• 16 - dashed
• 32 - dotted
• 48 - dot dash
• 64 - dot dot dash

The line thickness and line pattern codes can be combined using arithmetic addition or bit-wise OR.

8 BYTES	   HEADER
16 bytes   Normalized coordinate rectangle of the area around polyline
4 bytes    Line type (0=default)
4 bytes    Red/Green/Blue color code of lines
4 bytes    N = number of co-ordinates (should be 2 or more)
N*8 bytes  x/y-coordinates of the poly-line

NOTE: The line type field can contain the same codes as in the LINE (type 1) records.

8 BYTES    HEADER
16 bytes   Normalized rectangular area
4 bytes    Flags:
           0x0001 - if set, icon is ALWAYS shown. If not set,
           icon is only shown if the current GPS position
           is inside the specified rectangle
8 bytes    Reserved.
1 byte     Reserved. Must be 1.
1 byte     Reserved. Must be 1.
1 byte     L = length of the full filename of the icon to display
           (INcluding zero-termination)
1 byte     Reserved. Must be 1.
1 byte     Reserved. Must be 0.
1 byte     Reserved. Must be 0.
L bytes    Zero-terminated filename of a .BMP file (a 48x48,
           16-color or 256-color bitmap to be used as icon)
1 byte     Reserved. Must be 0.
? bytes    Zero-bytes, to make this record a multiple of 4 bytes long

NOTE: TomTom Navigator will never show more than 3 warning icons. No matter how many icons match the specified criteria, only the first three will be displayed and activated. Please note that each string needs to be less than 256 characters, and this INCLUDES the zero-terminator.