Humongous CUP: Difference between revisions

From MultimediaWiki
Jump to navigation Jump to search
(Link to decoder => !undiscovered)
 
(6 intermediate revisions by 4 users not shown)
Line 1: Line 1:
* Extension: cup
* Extension: cup
* Company: [[Humongous Entertainment]]
* Company: [[Humongous Entertainment]]
* Samples: http://www.mplayerhq.hu/MPlayer/samples/game-formats/cup/
* Samples: http://samples.mplayerhq.hu/game-formats/cup/
* Decoder: http://scummvm.svn.sourceforge.net/viewvc/scummvm/scummvm/trunk/engines/scumm/he/cup_player_he.cpp


Humongous CUP files are used as demo movies for games from Humongous Entertainment. CUP files have the file signature 'BEAN' and are played with an executable called coffee.exe. They appear to contain non-interleaved audio and video data; all of the audio data is stored in the file first and the video data second.
Humongous CUP files are used as demo movies for games from Humongous Entertainment. CUP files have the file signature 'BEAN' and are played with an executable called coffee.exe. They appear to contain non-interleaved audio and video data; all of the audio data is stored in the file first and the video data second.


== Data Format ==
== Data Format ==
Multi-byte numbers may be little or big endian
CUP file use both little and big endian numbers. Big endian numbers are used when encoding the chunk size in the chunk preamble. All other multi-byte numbers appear to be stored in little endian format.


   bytes 0-3    chunk type [[FourCC]]
   bytes 0-3    chunk type [[FourCC]]
   bytes 4-7    chunk size (including this 8-byte preamble); big endian
   bytes 4-7    chunk size (including this 8-byte preamble)
   bytes 8..    chunk payload
   bytes 8..    chunk payload


Line 15: Line 16:


   bytes 0-3    'BEAN' FourCC
   bytes 0-3    'BEAN' FourCC
   bytes 4-7    size of entire CUP file (including this preamble); big endian
   bytes 4-7    size of entire CUP file (including this preamble)
   bytes 8..    CUP file
   bytes 8..    CUP file


Line 21: Line 22:


   bytes 0-3    'HEAD' FourCC
   bytes 0-3    'HEAD' FourCC
   bytes 4-7    size = 0x0E = 14 bytes; big endian
   bytes 4-7    size = 0x0E = 14 bytes
   bytes 8-9    unknown, always seems to be 0x0042 (66) in little endian
   bytes 8-9    playback rate in ms (66 by default)
   bytes 10-11  video width
   bytes 10-11  video width
   bytes 12-13  video height
   bytes 12-13  video height
Line 29: Line 30:


   bytes 0-3    'RGBS' FourCC
   bytes 0-3    'RGBS' FourCC
   bytes 4-7    chunk size = 0x0308 = 776 bytes; big endian
   bytes 4-7    chunk size = 0x0308 = 776 bytes
   bytes 8..775  palette entries
   bytes 8..775  palette entries


Line 44: Line 45:


   bytes 0-3    'OFFS' FourCC
   bytes 0-3    'OFFS' FourCC
   bytes 4-7    chunk size; big endian
   bytes 4-7    chunk size
   bytes 8..    DATA chunk offsets; little endian
   bytes 8..    DATA chunk offsets


