View source for Data Compression Library (libpress)

You do not have permission to edit this page. Log in to edit.
---
title: Data Compression Library (libpress)
type: component
summary: Provides functions for compressing and decompressing image and sound data.
category: Psy-Q
info: Library = libpress.lib
info: Header File = libpress.h
info: SDK = Psy-Q
---

## Overview

The Data Compression Library (libpress) is a low-level library for compressing (encoding) and decompressing (decoding) image and sound data. It handles single images and the frames of video sequences that have been compressed into the PlayStation MDEC format. The MDEC is the part of the PlayStation hardware that specializes in image decompression.[^o7-3]

Three methods compress images. DCT (Discrete Cosine Transform) compresses direct color images, BVQ (Block Vector Quantization) reduces a direct color image to 256 or 16 colors, and Huffman encoding with a fixed codebook compresses 4-bit index colors reversibly. For sound, libpress uses ADPCM to compress 16-bit straight PCM to about 1/4, and the SPU uses the result as sound source data.[^o7-3]

A program that uses libpress links with libpress.lib and includes libpress.h.[^o7-3]

This library is part of the run-time library that Sony distributed with the [Psy-Q](/sdk/psy-q/) development tools.[^ptcd]

## Compressor and Decompressor Functions

The compressor functions compress image and sound data in main memory and return the result to main memory. They are used when an application must compress data at run time and when data is made off line by remote control from the authoring environment. The local environment also has a DCT circuit that compresses images at high speed.[^o7-3]

The decompressor functions expand compressed data in real time. Some formats made by the compressor functions, such as BVQ, are processed by the hardware without conversion, and the decompressor functions do not handle them.[^o7-3]

## MDEC

The MDEC (Motion DECoder) is a dedicated engine for fast image expansion. It expands compressed data in main memory and returns the result to main memory, from where it is transferred to the display area of the frame buffer. The MDEC shares the main bus with the CPU and the other devices by time sharing. Consequently, it expands data in parallel with the program and with transfers to the frame buffer.[^o7-3][^o7-4]

## Image Compression

The method of compression depends on the type and use of the image data. The three methods compare as follows:[^o7-6]

Table: Compression and decompression algorithms

| Item | DCT | BVQ | Huffman |
| --- | --- | --- | --- |
| Type | Lossy | Lossy | Lossless |
| Input format | 24-bit or 16-bit | 24-bit or 16-bit | 4-bit |
| Output format | Bitstream | 4-bit or 8-bit | Bitstream |
| Compression ratio | 10% to 5% | 50% to 25% | |

## DCT

DCT is the compression method used in JPEG and MPEG. It compresses 24-bit or 16-bit direct color images with high efficiency, and although it is lossy, its compression ratio can be set at will, usually between 5% and 10%. The unit of DCT is the macroblock, which is a 16 x 16 area of 24-bit color. An image is divided into macroblocks before compression, so a 320 x 240 image becomes 20 x 15 macroblocks, and decompression also outputs macroblocks.[^o7-4][^o7-5]

DCT is a frequency transform that makes the data easier to compress. It concentrates the low frequencies of an ordinary image, so most of the coefficients become 0 while the data size stays the same. Huffman encoding of the result, called VLC (Variable Length Coding), then gives a much higher ratio than Huffman encoding of the image directly. The VLC output has no meaningful byte or word boundaries and is called a bitstream. The quantization step after the DCT controls the ratio, and a larger step gives more compression.[^o7-6]

A macroblock is encoded in the following steps:[^o7-7]

1. CSC (Color Space Conversion) converts the RGB macroblock to Y, Cb and Cr. Y is the brightness and Cb and Cr are the color differences.
2. Y is divided into four 8 x 8 blocks, and Cb and Cr are thinned to one 8 x 8 block each. The macroblock therefore has six blocks: Y0, Y1, Y2, Y3, Cb and Cr.
3. Each block is converted by DCT.
4. Each element is quantized by a fixed value.
5. The elements are listed in zig-zag order.
6. The elements are run length compressed into run level data.
7. VLC (Huffman encoding) of the run level data produces the bitstream (BS).

