Compressed Texture Images

Texture images may also be specified or modified using image data already stored in a known compressed image format, such as the RGTC formats defined in ap- pendixC, or additional formats defined by GL extensions.

The commands

void CompressedTexImage1D(enumtarget, intlevel, enuminternalformat, sizeiwidth, intborder, sizeiimageSize, void*data);

void CompressedTexImage2D(enumtarget, intlevel, enuminternalformat, sizeiwidth, sizeiheight, intborder, sizeiimageSize, void*data);

void CompressedTexImage3D(enumtarget, intlevel, enuminternalformat, sizeiwidth, sizeiheight,

sizeidepth, intborder, sizeiimageSize, void*data);

define one-, two-, and three-dimensional texture images, respectively, with incom- ing data stored in a specific compressed image format. The target, level, inter- nalformat,width,height,depth, andborderparameters have the same meaning as inTexImage1D, TexImage2D, andTexImage3D, except that compressed rect- angular texture formats are not supported. data refers to compressed image data stored in the specific compressed image format corresponding to internal- format. If a pixel unpack buffer is bound (as indicated by a non-zero value of

PIXEL UNPACK BUFFER BINDING),datais an offset into the pixel unpack buffer and the compressed data is read from the buffer relative to this offset; otherwise,

data is a pointer to client memory and the compressed data is read from client memory relative to the pointer.

If thetargetparameter to any of the CompressedTexImagenDcommands is

TEXTURE RECTANGLEorPROXY TEXTURE RECTANGLE, the errorINVALID ENUM

is generated.

internalformat must be a supported specific compressed internal format. An

3.8. TEXTURING 136

generic compressed internal formats, is specified.

For all other compressed internal formats, the compressed image will be de- coded according to the specification defining the internalformat token. Com- pressed texture images are treated as an array of imageSize ubytes relative to

data. If a pixel unpack buffer object is bound anddata+imageSizeis greater than the size of the pixel buffer, anINVALID OPERATIONerror results. All pixel storage modes are ignored when decoding a compressed texture image. If theim- ageSizeparameter is not consistent with the format, dimensions, and contents of the compressed image, anINVALID VALUEerror results. If the compressed image is not encoded according to the defined image format, the results of the call are undefined.

Specific compressed internal formats may impose format-specific restrictions on the use of the compressed image specification calls or parameters. For example, the compressed image format might be supported only for 2D textures, or might not allow non-zerobordervalues. Any such restrictions will be documented in the extension specification defining the compressed internal format; violating these restrictions will result in anINVALID OPERATIONerror.

Any restrictions imposed by specific compressed internal formats will be invariant, meaning that if the GL accepts and stores a texture image in compressed form, providing the same image to CompressedTexImage1D, CompressedTexImage2D, or CompressedTexImage3D will not result in an

INVALID OPERATIONerror if the following restrictions are satisfied:

• datapoints to a compressed texture image returned byGetCompressedTex- Image(section6.1.4).

• target,level, andinternalformatmatch thetarget,levelandformatparame- ters provided to theGetCompressedTexImagecall returningdata.

• width, height, depth, border, internalformat, and image-

Size match the values of TEXTURE WIDTH, TEXTURE HEIGHT,

TEXTURE DEPTH, TEXTURE BORDER, TEXTURE INTERNAL FORMAT,

andTEXTURE COMPRESSED IMAGE SIZE for image levellevelin effect at the time of theGetCompressedTexImagecall returningdata.

This guarantee applies not just to images returned byGetCompressedTexImage, but also to any other properly encoded compressed texture image of the same size and format.

Ifinternalformat is one of the specificRGTCformats described in table3.14, the compressed image data is stored using one of the RGTC compressed texture image encodings (see appendix C.1) The RGTC texture compression algorithm

3.8. TEXTURING 137

supports only two-dimensional images without borders. If internalformat is an RGTC format,CompressedTexImage1Dwill generate anINVALID ENUMerror; CompressedTexImage2D will generate an INVALID OPERATION error if bor- deris non-zero ortargetisTEXTURE RECTANGLE; andCompressedTexImage3D will generate anINVALID OPERATIONerror ifborderis non-zero ortargetis not

TEXTURE 2D ARRAY. The commands

void CompressedTexSubImage1D(enumtarget, intlevel, intxoffset, sizeiwidth, enumformat, sizeiimageSize, void*data);

void CompressedTexSubImage2D(enumtarget, intlevel, intxoffset, intyoffset, sizeiwidth, sizeiheight, enumformat, sizeiimageSize, void*data);