The DATA chunk offsets are 4-byte numbers stored in little endian format that fill the remainder of the OFFS chunk after the preamble. They indicate the offsets (and, implicitly, the count) of audio DATA chunks. The offsets are relative to the start of the OFFS chunk. It is instructive to note that since the first DATA chunk immediately follows the OFFS chunk, its offset will be the same as the size of the OFFS chunk, though stored in the opposite byte order. For example, if there were only one audio DATA chunk in the file, and the OFFS chunk began at 0x32E:
The DATA chunk offsets are 4-byte numbers stored in little endian format that fill the remainder of the OFFS chunk after the preamble. They indicate the offsets (and, implicitly, the count) of audio DATA chunks. The offsets are relative to the start of the OFFS chunk. It is instructive to note that since the first DATA chunk immediately follows the OFFS chunk, its offset will be the same as the size of the OFFS chunk, though stored in the opposite byte order. For example, if there were only one audio DATA chunk in the file, and the OFFS chunk began at 0x32E:
Line 60: Line 61:


   bytes 0-3    'HSHD' FourCC
   bytes 0-3    'HSHD' FourCC
   bytes 4-7    chunk size = 0x18 = 24 bytes; big endian
   bytes 4-7    chunk size = 0x18 = 24 bytes
   bytes 8-13  unknown
   bytes 8-13  unknown
   bytes 14-15  sample rate; little endian
   bytes 14-15  sample rate
   bytes 16-23  unknown
   bytes 16-23  unknown


Line 73: Line 74:
** SNDE
** SNDE
** TOIL
** TOIL
** FRAM
** SRLE
** SRLE
** WRLE
** LZSS
** LZSS
The RGBS chunk, already described, indicates that the palette can change during playback. The RATE chunk has the following layout:
The RGBS chunk, already described, indicates that the palette can change during playback. The RATE chunk has the following layout:


   bytes 0-3    'RATE'
   bytes 0-3    'RATE'
   bytes 4-7    chunk size = 0xA = 10 bytes; big endian
   bytes 4-7    chunk size = 0xA = 10 bytes
   bytes 8-9    unknown
   bytes 8-9    playback rate in milliseconds


It is possible that this defines a change in the playback rate.
This chunk allows to change the playback rate of the movie.


The SNDE chunk has the following format:
The SNDE chunk has the following format:


   bytes 0-3    'SNDE'
   bytes 0-3    'SNDE'
   bytes 4-7    chunk size = 0x12 = 18 bytes; big endian
   bytes 4-7    chunk size = 0x12 = 18 bytes
   bytes 8-17   unknown
   bytes 8-11  unknown
  bytes 12-13  unknown
  bytes 13-15  unknown
  bytes 15-17 unknown


While the purpose of this block is unknown, some of the numbers may reference back into the AUDIO data chunks to specify which piece of audio should be playing at the current time.
While the purpose of this block is unknown, some of the numbers may reference back into the AUDIO data chunks to specify which piece of audio should be playing at the current time.


The TOIL chunk has the following format:
The TOIL chunk allows to execute special operations, it has the following format:


   bytes 0-3    'TOIL'
   bytes 0-3    'TOIL'
   bytes 4-7    chunk size = 0x10 = 16 bytes; big endian
   bytes 4-7    chunk size (variable)
   bytes 8-15   unknown
   bytes 8-9    number of opcodes
   bytes 10-    opcodes data


SRLE and LZSS indicated video compression types and will be explained in their own sections.
Each TOIL opcode data has the following format :
  byte  0      size of opcode
  byte  1      opcode number


== Chunk Types ==
The purpose of each opcode is :
  1  stop playback
  2  display copyright/information messageBox
  3  unknown
  4  restart playback
  5  disable screen update
  6  enable offscreen buffers swapping
  7  pause playback at specific frame


BEAN: file signature
The SRLE, WRLE, FRAM and LZSS chunk types indicate video compression types and will be explained in their own sections.


HEAD: contains 10-byte payload including unknown 16-bit quantity and 32-bit width and height stored as little-endian
== TRLE Compression ==
TRLE (which presumably stands for "transparent run length encoding") is name of the bitmap compression algorithm used in a FRAM chunk.


RGBS: palette triplets; payload should be 0x300 (768, 256x3) bytes long; values range from 0..255; must be a constant length since it has no provision for palette replacement
== SRLE Compression ==
SRLE is the name of one of the video compression algorithms seen in CUP files. It is suspected to be a simple run length encoding scheme.