Decompression reverses these steps. The bitstream of 24-bit data can be decompressed in 16-bit or 24-bit mode, and in 16-bit mode the STP bit of each pixel can be set on or off.[^o7-7]

## Decompression

Decompression has two passes: VLC decoding first and the IDCT (Inverse Discrete Cosine Transform) second. DecDCTvlc() decodes the bitstream to run level data. The IDCT takes time, so the MDEC performs it in parallel with the CPU. DecDCTin() sends run level data to the MDEC, and DecDCTout() receives the decompressed macroblocks.[^o7-7][^o7-8]

The MDEC and the CPU share main memory. DecDCTin() sends the run level data in the background in the intervals of the CPU work, and DecDCTout() moves the macroblocks to main memory in the background. Because the exchange is asynchronous, one frame of 640 x 240 can be decompressed without a frame-sized buffer in main memory. For example, the image is split into slices of 16 x 240 (15 macroblocks), and one DecDCTin() is received by several DecDCTout() calls. The number of macroblocks sent and received must then match.[^o7-8]

DecDCTin() and DecDCTout() are non-blocking. DecDCTinSync() and DecDCToutSync() poll for their end, and DecDCTinCallback() and DecDCToutCallback() register callbacks. A callback that starts the next transfer makes the whole decompression asynchronous.[^o7-8][^o7-9]

## Movies

A movie plays by reading bitstreams from the CD-ROM continuously and decompressing them. The MDEC decompresses at most 9,000 macroblocks per second, the equivalent of thirty 320 x 240 images, and its speed does not depend on the compression ratio. The resolution and the frame rate are therefore inversely proportional:[^o7-9]

Table: Decompression speed and resolution

| Resolution | Frames per second |
| --- | --- |
| 320 x 240 | 30 |
| 640 x 240 | 15 |
| 640 x 480 | 7.5 |

The CD-ROM transfers 150 KB/sec at normal speed or 300 KB/sec at double speed. At double speed a frame compressed to 10 KB (300 KB / 30) or less is therefore read 30 times per second:[^o7-9]

Table: Transfer speed and data size

| Data size | Frames per second |
| --- | --- |
| 10 KB | 30 |
| 20 KB | 15 |
| 30 KB | 7.5 |

Within these two limits any frame rate, resolution and compression ratio can be chosen. Continuous reading from the CD-ROM is called streaming, and its functions are in [libcd](/sdk/psy-q/libcd/). The bitstream holds no movie size or similar information, so this information is defined in the STR data format that is added to the header.[^o7-9][^o7-10]

Simple playback uses VRAM as a double buffer and transfers each decompressed image into the drawing buffer. This is direct transmission. Texture transmission instead sends the images to the texture area, where they are used as 16-bit textures.[^o7-10]

## Local Encoding

DCT compression is not normally performed at run time. libpress nevertheless provides DCT compression functions, which compress images captured from the frame buffer with the CPU of the local environment during authoring. The DCT of the compression can also run on the IDCT circuit of the MDEC, which makes the encoding faster.[^o7-10]

## BVQ

BVQ reduces the colors of a 24-bit or 16-bit direct color image by vector quantization and produces an 8-bit or 4-bit index color image. Vector quantization quantizes values that cannot be ordered in one dimension adaptively by their frequency. An index color image consists of a CLUT, which holds the actual colors, and indexes into the CLUT. When the image has 16 colors or fewer the index takes 4 bits, so the image is 25% of the size of a 16-bit direct color image.[^o7-5][^o7-10]

DCT data is expanded to 16 bits before it reaches the frame buffer and saves no frame buffer space. A BVQ image, however, goes to the frame buffer still compressed and is used directly as a 4-bit or 8-bit texture pattern. The image is divided into small areas before quantization, normally by the (u, v) of the polygons, since each polygon can have its own CLUT.[^o7-5][^o7-10]

