Export to GitHub

glextensions - GL_ARB_texture_compression.wiki

Dependencies
Overview
New Procedures and Functions
New Tokens
Errors

Dependencies

OpenGL 1.1 is required.

This extension is written against the OpenGL 1.2.1 Specification.

This extension is written against the GLX Extensions for OpenGL Specification (Version 1.3).

Depends on GL_ARB_texture_cube_map, as cube maps may be stored in compressed form.

Overview

Compressing texture images can reduce texture memory utilization and improve performance when rendering textured primitives. This extension allows OpenGL applications to use compressed texture images by providing:

(1) A framework upon which extensions providing specific compressed image formats can be built.

(2) A set of generic compressed internal formats that allow applications to specify that texture images should be stored in compressed form without needing to code for specific compression formats.

An application can define compressed texture images by providing a texture image stored in a specific compressed image format. This extension does not define any specific compressed image formats, but it does provide the mechanisms necessary to enable other extensions that do.

An application can also define compressed texture images by providing an uncompressed texture image but specifying a compressed internal format. In this case, the GL will automatically compress the texture image using the appropriate image format. Compressed internal formats can either be specific (as above) or generic. Generic compressed internal formats are not actual image formats, but are instead mapped into one of the specific compressed formats provided by the GL (or to an uncompressed base internal format if no appropriate compressed format is available). Generic compressed internal formats allow applications to use texture compression without needing to code to any particular compression algorithm. Generic compressed formats allow the use of texture compression across a wide range of platforms with differing compression algorithms and also allow future GL implementations to substitute improved compression methods transparently.

Compressed texture images can be obtained from the GL in uncompressed form by calling GetTexImage and in compressed form by calling !GetCompressedTexImageARB. Queried compressed images can be saved and later reused by calling CompressedTexImage[123]DARB. Pre-compressed texture images do not need to be processed by the GL and should significantly improve texture loading performance relative to uncompressed images.

This extension does not define specific compressed image formats (e.g., S3TC, FXT1), nor does it provide means to encode or decode such images. To support images in a specific compressed format, a hardware vendor would:

(1) Provide a new extension defininig specific compressed

and

tokens for TexImage[123]D, TexSubImage[123]D, CopyTexImage[12]D, CompressedTexImage[123]DARB, CompressedTexSubImage[123]DARB, and !GetCompressedTexImageARB calls.

(2) Specify the encoding of compressed images of that specific format.

(3) Specify a method for deriving the size of compressed images of that specific format, using the

<width>

<depth>

parameters, and (if necessary) the compressed image itself.

New Procedures and Functions

``` void CompressedTexImage3DARB(enum target, int level, enum internalformat, sizei width, sizei height, sizei depth, int border, sizei imageSize, const void *data);

void CompressedTexImage2DARB(enum target, int level, enum internalformat, sizei width, sizei height, int border, sizei imageSize, const void *data);

void CompressedTexImage1DARB(enum target, int level, enum internalformat, sizei width, int border, sizei imageSize, const void *data);

void CompressedTexSubImage3DARB(enum target, int level, int xoffset, int yoffset, int zoffset, sizei width, sizei height, sizei depth, enum format, sizei imageSize, const void *data);

void CompressedTexSubImage2DARB(enum target, int level, int xoffset, int yoffset, sizei width, sizei height, enum format, sizei imageSize, const void *data);

void CompressedTexSubImage1DARB(enum target, int level, int xoffset, sizei width, enum format, sizei imageSize, const void *data);

void GetCompressedTexImageARB(enum target, int lod, void *img); ```

New Tokens

Accepted by the

parameter of TexImage1D, TexImage2D, TexImage3D, CopyTexImage1D, and CopyTexImage2D:

|COMPRESSED_ALPHA_ARB | 0x84E9| |:----------------------------------------|:--------------| |COMPRESSED_LUMINANCE_ARB | 0x84EA| |COMPRESSED_LUMINANCE_ALPHA_ARB | 0x84EB| |COMPRESSED_INTENSITY_ARB | 0x84EC | |COMPRESSED_RGB_ARB | 0x84ED | |COMPRESSED_RGBA_ARB | 0x84EE|

Accepted by the

parameter of Hint and the

<value>

parameter of GetIntegerv, GetBooleanv, GetFloatv, and GetDoublev:

|TEXTURE_COMPRESSION_HINT_ARB | 0x84EF| |:----------------------------------------|:---------------|

Accepted by the

<value>

parameter of GetTexLevelParameter:

|TEXTURE_COMPRESSED_IMAGE_SIZE_ARB | 0x86A0| |:-----------------------------------------|:---------------| |TEXTURE_COMPRESSED_ARB | 0x86A1|

Accepted by the

<value>

parameter of GetIntegerv, GetBooleanv, GetFloatv, and GetDoublev:

|NUM_COMPRESSED_TEXTURE_FORMATS_ARB | 0x86A2| |:--------------------------------------------|:------------| |COMPRESSED_TEXTURE_FORMATS_ARB | 0x86A3|

Errors

Errors for compressed TexImage and TexSubImage calls specific to compression:

INVALID_OPERATION is generated by TexSubImage1D, TexSubImage2D, TexSubImage3D, CopyTexSubImage1D, CopyTexSubImage2D, or CopyTexSubImage3D if the internal format of the texture image is compressed and

, or

does not equal -b, where b is value of TEXTURE_BORDER.

INVALID_VALUE is generated by CompressedTexSubImage1DARB, CompressedTexSubImage2DARB, or CompressedTexSubImage3DARB if the entire texture image is not being edited: if

