'\" te
'\"! tbl|eqn | mmdoc
'\"macro stdmacro
.ds Vn Version 1.2
.ds Dt 24 September 1999
.ds Re Release 1.2.1
.ds Dp Jan 14 18:30
.ds Dm 01 texsubima
.ds Xs 43886 8 texsubimage1d.gl
.TH GLTEXSUBIMAGE1D 3G
.SH NAME
.B "glTexSubImage1D
\- specify a one-dimensional texture subimage

.SH C SPECIFICATION
void \f3glTexSubImage1D\fP(
GLenum \fItarget\fP,
.nf
.ta \w'\f3void \fPglTexSubImage1D( 'u
	GLint \fIlevel\fP,
	GLint \fIxoffset\fP,
	GLsizei \fIwidth\fP,
	GLenum \fIformat\fP,
	GLenum \fItype\fP,
	const GLvoid \fI*pixels\fP )
.fi

.EQ
delim $$
.EN
.SH PARAMETERS
.TP \w'\fIxoffset\fP\ \ 'u 
\f2target\fP
Specifies the target texture.
Must be \%\f3GL_TEXTURE_1D\fP.
.TP
\f2level\fP
Specifies the level-of-detail number.
Level 0 is the base image level.
Level \f2n\fP is the \f2n\fPth mipmap reduction image.
.TP
\f2xoffset\fP
Specifies a texel offset in the x direction within the texture array.
.TP
\f2width\fP
Specifies the width of the texture subimage.
.TP
\f2format\fP
Specifies the  of the pixel data.
The following symbolic values are accepted:
\%\f3GL_COLOR_INDEX\fP,
\%\f3GL_RED\fP,
\%\f3GL_GREEN\fP,
\%\f3GL_BLUE\fP,
\%\f3GL_ALPHA\fP,
\%\f3GL_RGB\fP,
\%\f3GL_BGR\fP,
\%\f3GL_RGBA\fP,
\%\f3GL_BGRA\fP,
\%\f3GL_LUMINANCE\fP, and
\%\f3GL_LUMINANCE_ALPHA\fP.
.TP
\f2type\fP
Specifies the data type of the pixel data.
The following symbolic values are accepted:
\%\f3GL_UNSIGNED_BYTE\fP,
\%\f3GL_BYTE\fP,
\%\f3GL_BITMAP\fP,
\%\f3GL_UNSIGNED_SHORT\fP,
\%\f3GL_SHORT\fP,
\%\f3GL_UNSIGNED_INT\fP,
\%\f3GL_INT\fP, 
\%\f3GL_FLOAT\fP,
\%\f3GL_UNSIGNED_BYTE_3_3_2\fP,
\%\f3GL_UNSIGNED_BYTE_2_3_3_REV\fP,
\%\f3GL_UNSIGNED_SHORT_5_6_5\fP,
\%\f3GL_UNSIGNED_SHORT_5_6_5_REV\fP,
\%\f3GL_UNSIGNED_SHORT_4_4_4_4\fP,
\%\f3GL_UNSIGNED_SHORT_4_4_4_4_REV\fP,
\%\f3GL_UNSIGNED_SHORT_5_5_5_1\fP,
\%\f3GL_UNSIGNED_SHORT_1_5_5_5_REV\fP,
\%\f3GL_UNSIGNED_INT_8_8_8_8\fP,
\%\f3GL_UNSIGNED_INT_8_8_8_8_REV\fP,
\%\f3GL_UNSIGNED_INT_10_10_10_2\fP, and
\%\f3GL_UNSIGNED_INT_2_10_10_10_REV\fP.
.TP
\f2pixels\fP
Specifies a pointer to the image data in memory.
.SH DESCRIPTION
Texturing maps a portion of a specified texture image
onto each graphical primitive for which texturing is enabled.
To enable or disable one-dimensional texturing, call \%\f3glEnable\fP
and \%\f3glDisable\fP with argument \%\f3GL_TEXTURE_1D\fP.
.P
\%\f3glTexSubImage1D\fP redefines a contiguous subregion of an existing one-dimensional
texture image.
The texels referenced by \f2pixels\fP replace the portion of the
existing texture array with x indices \f2xoffset\fP and
$"xoffset"~+~"width"~-~1$,inclusive.
This region may not include any texels outside the range of the
texture array as it was originally specified.
It is not an error to specify a subtexture with width of 0, but
such a specification has no effect.
.SH NOTES
\%\f3glTexSubImage1D\fP is available only if the GL version is 1.1 or greater.
.P
Texturing has no effect in color index mode.
.P
\%\f3glPixelStore\fP and \%\f3glPixelTransfer\fP modes affect texture images
in exactly the way they affect \%\f3glDrawPixels\fP.
.P
Formats \%\f3GL_BGR\fP, and \%\f3GL_BGRA\fP and types
\%\f3GL_UNSIGNED_BYTE_3_3_2\fP,
\%\f3GL_UNSIGNED_BYTE_2_3_3_REV\fP,
\%\f3GL_UNSIGNED_SHORT_5_6_5\fP,
\%\f3GL_UNSIGNED_SHORT_5_6_5_REV\fP,
\%\f3GL_UNSIGNED_SHORT_4_4_4_4\fP,
\%\f3GL_UNSIGNED_SHORT_4_4_4_4_REV\fP,
\%\f3GL_UNSIGNED_SHORT_5_5_5_1\fP,
\%\f3GL_UNSIGNED_SHORT_1_5_5_5_REV\fP,
\%\f3GL_UNSIGNED_INT_8_8_8_8\fP,
\%\f3GL_UNSIGNED_INT_8_8_8_8_REV\fP,
\%\f3GL_UNSIGNED_INT_10_10_10_2\fP, and
\%\f3GL_UNSIGNED_INT_2_10_10_10_REV\fP are available only if the GL version 
is 1.2 or greater.
.P
When the \%\f3GL_ARB_multitexture\fP extension is supported, \%\f3glTexSubImage1D\fP
specifies a one-dimensional sub texture for the current texture unit,
specified with \%\f3glActiveTextureARB\fP.
.P
When the \%\f3GL_ARB_imaging\fP extension is supported, the RGBA components
specified in \f2pixels\fP may be processed by the imaging pipeline.  See
\%\f3glTexImage1D\fP for specific details.
.SH ERRORS
\%\f3GL_INVALID_ENUM\fP is generated if \f2target\fP is not one of the
allowable values.
.P
\%\f3GL_INVALID_OPERATION\fP is generated if the texture array has not
been defined by a previous \%\f3glTexImage1D\fP operation.
.P
\%\f3GL_INVALID_VALUE\fP is generated if \f2level\fP is less than 0.
.P 
\%\f3GL_INVALID_VALUE\fP may be generated if \f2level\fP is greater
than $log sub 2$\f2max\fP,
where \f2max\fP is the returned value of \%\f3GL_MAX_TEXTURE_SIZE\fP.
.P
\%\f3GL_INVALID_VALUE\fP is generated if $"xoffset" ~<~ ~-b$,
or if $("xoffset"~+~"width") ~>~ (w ~-~ b)$, 
where $w$ is the \%\f3GL_TEXTURE_WIDTH\fP, and $b$ is 
the width of the \%\f3GL_TEXTURE_BORDER\fP 
of the texture image being modified.
Note that $w$ includes twice the border width.
.P
\%\f3GL_INVALID_VALUE\fP is generated if \f2width\fP is less than 0.
.P
\%\f3GL_INVALID_ENUM\fP is generated if \f2format\fP is not an accepted
 constant.