Many small areas produce many CLUTs, which can take too much space. libpress therefore quantizes the CLUTs themselves as well. For example, the 300 CLUTs of a 320 x 240 image divided into 300 cells of 16 x 16 in 4-bit mode can be combined into 8 CLUTs, and each pixel is then indexed twice, by the CLUT number of its area and by its index in that CLUT.[^o7-5][^o7-10]

## Huffman Encoding

DCT and BVQ are lossy, so libpress provides Huffman encoding for reversible compression of 4-bit index colors. It is the classical type with a fixed codebook. The encoder first builds the codebook from the frequency of the pixel values and assigns the shortest codes to the most frequent values. The output is a bitstream, as with DCT, and it is always decompressed together with its codebook.[^o7-6][^o7-11]

The ratio of a lossless method cannot be controlled and depends on the image, with higher compression when a few pixel values dominate. The codebook has a fixed size, so for a small number of pixels it takes a large share of the data and the compression is poor.[^o7-6][^o7-11]

## Sound Data

The PlayStation uses sound data compressed from 16-bit straight PCM to 4-bit ADPCM, which the SPU uses as sound source data without conversion. The SPU can loop sound, so periodic sound is recorded with few samples, and a loop point can be set when the sound is compressed.[^o7-11]

## Structures

In the tables below, Introduced is the run-time library version that added the item.[^refs63]

libpress has the following structures:[^refs63]

Table: libpress structures

| Structure | Introduced | Purpose |
| --- | --- | --- |
| `DECDCTENV` | 3.5 | Quantization tables used during MDEC decoding process. |
| `ENCSPUENV` | 3.6 | SPU encode environment attribute structure. |

## Functions

libpress has the following functions:[^reff65]

Table: libpress functions

| Function | Introduced | Purpose |
| --- | --- | --- |
| `DecDCTBufSize` | 2.x | Get size of run-level DCT data. |
| `DecDCTGetEnv` | 3.5 | Get current quantization tables and environment data used during MDEC image decoding. |
| `DecDCTin` | 2.x | Begin decoding RLE-encoded MDEC image data. |
| `DecDCTinCallback` | 2.x | Install a callback routine to be called at termination of MDEC transmission. |
| `DecDCTinSync` | 2.x | Detect DecDCTin() termination. |
| `DecDCTout` | 2.x | Receive decoded data from the image processing subsystem. |
| `DecDCToutCallback` | 2.x | Install a callback routine to be called at termination of MDEC transmission. |
| `DecDCToutSync` | 2.x | Detect termination of DecDCTout(). |
| `DecDCTPutEnv` | 3.5 | Set image-processing-subsystem environment. |
| `DecDCTReset` | 2.x | Initialize image processing subsystem. |
| `DecDCTvlc` | 2.x | Decode Huffman-compressed MDEC image data. |
| `DecDCTvlc2` | 3.7 | Decode VLC. |
| `DecDCTvlcBuild` | 3.7 | Build the VLC table. |
| `DecDCTvlcSize` | 3.2 | Set maximum amount of data returned by a single call to DecDCTvlc(). |
| `DecDCTvlcSize2` | 3.7 | Set maximum size of single VLC decoding process. |
| `EncSPU` | 3.6 | Encode 16-bit PCM data into PlayStation waveform format. |

## References

[^o7-3]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 7-3.
[^o7-4]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 7-4.
[^o7-5]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 7-5.
[^o7-6]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 7-6.
[^o7-7]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 7-7.
[^o7-8]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 7-8.
[^o7-9]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 7-9.
[^o7-10]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 7-10.
[^o7-11]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 7-11.
[^refs63]: Sony Computer Entertainment Inc. Run-Time Library Reference. Run-Time Library 4.4. January 1999. Pages 6-3 to 6-4.
[^reff65]: Sony Computer Entertainment Inc. Run-Time Library Reference. Run-Time Library 4.4. January 1999. Pages 6-5 to 6-20.
[^ptcd]: Sony Computer Entertainment Inc. Programmer Tools CD (DTL-S2002), README.TXT. 11/26/96. Section "CD-ROM Contents - Highlights", directories \PSX and \PSYQ.