void CompressedTexSubImage3D(enumtarget, intlevel, intxoffset, intyoffset, intzoffset, sizeiwidth, sizeiheight, sizeidepth, enumformat,

sizeiimageSize, void*data);

respecify only a rectangular region of an existing texel array, with incoming data stored in a known compressed image format. Thetarget,level,xoffset,yoffset,zoff- set,width,height, anddepthparameters have the same meaning as inTexSubIm- age1D,TexSubImage2D, andTexSubImage3D.datapoints to compressed image data stored in the compressed image format corresponding toformat. Using any of the generic compressed internal formats asformatwill result in anINVALID ENUM

error.

If the target parameter to any of the CompressedTexSubImagenD com- mands is TEXTURE RECTANGLE or PROXY TEXTURE RECTANGLE, the error

INVALID ENUMis generated.

The image pointed to by data and the imageSize parameter are interpreted as though they were provided toCompressedTexImage1D,CompressedTexIm- age2D, and CompressedTexImage3D. These commands do not provide for im- age format conversion, so an INVALID OPERATION error results if format does not match the internal format of the texture image being modified. If theimage- Sizeparameter is not consistent with the format, dimensions, and contents of the compressed image (too little or too much data), anINVALID VALUEerror results.

As with CompressedTexImagecalls, compressed internal formats may have additional restrictions on the use of the compressed image specification calls or parameters. Any such restrictions will be documented in the specification defin- ing the compressed internal format; violating these restrictions will result in an

3.8. TEXTURING 138

Any restrictions imposed by specific compressed internal formats will be invariant, meaning that if the GL accepts and stores a texture image in com- pressed form, providing the same image toCompressedTexSubImage1D,Com- pressedTexSubImage2D, CompressedTexSubImage3D will not result in an

INVALID OPERATIONerror if the following restrictions are satisfied:

• datapoints to a compressed texture image returned byGetCompressedTex- Image(section6.1.4).

• target,level, andformatmatch thetarget, levelandformatparameters pro- vided to theGetCompressedTexImagecall returningdata.

• width, height, depth, format, and imageSize match the val-

ues of TEXTURE WIDTH, TEXTURE HEIGHT, TEXTURE DEPTH,

TEXTURE INTERNAL FORMAT, and TEXTURE COMPRESSED IMAGE SIZE

for image levellevelin effect at the time of theGetCompressedTexImage call returningdata.

• width, height, depth, format match the values of TEXTURE WIDTH,

TEXTURE HEIGHT, TEXTURE DEPTH, and TEXTURE INTERNAL FORMAT

currently in effect for image levellevel.

• xoffset, yoffset, and zoffset are all −b, where b is the value of

TEXTURE BORDERcurrently in effect for image levellevel.

This guarantee applies not just to images returned byGetCompressedTexIm- age, but also to any other properly encoded compressed texture image of the same size.

Calling CompressedTexSubImage3D, CompressedTexSubImage2D, or CompressedTexSubImage1Dwill result in anINVALID OPERATIONerror ifxoff- set, yoffset, or zoffset is not equal to −bs (border width), or if width, height,

and depth do not match the values of TEXTURE WIDTH, TEXTURE HEIGHT, or

TEXTURE DEPTH, respectively. The contents of any texel outside the region modi- fied by the call are undefined. These restrictions may be relaxed for specific com- pressed internal formats whose images are easily modified.

Ifinternalformat is one of the specificRGTCformats described in table3.14, the texture is stored using one of the RGTC compressed texture image encodings (see appendixC.1). Ifinternalformatis an RGTC format,CompressedTexSubIm- age1Dwill generate anINVALID ENUMerror;CompressedTexSubImage2Dwill generate anINVALID OPERATIONerror ifborderis non-zero; andCompressed- TexSubImage3Dwill generate anINVALID OPERATION error if borderis non- zero or targetis not TEXTURE 2D ARRAY. Since RGTC images are easily edited

3.8. TEXTURING 139

along 4 × 4 texel boundaries, the limitations on subimage location and size are relaxed forCompressedTexSubImage2DandCompressedTexSubImage3D. These commands will result in anINVALID OPERATIONerror if one of the follow- ing conditions occurs:

• widthis not a multiple of four or equal toTEXTURE WIDTH. • heightis not a multiple of four or equal toTEXTURE HEIGHT. • xoffsetoryoffsetis not a multiple of four.

The contents of any 4×4 block of texels of an RGTC compressed texture image that does not intersect the area being modified are preserved during valid TexSubImage*andCopyTexSubImage*calls.