PSX/TIM format

Introduction

A TIM file is a standard image file format for the Sony PlayStation. The file structure closely mimics the way textures are managed in the frame buffer by the GPU. TIM files are little endian-based.

File layout

A TIM file is made up of three conceptual blocks; the header, the color lookup table (CLUT) and the image data. The CLUT block and the image data block have the same basic layout and are also treated the same way when loading a TIM file into the PlayStation frame buffer. Also, the CLUT block is optional and technically does not need to be present, even when the image data consists of color indices. Such image data is assumed to refer to some color lookup table, but not necessarily one stored in the same TIM file. In almost all cases though, the CLUT is included in the same TIM file as the image data using it and can thus be assumed to be applicable.

Header

The header starts with a 'tag' byte; this value is constant for all TIM files and must be 0x10. The immediately following byte denotes the version of the file format. At present, only version '0' TIM files are known to exist.

The next 32-bit word contains specific flags denoting the basic properties of the TIM file. The BPP (Bits Per Pixel) value denotes the bit depth of the image data, according to the following values:

00  4-bit (color indices)
01  8-bit (color indices)
10  16-bit (actual colors)
11  24-bit (actual colors)

The CLP (Color Lookup table Present) flag simply denotes if the CLUT block is present in the TIM file. This flag is typically set when BPP is 00 or 01, and cleared otherwise.

CLUT (color lookup table)

The CLUT starts with a simple 32-bit word telling the length, in bytes, of the entire CLUT block (including the header). Following that is a set of four 16-bit values telling how the CLUT data should be loaded into the frame buffer. These measurements are in frame buffer pixels, which are 16-bit. Each CLUT is stored in a rectangular portion of the frame buffer, which is typically 16 or 256 pixels wide (corresponding to 4-bit or 8-bit color indices). The rows define one or more 'palettes' which can be selected at runtime to use when drawing a color-indexed image.

In the frame buffer, CLUTs need to be stored on even multiples of 16 horizontally, but can be stored freely on any row. Typically they are stored directly under the front/back buffers.