.P
\%\f3GL_INVALID_ENUM\fP is generated if \f2type\fP is not a type constant.
.P
\%\f3GL_INVALID_ENUM\fP is generated if \f2type\fP is \%\f3GL_BITMAP\fP and
\f2format\fP is not \%\f3GL_COLOR_INDEX\fP.
.P
\%\f3GL_INVALID_OPERATION\fP is generated if \%\f3glTexSubImage1D\fP is executed
between the execution of \%\f3glBegin\fP and the corresponding
execution of \%\f3glEnd\fP.
.P
\%\f3GL_INVALID_OPERATION\fP is generated if \f2type\fP is one of
\%\f3GL_UNSIGNED_BYTE_3_3_2\fP,
\%\f3GL_UNSIGNED_BYTE_2_3_3_REV\fP,
\%\f3GL_UNSIGNED_SHORT_5_6_5\fP, or
\%\f3GL_UNSIGNED_SHORT_5_6_5_REV\fP
and \f2format\fP is not \%\f3GL_RGB\fP.
.P
\%\f3GL_INVALID_OPERATION\fP is generated if \f2type\fP is one of
\%\f3GL_UNSIGNED_SHORT_4_4_4_4\fP,
\%\f3GL_UNSIGNED_SHORT_4_4_4_4_REV\fP,
\%\f3GL_UNSIGNED_SHORT_5_5_5_1\fP,
\%\f3GL_UNSIGNED_SHORT_1_5_5_5_REV\fP,
\%\f3GL_UNSIGNED_INT_8_8_8_8\fP,
\%\f3GL_UNSIGNED_INT_8_8_8_8_REV\fP,
\%\f3GL_UNSIGNED_INT_10_10_10_2\fP, or
\%\f3GL_UNSIGNED_INT_2_10_10_10_REV\fP
and \f2format\fP is neither \%\f3GL_RGBA\fP nor \%\f3GL_BGRA\fP.
.SH ASSOCIATED GETS
\%\f3glGetTexImage\fP
.br
\%\f3glIsEnabled\fP with argument \%\f3GL_TEXTURE_1D\fP
.SH SEE ALSO
\%\f3glActiveTextureARB(3G)\fP,
\%\f3glCopyTexImage1D(3G)\fP,
\%\f3glCopyTexImage2D(3G)\fP,
\%\f3glCopyTexSubImage1D(3G)\fP,
\%\f3glCopyTexSubImage2D(3G)\fP,
\%\f3glCopyTexSubImage3D(3G)\fP,
\%\f3glDrawPixels(3G)\fP,
\%\f3glPixelStore(3G)\fP,
\%\f3glPixelTransfer(3G)\fP,
\%\f3glTexEnv(3G)\fP,
\%\f3glTexGen(3G)\fP,
\%\f3glTexImage1D(3G)\fP,
\%\f3glTexImage2D(3G)\fP,
\%\f3glTexImage3D(3G)\fP,
\%\f3glTexParameter(3G)\fP,
\%\f3glTexSubImage2D(3G)\fP,
\%\f3glTexSubImage3D(3G)\fP