SHP

SHP (TS) files are used on Tiberian Sun, FireStorm, Red Alert 2 and Yuri's Revenge to make buildings, infantry, animations, cameos (sidebar icons), among many other things. They consists on images with several frames using 256 colours from an external palette. Several programs are able to create and edit them like OS SHP Builder, Will's SHP Editor, XCC Mixer, etc. Several modders use XCC Mixer to convert images made with 3rd party programs into this format, while others edit them straight with OS SHP Builder.

Below, I'll explain the file format and how does it work, so future programmers may also be able to play with these files:

SHP (TS) File Format

The internal format

Things work in a very simple way. We have one main header, follow by header from each frame and then, the data from each frame. Here's a how it works:

• File Header
• Frame 1 Header
• Frame 2 Header
• ...
• Frame N Header
• Frame 1 Data
• Frame 2 Data
• ...
• Frame N Data
  

File Header

The File Header is very simple and consists only of few variables (unsigned 2 bytes integers):

• Reserved word (must be zero)
• Width
• Height
• NumberOfFrames
  

Frame Header

Each Frame comes with a relevant amount of data that will help to render it.

• X[uint16] (Horizontal position of the 0,0)
• Y[uint16] (Vertical position of the 0,0)
• Width[uint16] (Width of the frame. Note that X + Width < FileHeader.Width)
• Height[uint16] (Height of the frame. Note that Y + Height < FileHeader.Height)
• Flags[uint8] Special flags. It can be any number
• Align[3] 3 bytes align to dword
• Color[uint32] Some color (Can be Transparent color)
• Reserved2[uint32] (A bunch of zero. Unused by Westwood. That's a kind of space you can use to add... things like password for it).
• Offset[uint32] (Location, inside the file, of the frame data. Use this value with Seek to reach the frame data. If offset equal 0 it is NULL "frame"
  

Frame Data

The frame data is stored in one of two types, determined by the "flags" byte in the frame header. If the flag data have second bit clear, the frame data is stored as (FrameHeader.Height * FrameHeader.Width) bytes, each byte being an index of the palette

If the flag data second bit is set the data is stored using RLE compression. See below for more details.

Compression

If FrameHeader.Flag have second bit set, compression is used.

if (info->flag & 0x2)
{
  // with compression code
}
else
{
  // without compression code
}

First method:
The first two bytes of the frame data indicate how many bytes are in the line (that is, how many bytes of the frame data represent a whole row of pixels). This count includes the two bytes that say how many bytes in the line (for example if the value was 8, there would be 6 bytes of pixel information until the next line).
After this, there is a series of bytes indicating which index of the PAL file the colour is. In any case where the colour is 0x00, then the following byte indicates how many pixels of colour 0x00 (transparent) are to be written. For example, a line might read:

   07 00 00 09 53 00 9C

This would be 9 pixels of transparent colour, colour 0x53 in the pallette, and then another 0x9C pixels of transparent. This format repeats until all the lines in the image have been accounted for.

Second method:
The second method is used when the flag data of the frame is exactly 0x02. In this format (which I suppose isn't really compression), there are the two bytes to indicate how many bytes in the line, then a byte for each colour of the pixels in that line. This format repeats until all the lines in the image have been accounted for.

Practical Application

Both XCC Mixer and OS SHP Builder are open source programs that are able to load and save SHP files. XCC Mixer's source code is available at the CVS from XCCU project at SourceForge. It was written using C++ language. OS SHP Builder's source code, written in Delphi, is available with the program downloadable at Project Perfect Mod.

• XCC Mixer: http://cvs.sourceforge.net/viewcvs.py/xccu
• OS SHP Builder: http://www.ppmsite.com
  
• SHP Shell Extension for WIN32 will allow your windows explorer to display SHP files

Note: This tutorial was written by Banshee. Feel free to mirror it in your site, as long as you credit me.