| Name | ATX_dxtcomp |
| Name strings | KD_ATX_dxtcomp |
| Contributors | Russell Wood, Phil Huxley, Elizabeth Wootten, Tim Renouf |
| Contacts | Antix Labs Limited |
| Status | Implemented by Antix Labs |
| Version | Version 5, 2009-02-04 |
| Number | 14 |
| 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. |
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.
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.
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:
KD_DXTCOMP_TYPE_DXT1_ATX#define KD_DXTCOMP_TYPE_DXT1_ATX 144
DXT1 compression is used without encoding the alpha channel of the input data.
The resulting image format is KD_IMAGE_FORMAT_DXT1.
KD_DXTCOMP_TYPE_DXT1A_ATX#define KD_DXTCOMP_TYPE_DXT1A_ATX 145
DXT1 compression is used and the alpha channel of the input data is encoded.
The resulting image format is KD_IMAGE_FORMAT_DXT1.
KD_DXTCOMP_TYPE_DXT3_ATX#define KD_DXTCOMP_TYPE_DXT3_ATX 146
DXT3 compression is used and encodes the alpha and color components of the input data.
The resulting image format is KD_IMAGE_FORMAT_DXT3.
KD_DXTCOMP_TYPE_DXT5_ATX#define KD_DXTCOMP_TYPE_DXT5_ATX 147
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.
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.