3.8 Texturing
3.8.2 Alternate Texture Image Specification Commands
Two-dimensional and one-dimensional texture images may also be specified us- ing image data taken directly from the framebuffer, and rectangular subregions of existing texture images may be respecified.
The command
void CopyTexImage2D(enumtarget, intlevel, enuminternalformat, intx, inty, sizeiwidth, sizeiheight, intborder);
defines a two-dimensional texel array in exactly the manner of TexIm- age2D, except that the image data are taken from the framebuffer rather
3.8. TEXTURING 129 i −1 0 1 2 3 4 5 6 7 8 u −1.0 9.0 0.0 s 1.0 −1 0 2 1 3 4 j −1.0 5.0 v t 0.0 1.0 α β
Figure 3.6. A texture image and the coordinates used to access it. This is a two- dimensional texture withn = 3andm = 2. A one-dimensional texture would consist of a single horizontal strip.αandβ, values used in blending adjacent texels to obtain a texture value, are also shown.
3.8. TEXTURING 130
than from client memory. Currently, target must be one of TEXTURE 2D,
TEXTURE 1D ARRAY, TEXTURE RECTANGLE, TEXTURE CUBE MAP POSITIVE X,
TEXTURE CUBE MAP NEGATIVE X, TEXTURE CUBE MAP POSITIVE Y,
TEXTURE CUBE MAP NEGATIVE Y, TEXTURE CUBE MAP POSITIVE Z, or
TEXTURE CUBE MAP NEGATIVE Z. x, y, width, and height correspond precisely to the corresponding arguments toReadPixels(refer to section4.3.1); they specify the image’swidth andheight, and the lower left(x, y) coordinates of the frame- buffer region to be copied. The image is taken from the framebuffer exactly as if these arguments were passed toReadPixels with argumenttypeset to COLOR,
DEPTH, or DEPTH STENCIL, depending on internalformat, stopping after con- version of depth values. RGBA data is taken from the current color buffer, while depth component and stencil index data are taken from the depth and sten- cil buffers, respectively. The error INVALID OPERATION is generated if depth component data is required and no depth buffer is present; if stencil index data is required and no stencil buffer is present; if integer RGBA data is required and the format of the current color buffer is not integer; or if floating- or fixed-point RGBA data is required and the format of the current color buffer is integer.
Subsequent processing is identical to that described forTexImage2D, begin- ning with clamping of the R, G, B, A, or depth values, and masking of the stencil index values from the resulting pixel groups. Parameterslevel,internalformat, and
borderare specified using the same values, with the same meanings, as the equiv- alent arguments of TexImage2D. An invalid value specified for internalformat
generates the errorINVALID ENUM. The constraints onwidth,height, andborder
are exactly those for the equivalent arguments ofTexImage2D.
When the target parameter toCopyTexImage2Dis one of the six cube map two-dimensional image targets, the errorINVALID VALUEis generated if thewidth
andheightparameters are not equal.
AnINVALID FRAMEBUFFER OPERATIONerror will be generated if the object bound toREAD FRAMEBUFFER BINDING(see section4.4) is not framebuffer com- plete (as defined in section4.4.4). AnINVALID OPERATIONerror will be gener- ated if the object bound toREAD FRAMEBUFFER BINDINGis framebuffer complete and the value ofSAMPLE BUFFERSis greater than zero.
The command
void CopyTexImage1D(enumtarget, intlevel, enuminternalformat, intx, inty, sizeiwidth, intborder);
defines a one-dimensional texel array in exactly the manner ofTexImage1D, ex- cept that the image data are taken from the framebuffer, rather than from client
3.8. TEXTURING 131
memory. Currently,targetmust beTEXTURE 1D. For the purposes of decoding the texture image,CopyTexImage1Dis equivalent to callingCopyTexImage2Dwith corresponding arguments and heightof 1, except that the heightof the image is always 1, regardless of the value ofborder. level, internalformat, andborderare specified using the same values, with the same meanings, as the equivalent argu- ments of TexImage1D. The constraints onwidthandborderare exactly those of the equivalent arguments ofTexImage1D.
Six additional commands,
void TexSubImage3D(enumtarget, intlevel, intxoffset, intyoffset, intzoffset, sizeiwidth, sizeiheight, sizeidepth, enumformat, enumtype, void*data); void TexSubImage2D(enumtarget, intlevel, intxoffset,
intyoffset, sizeiwidth, sizeiheight, enumformat, enumtype, void*data);
void TexSubImage1D(enumtarget, intlevel, intxoffset, sizeiwidth, enumformat, enumtype, void*data); void CopyTexSubImage3D(enumtarget, intlevel,
intxoffset, intyoffset, intzoffset, intx, inty, sizeiwidth, sizeiheight);
void CopyTexSubImage2D(enumtarget, intlevel, intxoffset, intyoffset, intx, inty, sizeiwidth, sizeiheight);
void CopyTexSubImage1D(enumtarget, intlevel, intxoffset, intx, inty, sizeiwidth);
respecify only a rectangular subregion of an existing texel array. No change is made to the internalformat, width, height, depth, or border parameters of the specified texel array, nor is any change made to texel values out- side the specified subregion. Currently the target arguments of TexSubIm- age1D and CopyTexSubImage1D must be TEXTURE 1D, the target arguments of TexSubImage2D and CopyTexSubImage2D must be one of TEXTURE 2D,
TEXTURE 1D ARRAY, TEXTURE RECTANGLE, TEXTURE CUBE MAP POSITIVE X,
TEXTURE CUBE MAP NEGATIVE X, TEXTURE CUBE MAP POSITIVE Y,
TEXTURE CUBE MAP NEGATIVE Y, TEXTURE CUBE MAP POSITIVE Z, or
TEXTURE CUBE MAP NEGATIVE Z, and thetargetarguments ofTexSubImage3D and CopyTexSubImage3D must be TEXTURE 3D or TEXTURE 2D ARRAY. The
levelparameter of each command specifies the level of the texel array that is mod- ified. Iflevelis less than zero or greater than the base 2 logarithm of the maximum texture width, height, or depth, the errorINVALID VALUEis generated. Iftarget
3.8. TEXTURING 132
isTEXTURE RECTANGLEandlevelis not zero, the errorINVALID VALUEis gen- erated. TexSubImage3Dargumentswidth,height,depth,format,type, anddata
match the corresponding arguments toTexImage3D, meaning that they are spec- ified using the same values, and have the same meanings. Likewise,TexSubIm- age2Dargumentswidth, height, format, type, and datamatch the corresponding arguments toTexImage2D, andTexSubImage1Dargumentswidth,format,type, anddatamatch the corresponding arguments toTexImage1D.
CopyTexSubImage3D and CopyTexSubImage2D arguments x, y, width, andheightmatch the corresponding arguments toCopyTexImage2D1.CopyTex-
SubImage1D arguments x, y, and width match the corresponding arguments to CopyTexImage1D. Each of theTexSubImagecommands interprets and processes pixel groups in exactly the manner of itsTexImagecounterpart, except that the as- signment of R, G, B, A, depth, and stencil index pixel group values to the texture components is controlled by theinternalformatof the texel array, not by an argu- ment to the command. The same constraints and errors apply to theTexSubImage commands’ argumentformat and the internalformat of the texel array being re- specified as apply to the format and internalformat arguments of its TexImage counterparts.
Arguments xoffset, yoffset, and zoffset of TexSubImage3D and CopyTex- SubImage3Dspecify the lower left texel coordinates of awidth-wide byheight- high bydepth-deep rectangular subregion of the texel array. Thedepthargument associated withCopyTexSubImage3Dis always 1, because framebuffer memory is two-dimensional - only a portion of a single s, t slice of a three-dimensional texture is replaced byCopyTexSubImage3D.
Negative values of xoffset, yoffset, and zoffset correspond to the coordinates of border texels, addressed as in figure3.6. Taking ws, hs,ds, wb,hb, anddb to
be the specified width, height, depth, and border width, border height, and border depth of the texel array, and takingx,y,z, w, h, anddto be thexoffset,yoffset,
zoffset,width,height, anddepthargument values, any of the following relationships generates the errorINVALID VALUE:
x <−wb
x+w > ws−wb
y <−hb
y+h > hs−hb
z <−db
1 Because the framebuffer is inherently two-dimensional, there is noCopyTexImage3Dcom- mand.
3.8. TEXTURING 133
z+d > ds−db
Counting from zero, thenth pixel group is assigned to the texel with internal integer coordinates[i, j, k], where
i=x+ (nmodw)
j=y+ (bn
wcmodh) k=z+ (b n
width∗heightcmodd
ArgumentsxoffsetandyoffsetofTexSubImage2DandCopyTexSubImage2D specify the lower left texel coordinates of awidth-wide byheight-high rectangular subregion of the texel array. Negative values ofxoffset andyoffset correspond to the coordinates of border texels, addressed as in figure3.6. Takingws,hs, andbs
to be the specified width, height, and border width of the texel array, and takingx,
y,w, andhto be thexoffset,yoffset,width, andheightargument values, any of the following relationships generates the errorINVALID VALUE:
x <−bs
x+w > ws−bs
y <−bs
y+h > hs−bs
Counting from zero, thenth pixel group is assigned to the texel with internal integer coordinates[i, j], where
i=x+ (nmodw)
j=y+ (bn
wcmodh)
The xoffset argument ofTexSubImage1DandCopyTexSubImage1D speci- fies the left texel coordinate of awidth-wide subregion of the texel array. Negative values ofxoffsetcorrespond to the coordinates of border texels. Takingwsandbs
to be the specified width and border width of the texel array, andxandwto be the
xoffsetandwidthargument values, either of the following relationships generates the errorINVALID VALUE:
x <−bs
3.8. TEXTURING 134
Counting from zero, thenth pixel group is assigned to the texel with internal integer coordinates[i], where
i=x+ (nmodw)
Texture images with compressed internal formats may be stored in such a way that it is not possible to modify an image with subimage commands without having to decompress and recompress the texture image. Even if the image were modi- fied in this manner, it may not be possible to preserve the contents of some of the texels outside the region being modified. To avoid these complications, the GL does not support arbitrary modifications to texture images with compressed internal formats. CallingTexSubImage3D,CopyTexSubImage3D,TexSubIm- age2D,CopyTexSubImage2D,TexSubImage1D, orCopyTexSubImage1Dwill result in anINVALID OPERATIONerror ifxoffset,yoffset, orzoffsetis not equal to −bs(border width). In addition, the contents of any texel outside the region mod-
ified by such a call are undefined. These restrictions may be relaxed for specific compressed internal formats whose images are easily modified.
If the internal format of the texture image being modified is one of the spe- cificRGTCformats described in table 3.14, the texture is stored using one of the RGTC texture image encodings (see appendixC.1). Since RGTC images are easily edited along4×4texel boundaries, the limitations on subimage location and size are relaxed forTexSubImage2D,TexSubImage3D,CopyTexSubImage2D, and CopyTexSubImage3D. These commands will generate anINVALID OPERATION
error if one of the following conditions occurs:
• widthis not a multiple of four or equal to TEXTURE WIDTH, unlessxoffset
andyoffsetare both zero.
• heightis not a multiple of four or equal toTEXTURE HEIGHT, unlessxoffset
andyoffsetare both zero.
• 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.
Calling CopyTexSubImage3D, CopyTexImage2D, CopyTexSubIm- age2D, CopyTexImage1D, or CopyTexSubImage1D will result in
an INVALID FRAMEBUFFER OPERATION error if the object bound to
3.8. TEXTURING 135
Texture Copying Feedback Loops
Calling CopyTexSubImage3D, CopyTexImage2D, CopyTexSubImage2D, CopyTexImage1D, orCopyTexSubImage1Dwill result in undefined behavior if the destination texture image level is also bound to to the selected read buffer (see section4.3.1) of the read framebuffer. This situation is discussed in more detail in the description of feedback loops in section4.4.2.