The command
void TexImage2D ( enum target, int level, int internalformat, sizei width, sizei height, int border, enum format, enum type, void *data ) ;
is used to specify a two-dimensional texture image.
target must be either TEXTURE_2D,
or PROXY_TEXTURE_2D in the special case discussed in
section 3.8.3.
width, height, format, type, and *data
correspond precisely to the corresponding arguments to DrawPixels
(refer to section 3.6.3);
they specify the image's width and height,
a format of the image data,
the type of those data,
and a pointer to the image data in memory.
The image is taken from memory exactly as if these arguments
were passed to DrawPixels , but the process stops just before
final conversion. Each R, G, B, and A value so generated is clamped to 
.
(The formats STENCIL_INDEX and DEPTH_COMPONENT
are not allowed.)
Components are then selected from the resulting R, G, B, and A values
to obtain a texture with the base internal format specified by
(or derived from) internalformat.
Table 3.7 summarizes the mapping of R, G, B, and A values
to texture components,
as a function of the base internal format of the texture image.
internalformat may be specified as one of the six base internal format symbolic constants
listed in Table 3.7,
or it may be specified as any one of the sized internal format symbolic
constants listed in Table 3.8.
(For compatibility with the 1.0 version of the GL,
internalformat values 1, 2, 3, and 4 are equivalent to
symbolic constants LUMINANCE, LUMINANCE_ALPHA,
RGB, and RGBA respectively.)
Specifying a value for internalformat that is not a base internal format,
a sized internal format,
1, 2, 3, or 4
generates the error INVALID_VALUE.
(For compatibility with the 1.0 version of the GL,
parameter internalformat is type int,
not type enum.)
The internal component resolution is the number of bits allocated to each value in a texture image. If internalformat is specified as a base internal format, the GL stores the resulting texture with internal component resolutions of its own choosing. If a sized internal format is specified, the mapping of the R, G, B, and A values to texture components is equivalent to the mapping of the corresponding base internal format's components, as specified in Table 3.7, and the memory allocation per texture component is assigned by the GL to match the allocations listed in Table 3.8 as closely as possible. (The definition of closely is left up to the implementation. Implementations are not required to support more than one resolution for each base internal format.)
A GL implementation may vary its allocation of internal component resolution based on any TexImage1D (see below) or TexImage2D parameter (except target), but the allocation must not be a function of any other state, and cannot be changed once it is established. Allocations must be invariant; the same allocation must be made each time a texture image is specified with the same parameter values. These allocation rules also apply to proxy textures, which are described in section 3.8.3.
Table 3.7: Correspondence
of texture components to pixel group R, G, B, and A values.
See section 3.8.5 for a description of the texture components
R, G, B, A, L, and I.
Table 3.8: Correspondence of sized internal formats to base internal formats,
and desired component resolutions for each sized internal format.
The image itself (pointed to by *data) is a sequence of groups of values.
The first group is the lower left corner of the texture image.
Subsequent groups fill out rows of width width from left to right;
height rows are stacked from bottom to top.
Each color component is converted (by rounding to nearest) to a fixed-point
value with n bits,
where n is the number of bits of storage allocated to that component in
the image array.
We assume that the fixed-point representation used represents each value
, where 
, as
k (e.g. 1.0 is represented in binary as a string of all ones).
The level argument to TexImage2D is an integer level-of-detail number. Levels of detail are discussed below, under Mipmapping. The main texture image has a level of detail number of 0. If a level-of-detail less than zero is specified, the error INVALID_VALUE is generated.
The border argument to TexImage2D is a border width.
The significance of borders is described below.
The border width affects the required dimensions of the
texture image:
it must be the case that 
and 
,
where 
is the specified (non-negative) border width,
and 
and 
are the specified image width and height.
If width and height do not satisfy these relationships,
then the error INVALID_VALUE is generated.
Currently the maximum border width 
is 1.
If 
is less than zero,
or greater than 
,
then the error INVALID_VALUE is generated.
The maximum allowable width or height of an image
is an implementation dependent function of the level-of-detail
and internal format of the resulting image array.
It must be at least 
for image arrays of level-of-detail
0 through k,
where k is the log base 2 of MAX_TEXTURE_SIZE, lod is the level-of-detail of the image array,
and 
is the maximum border width.
It may be zero for image arrays of any level-of-detail greater than k.
The error INVALID_VALUE is generated
if the specified image is too large to be stored under any conditions.
Section 3.8.3 describes a query mechanism to determine the
maximum dimensions of a texture array of a specific level of detail
and internal format.
In order to allow the client to meaningfully query
the maximum image array sizes that are supported,
an implementation must not allow an image array of level one or greater
to be created if a complete set of image arrays
consistent with the requested array could not be supported.
The definition of a complete set of image arrays is provided below,
under Mipmapping.
Another command,
void TexImage1D ( enum target, int level, int internalformat, sizei width, int border, enum format, enum type, void *data ) ;
is used to specify one-dimensional texture images.
target must be either TEXTURE_1D or PROXY_TEXTURE_1D.
(It is TEXTURE_1D except in the special case discussed in
section 3.8.3.)
For the purposes of decoding the texture image,
TexImage1D is equivalent to calling TexImage2D with corresponding
arguments and height of 1,
except that the height
of the image is always 1, regardless of the value of
border.
It must be the case that 
for some integer n where 
is the value of border and 
is the value of width,
or the error INVALID_VALUE is generated.
An image with zero height or width (or zero width, for TexImage1D ) indicates the null texture. If the null texture is specified for level-of-detail zero, it is as if texturing were disabled.
The image indicated to the GL by the image pointer is decoded and copied into the GL's internal memory. This copying effectively places the decoded image inside a border of the maximum allowable width (currently 1) whether or not a border has been specified (see Figure 3.10). If no border or a border smaller than the maximum allowable width has been specified, then the image is still stored as if it were surrounded by a border of the maximum possible width. Any excess border (which surrounds the specified image, including any border) is assigned unspecified values. A one-dimensional texture has a border only at its left and right ends.
We shall refer to the (possibly border augmented) decoded image
as the texture array.
A two-dimensional texture array has width 
and height 
,
where 
is the maximum allowable border width;
a one-dimensional texture array has width 
and height 
.
An element 
of the texture array is called a texel
(for a 1-dimensional texture, j is irrelevant).
The texture value
used in texturing a fragment is determined by that
fragment's associated 
coordinates,
but may not correspond to any actual texel.
See Figure 3.10.
Figure 3.10: A texture image and the coordinates used to
access it. This is a two-dimensional texture with n=3 and m=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.
If the data argument of TexImage1D or TexImage2D is a null pointer (a zero-valued pointer in the C implementation), a one-dimensional or two-dimensional texture array is created with the specified target, level, internalformat, width, and height, but with unspecified image contents. In this case no pixel values are accessed in client memory, and no pixel processing is performed. Errors are generated, however, exactly as though the data pointer were valid.