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[uint32] Special flags. It can be any number
• 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

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 byte indicating which index of the PAL file the colour is, then a byte indicating how many pixels of this colour are to be written. This format of 1 pixel for colour, 1 pixel for count continues until the next pixel row is reached (when you reach the number of bytes for this line).
This format then repeats for each line in Frame_Header.Height.

Second method:
The second method is identical to the first method, except only colour 0 (transparent colour) is followed by the count of pixels. Therefore for any instance of the colour #0, the next byte will be the ammount of pixels (until 255) to write.

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.