SFXB..WRAP..OFFS: apparently a setup for audio data
== LZSS (Tri-LZ) Compression ==
LZSS indicates one of the video compression algorithms seen in CUP files. It is a variant of the common [[LZ]] algorithm. An LZSS chunk has the following hierarchical organization:
* LZSS
** LZHD
** DATA
Thus, the LZSS chunk contains its preamble followed by an LZHD chunk and ''(another type of!)'' DATA chunk. The LZHD chunk has the following layout:


DATA: audio or video data; audio data is 8-bit, unsigned PCM
  bytes 0-3    'LZHD' FourCC
  bytes 4-7    size = 0x10 = 16 bytes
  bytes 8-11  compression type
  bytes 12-15  size of decompressed data


BLOK: video data block?
The only valid compression type is 0x2000 which indicates the tri-lz method. The DATA chunk contains the compressed data.
 
SRLE: apparently the video compression type, possibly based on lzss.c
 
SNDE: reference into audio data?
 
RATE:


A block of tri-lz compressed data is stored in 3 parts. In a compressed data block, part 1 starts at byte 8. Part 2 starts at the offset formed from bytes 0-3 of the compressed buffer. Part 3 starts at the offset formed from bytes 4-7 of the compressed buffer.


'''(TODO: finish description)'''


[[Category:Game Formats]]
[[Category:Game Formats]]
[[Category:Undiscovered Game Formats]]
[[Category:Video Codecs]]
[[Category:Formats missing in FFmpeg]]

Latest revision as of 22:28, 2 September 2009

Humongous CUP files are used as demo movies for games from Humongous Entertainment. CUP files have the file signature 'BEAN' and are played with an executable called coffee.exe. They appear to contain non-interleaved audio and video data; all of the audio data is stored in the file first and the video data second.

Data Format

CUP file use both little and big endian numbers. Big endian numbers are used when encoding the chunk size in the chunk preamble. All other multi-byte numbers appear to be stored in little endian format.

 bytes 0-3     chunk type FourCC
 bytes 4-7     chunk size (including this 8-byte preamble)
 bytes 8..     chunk payload

The top-level chunk in a CUP file is the BEAN chunk which encapsulates the entire file and can also serve as a file signature:

 bytes 0-3     'BEAN' FourCC
 bytes 4-7     size of entire CUP file (including this preamble)
 bytes 8..     CUP file

Following the BEAN signature is a HEAD chunk with the following format:

 bytes 0-3     'HEAD' FourCC
 bytes 4-7     size = 0x0E = 14 bytes
 bytes 8-9     playback rate in ms (66 by default)
 bytes 10-11   video width
 bytes 12-13   video height

An RGBS chunk often appears after the HEAD chunk in a CUP file. It has the following layout:

 bytes 0-3     'RGBS' FourCC
 bytes 4-7     chunk size = 0x0308 = 776 bytes
 bytes 8..775  palette entries

The palette entries are 256 3-byte triplets of red-green-blue palette components. Each component is 8 bits (as opposed to 6 bits which is often seen in palettized formats).

The RGBS chunk is generally followed by the SFXB chunk which contains audio data. This is the typical hierarchical organization of the SFXB chunk and its constituent chunks:

  • SFXB
    • WRAP
      • OFFS
      • DATA
      • DATA
      • ..

The SFXB chunk contains its preamble and the WRAP chunk. The WRAP chunk contains its preamble, an OFFS chunk and a series of DATA chunks. The OFFS chunk has the following format:

 bytes 0-3    'OFFS' FourCC
 bytes 4-7    chunk size
 bytes 8..    DATA chunk offsets

The DATA chunk offsets are 4-byte numbers stored in little endian format that fill the remainder of the OFFS chunk after the preamble. They indicate the offsets (and, implicitly, the count) of audio DATA chunks. The offsets are relative to the start of the OFFS chunk. It is instructive to note that since the first DATA chunk immediately follows the OFFS chunk, its offset will be the same as the size of the OFFS chunk, though stored in the opposite byte order. For example, if there were only one audio DATA chunk in the file, and the OFFS chunk began at 0x32E:

 0x32E  4F 46 46 53  00 00 00 0C  0C 00 00 00  44 41 54 41  OFFS........DATA
 0x33E  ....

