SHP

SHP (TS) files are used on Tiberian Sun and Red Alert 2 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):

• Signature (always #00000000)
• Width
• Height
• NumberOfFrames
  

Frame Header

Each Frame comes with a relevant ammount 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[uint24] Unused
• 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"
  

Special flags

If bit 2 is set - use compression 3, otherwise use compression 1 Example: (b - binary)

0 = 000b 1 = 001b 2 = 010b 3 = 011b 4 = 100b

Frame Data

If the frame compression is 1, Frame data is composed of a (FrameHeader.Width * FrameHeader.Height) bytes, each byte being a colour of the palette. For Compression 3, you have to decompress it.

The compression 3 is quite easy to be understood. The colour #0 repeats many times in a SHP file, since it's the background (transparent) colour. Therefore for any instance of the colour #0, the next byte will be the ammount of times (until 255) that #0 repeats. Another thing that must be considered on the compression 3 is that the first 2 bytes of a line are not colours. They indicate the size (in bytes) of the line.

The compression 2 works similarly to compression 3, but there is no special treatment for colour #0.

Pratical Aplication

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.