, or

is greater than -b,

<width>

is less than w+b,

is less than h+b, or

<depth>

is less than d+b, where b is the value of TEXTURE_BORDER, w is the value of TEXTURE_WIDTH, h is the value of TEXTURE_HEIGHT, and d is the value of TEXTURE_DEPTH.

INVALID_ENUM is generated by CompressedTexImage1DARB, CompressedTexImage2DARB, or CompressedTexImage3DARB, CompressedTexSubImage1DARB, CompressedTexSubImage2DARB, or CompressedTexSubImage3DARB, if

is any of the six generic compressed internal formats (e.g., COMPRESSED_RGBA_ARB)

INVALID_OPERATION is generated by CompressedTexImage1DARB, CompressedTexImage2DARB, CompressedTexImage3DARB, CompressedTexSubImage1DARB, CompressedTexSubImage2DARB, or CompressedTexSubImage3DARB, if any parameter combinations are not supported by the specific compressed internal format. Such invalid combinations are documented in the specification defining the internal format.

INVALID_VALUE is generated by CompressedTexImage1DARB, CompressedTexImage2DARB, or CompressedTexImage3DARB, CompressedTexSubImage1DARB, CompressedTexSubImage2DARB, or CompressedTexSubImage3DARB, if

is not consistent with the format, dimensions, and contents of the specified image. The appropriate value for the

parameter is documented in the specification defining the compressed internal format.

Undefined results (including abnormal program termination) are generated by CompressedTexImage1DARB, CompressedTexImage2DARB, or CompressedTexImage3DARB, CompressedTexSubImage1DARB, CompressedTexSubImage2DARB, or CompressedTexSubImage3DARB, is not encoded in a manner consistent with the specification defining the internal format.

INVALID_OPERATION is generated by CompressedTexSubImage1DARB, CompressedTexSubImage2DARB, or CompressedTexSubImage3DARB if

does not match the internal format of the texture image being modified.

INVALID_OPERATION is generated by GetTexLevelParameter[if]v if

is PROXY_TEXTURE_1D, PROXY_TEXTURE_2D, or PROXY_TEXTURE_3D and

<value>

is TEXTURE_COMPRESSED_IMAGE_SIZE_ARB.

INVALID_OPERATION is generated by GetTexLevelParameter[if]v if the internal format of the queried texture image is not compressed and

<value>

is TEXTURE_COMPRESSED_IMAGE_SIZE_ARB.

INVALID_OPERATION is generated by !GetCompressedTexImageARB if the internal format of the queried texture image is not compressed.

Errors for compressed TexImage and TexSubImage calls not specific to compression:

INVALID_ENUM is generated by CompressedTexImage3DARB or CompressedTexSubImage3DARB if

is not TEXTURE_3D.

INVALID_ENUM is generated by CompressedTexImage2DARB or CompressedTexSubImage2DARB if

is not TEXTURE_2D, TEXTURE_CUBE_MAP_POSITIVE_X_ARB, TEXTURE_CUBE_MAP_NEGATIVE_X_ARB, TEXTURE_CUBE_MAP_POSITIVE_Y_ARB, TEXTURE_CUBE_MAP_NEGATIVE_Y_ARB, TEXTURE_CUBE_MAP_POSITIVE_Z_ARB, or TEXTURE_CUBE_MAP_NEGATIVE_Z_ARB.

INVALID_ENUM is generated by CompressedTexImage1DARB or CompressedTexSubImage1DARB if

is not TEXTURE_1D.

INVALID_VALUE is generated by CompressedTexImage1DARB, CompressedTexImage2DARB, CompressedTexImage3DARB, CompressedTexSubImage1DARB, CompressedTexSubImage1DARB, or CompressedTexSubImage3DARB if

<level>

is negative.

INVALID_VALUE is generated by CompressedTexImage1DARB, CompressedTexImage2DARB, CompressedTexImage3DARB, CompressedTexSubImage1DARB, CompressedTexSubImage2DARB, or CompressedTexSubImage3DARB, if

<width>

, or

<depth>

is negative.

INVALID_VALUE is generated by CompressedTexImage1DARB, CompressedTexImage2DARB, or CompressedTexImage3DARB if

<width>

, or

<depth>

can not be represented as 2^k+2 for some integer value k.

INVALID_VALUE is generated by CompressedTexImage1DARB, CompressedTexImage2DARB, or CompressedTexImage3DARB if

is not zero or one.

INVALID_VALUE is generated by CompressedTexImage1DARB, CompressedTexImage2DARB, CompressedTexImage3DARB, CompressedTexSubImage1DARB, CompressedTexSubImage1DARB, or CompressedTexSubImage3DARB if the call is made between a call to Begin and the corresponding call to End.

INVALID_VALUE is generated by CompressedTexSubImage1DARB, CompressedTexSubImage2DARB, or CompressedTexSubImage3DARB if

, or

is less than -b,

<width>

is greater than w+b,

<height>

is greater than h+b, or

<depth>

is greater than d+b, where b is the value of TEXTURE_BORDER, w is the value of TEXTURE_WIDTH, h is the value of TEXTURE_HEIGHT, and d is the value of TEXTURE_DEPTH.

INVALID_VALUE is generated by GetCompressedTexImageARB if

<lod>

is negative or greater than the maximum allowable level.

Code

Archive

glextensions - GL_ARB_texture_compression.wiki

Contents

Dependencies

Overview

New Procedures and Functions

New Tokens

Errors