Why a Standard Texture Format?

There are many reasons why to provide a standard texture format for the FAT-Engine. The most important one is that this way textures can easily shared and distributed. Not everyone wants to develop textures (especially textures for sprites) by himself. Additionally tools like level editors can be crafted based on that format. Things should become much more easier this way.

Design Goal

Due to the fact that FAT textures will need much memory on the calc the main design goal for the file format is to use texture files directly from archive memory. The additionally necessary RAM amount should be kept as small as possible.
If you want to use compressed texture files you can easily compress standard texture files using the exepack tools from the TIGCC Tools. But compressed texture files need to be decompressed before using them and this makes only sense if you have not much of them.
An additionally design goal is that it should be possible to store generic data in texture files, too. This way any data necessary for a FAT client program can be "packed" into a single file.

Involved FAT-Structures

In general textures for the FAT-Engine are fixed to 64x64 pixels, but there many tricks to optimize the memory requirements like mirroring and similar.
The most basic texture unit of the FAT-Engine is a texture strip: a 16 columns wide and 64 pixel long texture block.

TEXSTRIP

typedef struct {
    unsigned short* lightdata;   // pointer to a 16 "columns" wide strip (light plane data)
                                 // 64 shorts == 128 bytes
    unsigned short* darkdata;    // pointer to a 16 "columns" wide strip (dark  plane data)
                                 // 64 shorts == 128 bytes
    unsigned short* maskdata;    // a possible mask for it or NULL (ignored for walls!!)
                                 // 64 shorts == 128 bytes
    short           mirrored;    // if ==STRIP_NORMAL this strip is rendered normal
                                 // if ==STRIP_MIRRORED this strip is rendered mirrored
                                 // if ==STRIP_IGNORE this strip will be ignored (not rendered)
}
TEXSTRIP;

Four of these TEXSTRIP structures forms a FAT-Texture (TEXCONFIG).

TEXCONFIG

typedef struct {
    TEXSTRIP strips[4]; // each 64x64 pixel texture consists of 4 texture strips
} TEXCONFIG;

Texture File Format

A Texture file is structured like this:

magic number	unsigned long	=0x46545830UL ('FTX0')
texconfig count	unsigned short	number of textures in this file (0 if none)
genericdata count	unsigned short	number of generic data blocks in this file (0 if none)
lightdata	unsigned long	lightdata offset of TEXCONFIG 1 STRIP 1 (if any!)
darkdata	unsigned long	darkdata offset of TEXCONFIG 1 STRIP 1
maskdata	unsigned long	maskdata offset of TEXCONFIG 1 STRIP 1
mirror	unsigned short	value for mirror field of TEXCONFIG 1 STRIP 1
lightdata	unsigned long	lightdata offset of TEXCONFIG 1 STRIP 2
darkdata	unsigned long	darkdata offset of TEXCONFIG 1 STRIP 2
maskdata	unsigned long	maskdata offset of TEXCONFIG 1 STRIP 2
mirror	unsigned short	value for mirror field of TEXCONFIG 1 STRIP 2
lightdata	unsigned long	lightdata offset of TEXCONFIG 1 STRIP 3
darkdata	unsigned long	darkdata offset of TEXCONFIG 1 STRIP 3
maskdata	unsigned long	maskdata offset of TEXCONFIG 1 STRIP 3
mirror	unsigned short	value for mirror field of TEXCONFIG 1 STRIP 3
lightdata	unsigned long	lightdata offset of TEXCONFIG 1 STRIP 4
darkdata	unsigned long	darkdata offset of TEXCONFIG 1 STRIP 4
maskdata	unsigned long	maskdata offset of TEXCONFIG 1 STRIP 4
mirror	unsigned short	value for mirror field of TEXCONFIG 1 STRIP 4
- more -	- more -	depending on texconfig count more TEXCONFIGs may follow here
offset	unsigned short	offset of GENERICDATA block 1 (if any!)
length	unsigned short	length of GENERICDATA block 1
- more -	- more -	depending on genericdata count more GENERICDATA definition may follow here

Right after the last TEXCONFIG follows the raw binary data of the textures. All offsets in the TEXCONFIG setups will point into this binary data block with one exeception:

If the content of an offset field is 0 (which isn't possible for a real offset in the file), then this corresponding pointer is set to NULL during the loading of the file. This makes sense for maskdata pointers, because masks are only used for sprites.

All offsets used in the TEXCONFIG setup blocks are offsets based on the first byte of the magic number. This way the loading routine has just to add the address of the beginning of the file to all pointers and the pointers will point right into the correct data.

Valid values for the mirror fields are: 0 (NORMAL), 1 (MIRROR) and 2 (IGNORE)

IMPORTANT NOTE 1: There is NO need that every offset points to its own data. Re-using offsets of single strips make much sense if two strips contain the same data or if the only difference between them is mirroring (just set the MIRROR field in the strip config). This way you can keep the length of the raw binary data small - a VERY good idea if you have many textures!

IMPORTANT NOTE 2: Make sure that all offsets used for TEXCONFIG setups are even numbers. Otherwise the engine will crash when it tries to use the textures. Program TexMaker (description below) garantees that these offsets are really even numbers. If you use TexMaker you have not take care on that for your own.

Integrated Support for the Standard Texture Format

Since v0.99 the FAT-Engine comes with integrated support for the standard texture format. The texture loading function takes a pointer to the start of a standard texture format block (the first byte of the magic number). This way it is completely independent. Either the data comes from a file or from somewhere else - it doesn't matter. For ease of use the FAT-Engine supplies file handling functions, too. In detail the following functions are related to the standard texture format:

• FAT_GetHandleOfFile()
• FAT_LockHandleOfFile()
• FAT_UnlockHandleOfFile()
• FAT_GetNumberOfTextures()
• FAT_LoadTextures()
• FAT_GetNumberOfGenericData()
• FAT_GetGenericData()
• FAT_GetGenericDataLength()

Check the FAT-API docs for details.

TexMaker - A Tool to generate Standard Texture Format Files

TexMaker is a tiny tool which comes with the FAT-SDK. It takes a text configuration file and converts it into a binary texture file (OTH file). Files for the TI-89 and TI-92p are generated in one step. On the calculator they show up with extension "ftex".

The configuration file format of TexMaker is pretty simple. Here is an example of a file which contains just one texture:

// this is a comment
# this is also a comment

TEXCONFIG [name_of_texconfig]
STRIP1 mylabel_1,     mylabel_2,     NULL, NORMAL
STRIP2 mylabel_1+128, mylabel_2+128, NULL, NORMAL
STRIP3 mylabel_1+256, mylabel_2+256, NULL, NORMAL
STRIP4 mylabel_1+384, mylabel_2+384, NULL, NORMAL

// NOTE how the length of the string is calculated automatically in the
// following GENERICDATA definition!

GENERICDATA  [name_of_genericdata]
text_start, text_end - textstart

GENERICDATA  [name_of_genericdata]
other_data, 1000

BINDATA

LABEL mylabel_1
0x12, 0x3456, 0xff88ff88, .... and so on (hex numbers)

LABEL mylabel_2
0b10001000, 0b1111111111111111, 0b10101010101010101010101010101010, .... and so on (binary numbers)

LABEL text_start
"This is an string embedded in the texturefile"
LABEL text_end

LABEL other_data
0b10001000, "hey you!", 0x12, ... and so on

Short Overview of TexMaker Features

• The configuration is splitted into two main parts: the TEXCONFIG setups (if any) at the beginning of the file followed by the GENERICDATA setups (if any) and at the "end" the raw binary data.
• Comment lines have to start with "//" or "#". Comments at the end of data lines are NOT allowed.
• empty lines are allowed
• keyword TEXCONFIG (on a line by itself only followed by an optional name) tells the tool that a TEXCONFIG setup will follow.
• STRIP1, STRIP2, STRIP3, STRIP4 - strip configuration lines. The STRIPn keyword is followed by the offset to the lightdata, darkdata, maskdata and the content of the mirror field. All fields after the keyword have to be separated by commas. Offsets can consists of any number of labels and decimal integers separated by '+' and '-' signs. For the mirror field content you can use keywords NORMAL, MIRROR or IGNORE. If keyword NULL is detected within an offset complete offset is treated as 0 value (results in a NULL pointer during loading). All offsets are byte offset. Note that all offsets used for a TEXSTRIP must be even offsets.
• It's not allowed to rearrange the lines of a TEXCONFIG setup block or the insert comment lines or empty lines within the TEXCONFIG setup block.
• keyword GENERICDATA (on a line by itself only followed by an optional name) tells the tool that a GENERICDATA definition will follow in the next line. A GENERICDATA definition consists of an offset into the binary data followed by a comma and the length in bytes of the data block.
• keyword BINDATA (on a line by itself) tells the tool that the raw binary data block starts below.
• keyword LABEL tells the tool that the next word is used as label in the TEXCONFIG setup and that the tool should remember the offset at this line.
• Binary data values have to be separated by commas. Spaces are ignored.
• NO size checking is done yet if the produced binary file will fit into a 64kB calculator file. But I think you will guess soon enough if you are beyond the "border" (the length of the BINDATA block itself GETs checked against 64kB, btw).

Yet binary data values in the BINDATA section can be of one of the following types:

0xhh	2-digit hexnumber (h = 0-f)
0xhhhh	4-digit hexnumber (h = 0-f)
0xhhhhhhhh	8-digit hexnumber (h = 0-f)
0bdddddddd	8-digit binary number (d = 0/1)
0bdddddddddddddddd	16-digit binary number (d = 0/1)
0bdddddddddddddddddddddddddddddddd	32-digit binary number (d = 0/1)
"string content within doublequotes"	standard string. The following escape sequences are handled:
	\t, \n, \\, \0, \" and \xhh (h = 0-f)

All of the above types can be mixed in on single line.

Due to the fact that TEXCONFIG setups requires even offsets, it is a good idea to put generic data blocks below the data of the textures.

Optional Names for TEXCONFIG and GENERICDATA setups

Since version 1.08 of TexMaker you can specify an optional name after the keywords TEXCONFIG and GENERICDATA. If you use commandline parameter -i followed by a headerfile name TexMaker will generate a headerfile which holds defines for all specified names. Suppose the configuration file contains 2 TEXCONFIG blocks named TEXIDX_MYTEXTURE1/TEXIDX_MYTEXTURE2 and 2 GENERICDATA blocks named GENIDX_MYDATA1 and GENIDX_MYDATA2. Then the generated headerfile will look like this:

#define TEXIDX_MYTEXTURE1       0
#define TEXIDX_MYTEXTURE2       1

#define GENIDX_MYDATA1          0
#define GENIDX_MYDATA2          1

In general such a headerfile makes the handling of indices easier for you by reducing the bookkeeping effort of the indices.

To examine a full-blown texmaker configuration file, please examine file src/examples/gfx/textures.txt. This file contains the configuration for all textures and other graphical data used by the FAT-SDK demos.

Copyleft

This release of the FAT-Engine-SDK may be distributed by any other website for non-commercial use only.

DISTRIBUTIONS of the FAT-Engine-SDK and the sourcecode of the FAT-Engine ON ANY OTHER MEDIUM (Disc,CD-ROM,DVD etc.) are PROHIBITED without separate allowance of the author.

The FAT-Engine-BINARIES (fatlib.89y/fatlib.9xy) can be DISTRIBUTED FREE in ANY FORM for non-commercial use only (i.e. as part of your own distribution of a client program).

The author makes no representations or warranties about the suitability of the software and/or the data files, either express or implied. The author shall not be liable for any damages suffered as a result of using or distributing this software and/or data files.

You are free to re-use any part of the sourcecode in your products as long as you give credits including a reference to the TICT-HQ (http://tict.ticalc.org/).

Contact TI-Chess Team Members

• You can reach Thomas Nussbaumer at thomas.nussbaumer@gmx.net
• Marcos Lopez can be reached at marcos.lopez@gmx.net
• Lionel Debroux can be reached at lionel_debroux@yahoo.fr

Bug reports and similar are VERY welcome. Please use our Messageboard at http://pub26.ezboard.com/btichessteamhq for this.

... and last but not least: The TI-Chess Team (TICT) Website can be found at: http://tict.ticalc.org