OpenKODE Core extension: KD_ATX_dxtcomp

Name stringsKD_ATX_dxtcomp
ContributorsRussell Wood, Phil Huxley, Elizabeth Wootten, Tim Renouf
ContactsAntix Labs Limited
StatusImplemented by Antix Labs
VersionVersion 5, 2009-02-04
Dependencies Requires OpenKODE Core 1.0, the ATX_imgdec extension and the ATX_imgdec_pvr extension. This extension is written based on the wording of the OpenKODE Core 1.0 specification, version 4 of the ATX_imgdec extension, and version 4 of the ATX_imgdec_pvr extension.

1. Overview

This OpenKODE Core extension provides functions for compressing RGBA image data to a DXT format. It extends the functionality of the image decoder extensions KD_ATX_imgdec and KD_ATX_imgdec_pvr.

This extension can assist in lowering the asset sizes needed to be packaged with a game by allowing graphics to be supplied using PVRTC compression. On platforms that provide DXT support this can be decoded as RGBA data and recompressed as DXT. For platforms that support neither compression format, images can be decompressed to an OpenGL-compatible RGB(A) type.

There are quality issues associated with texture compression, and where the resulting texture quality is not acceptable this extension should not be used.

The documentation for the GL_EXT_texture_compression_s3tc OpenGL extension describes the DXT data formats.

Implementations of this extension are expected to provide fast compression such that image assets can be converted by an application at run-time. Encoding accuracy can be sacrificed for real-time performance. If the highest quality compression is required then off-line compression of assets should be used in place of this extension.

Suitable algorithms are described in the paper Real-Time DXT Compression by J.M.P. van Wavern, Id Software Inc.

2. Header file

When this extension is present, its facilities are accessed by including its header file:

#include <KD/ATX_dxtcomp.h>

This also includes KD/ATX_imgdec_pvr.h (and thus KD/ATX_imgdec.h) if that has not already been done.

3. New functions

3.1.  kdDXTCompressImageATX, kdDXTCompressBufferATX

Compresses an image into a DXT format.


KDImageATX kdDXTCompressImageATX(KDImageATX image,
 KDint32  comptype);
KDImageATX kdDXTCompressBufferATX(const void * buffer,
 KDint32  width,
 KDint32  height,
 KDint32  compType,
 KDint32  levels);


These functions read an image and compress it to one of the DXT compressed image format. The compressed image is returned in a KDImageATX object.

For kdDXTCompressImageATX, image is the input image as a KDImageATX image object (a decoded image object, not an informational image object). It must have a format of KD_IMAGE_FORMAT_RGBA8888_ATX, and its width and height must both be powers of two.

For kdDXTCompressBufferATX, buffer is a 4-aligned buffer containing the input image bitmap. It must be in the same format as would be found in the image data in an image object of format KD_IMAGE_FORMAT_RGBA8888_ATX. On entry width and height are the image width and height in pixels, and each must be a power of two. levels is the number of extra mipmap levels beyond the main level to be compressed, thus 0 means compress just the main image. If mipmaps are included they should follow the top-level image in memory and be tightly packed.

For both functions, comptype specifies the output format for the compressed image, one of:


DXT1 compression is used without encoding the alpha channel of the input data.

The resulting image format is KD_IMAGE_FORMAT_DXT1.


DXT1 compression is used and the alpha channel of the input data is encoded.

The resulting image format is KD_IMAGE_FORMAT_DXT1.


DXT3 compression is used and encodes the alpha and color components of the input data.

The resulting image format is KD_IMAGE_FORMAT_DXT3.


DXT5 compression is used and encodes the alpha and color components of the input data.

The resulting image format is KD_IMAGE_FORMAT_DXT5.

For kdDXTCompressImageATX, if image is not a valid KDImageATX object, then undefined behavior results. For kdDXTCompressBufferATX, if buffer does not point to a 4-aligned readable buffer of at least enough size for the specified image size and number of mipmap levels, then undefined behavior results.

Return Value

On success, the functions return the KDImageATX handle to a new image object (a decoded image object, that is, one with image data attached). The image object can be queried using kdGetImagePointerATX(), kdGetImageIntATX() or kdGetImageLevelIntATX(), and freed using kdFreeImageATX().

On failure, the functions return KD_NULL and store one of the error codes below into the error indicator returned by kdGetError.

Error codes


The image object does not have any image data attached, or the format is not KD_IMAGE_FORMAT_RGBA8888_ATX, or the width or height is not a power of two, or the requested compression format is not recognized.


The operation failed due to insufficient memory.

4. Revision history

4.1. Version 5, 2009-02-04

  • Allocated extension number 14.

4.2. Version 4, 2008-09-16

  • Allocated extension number 12.

4.3. Version 3, 2008-06-20

  • Draft of version prepared to release to OpenKODE WG.