The audio DATA chunks usually contain uncompressed PCM in 8-bit, unsigned format. But they sometimes contain the following hierarchical organizations:

  • DATA
    • TALK
      • HSHD
      • SDAT

In this case, the DATA chunk contains its preamble and the TALK chunk. The TALK chunk contains its preamble followed by the HSHD and SDAT chunks. The HSHD chunk has the following layout:

 bytes 0-3    'HSHD' FourCC
 bytes 4-7    chunk size = 0x18 = 24 bytes
 bytes 8-13   unknown
 bytes 14-15  sample rate
 bytes 16-23  unknown

The SDAT chunk contains uncompressed, unsigned, 8-bit PCM data.

After the SFXB is another chunk marked DATA. DATA has many meanings in this formats. This data chunk encapsulates a number of BLOK chunks. This is the hierarchical organization of BLOCK chunk:

  • BLOK
    • RGBS
    • RATE
    • SNDE
    • TOIL
    • FRAM
    • SRLE
    • WRLE
    • LZSS

The RGBS chunk, already described, indicates that the palette can change during playback. The RATE chunk has the following layout:

 bytes 0-3    'RATE'
 bytes 4-7    chunk size = 0xA = 10 bytes
 bytes 8-9    playback rate in milliseconds

This chunk allows to change the playback rate of the movie.

The SNDE chunk has the following format:

 bytes 0-3    'SNDE'
 bytes 4-7    chunk size = 0x12 = 18 bytes
 bytes 8-11   unknown
 bytes 12-13  unknown
 bytes 13-15  unknown
 bytes 15-17  unknown

While the purpose of this block is unknown, some of the numbers may reference back into the AUDIO data chunks to specify which piece of audio should be playing at the current time.

The TOIL chunk allows to execute special operations, it has the following format:

 bytes 0-3    'TOIL'
 bytes 4-7    chunk size (variable)
 bytes 8-9    number of opcodes
 bytes 10-    opcodes data

Each TOIL opcode data has the following format :

 byte  0      size of opcode
 byte  1      opcode number

The purpose of each opcode is :

 1  stop playback
 2  display copyright/information messageBox
 3  unknown
 4  restart playback
 5  disable screen update
 6  enable offscreen buffers swapping
 7  pause playback at specific frame

The SRLE, WRLE, FRAM and LZSS chunk types indicate video compression types and will be explained in their own sections.

TRLE Compression

TRLE (which presumably stands for "transparent run length encoding") is name of the bitmap compression algorithm used in a FRAM chunk.

SRLE Compression

SRLE is the name of one of the video compression algorithms seen in CUP files. It is suspected to be a simple run length encoding scheme.

LZSS (Tri-LZ) Compression

LZSS indicates one of the video compression algorithms seen in CUP files. It is a variant of the common LZ algorithm. An LZSS chunk has the following hierarchical organization:

  • LZSS
    • LZHD
    • DATA

Thus, the LZSS chunk contains its preamble followed by an LZHD chunk and (another type of!) DATA chunk. The LZHD chunk has the following layout:

 bytes 0-3    'LZHD' FourCC
 bytes 4-7    size = 0x10 = 16 bytes
 bytes 8-11   compression type
 bytes 12-15  size of decompressed data

The only valid compression type is 0x2000 which indicates the tri-lz method. The DATA chunk contains the compressed data.

A block of tri-lz compressed data is stored in 3 parts. In a compressed data block, part 1 starts at byte 8. Part 2 starts at the offset formed from bytes 0-3 of the compressed buffer. Part 3 starts at the offset formed from bytes 4-7 of the compressed buffer.

(TODO: finish description)