NAME
	  fglTexImage2D	- specify a two-dimensional texture image


     FORTRAN SPECIFICATION
	  SUBROUTINE fglTexImage2D( INTEGER*4 target,
				    INTEGER*4 level,
				    INTEGER*4 internalformat,
				    INTEGER*4 width,
				    INTEGER*4 height,
				    INTEGER*4 border,
				    INTEGER*4 format,
				    INTEGER*4 type,
				    CHARACTER*8	pixels )


     PARAMETERS
	  target	  Specifies the	target texture.	 Must be
			  GL_TEXTURE_2D	or GL_PROXY_TEXTURE_2D.

	  level		  Specifies the	level-of-detail	number.	 Level
			  0 is the base	image level.  Level n is the
			  nth mipmap reduction image.

	  internalformat  Specifies the	number of color	components in
			  the texture.	Must be	1, 2, 3, or 4, or one
			  of the following symbolic constants:
			  GL_ALPHA, GL_ALPHA4, GL_ALPHA8, GL_ALPHA12,
			  GL_ALPHA16, GL_LUMINANCE, GL_LUMINANCE4,
			  GL_LUMINANCE8, GL_LUMINANCE12,
			  GL_LUMINANCE16, GL_LUMINANCE_ALPHA,
			  GL_LUMINANCE4_ALPHA4,	GL_LUMINANCE6_ALPHA2,
			  GL_LUMINANCE8_ALPHA8,	GL_LUMINANCE12_ALPHA4,
			  GL_LUMINANCE12_ALPHA12,
			  GL_LUMINANCE16_ALPHA16, GL_INTENSITY,
			  GL_INTENSITY4, GL_INTENSITY8,
			  GL_INTENSITY12, GL_INTENSITY16, GL_R3_G3_B2,
			  GL_RGB, GL_RGB4, GL_RGB5, GL_RGB8, GL_RGB10,
			  GL_RGB12, GL_RGB16, GL_RGBA, GL_RGBA2,
			  GL_RGBA4, GL_RGB5_A1,	GL_RGBA8, GL_RGB10_A2,
			  GL_RGBA12, or	GL_RGBA16.

	  width		  Specifies the	width of the texture image.
			  Must be 2n+2(border) for some	integer	n. All
			  implementations support texture images that
			  are at least 64 texels wide.

	  height	  Specifies the	height of the texture image.
			  Must be 2m+2(border) for some	integer	m. All
			  implementations support texture images that
			  are at least 64 texels high.

	  border	  Specifies the	width of the border.  Must be
			  either 0 or 1.

	  format	  Specifies the	format of the pixel data.  The
			  following symbolic values are	accepted:
			  GL_COLOR_INDEX, GL_RED, GL_GREEN, GL_BLUE,
			  GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE, and
			  GL_LUMINANCE_ALPHA.

	  type		  Specifies the	data type of the pixel data.
			  The following	symbolic values	are accepted:
			  GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP,
			  GL_UNSIGNED_SHORT, GL_SHORT,
			  GL_UNSIGNED_INT, GL_INT, and GL_FLOAT.

	  pixels	  Specifies a pointer to the image data	in
			  memory.

     DESCRIPTION
	  Texturing maps a portion of a	specified texture image	onto
	  each graphical primitive for which texturing is enabled.  To
	  enable and disable two-dimensional texturing,	call fglEnable
	  and fglDisable with argument GL_TEXTURE_2D.

	  To define texture images, call fglTexImage2D.	The arguments
	  describe the parameters of the texture image,	such as
	  height, width, width of the border, level-of-detail number
	  (see fglTexParameter), and number of color components
	  provided.  The last three arguments describe how the image
	  is represented in memory; they are identical to the pixel
	  formats used for fglDrawPixels.

	  If target is GL_PROXY_TEXTURE_2D, no data is read from
	  pixels, but all of the texture image state is	recalculated,
	  checked for consistency, and checked against the
	  implementation's capabilities. If the	implementation cannot
	  handle a texture of the requested texture size, it sets all
	  of the image state to	0, but does not	generate an error (see
	  fglGetError).	To query for an	entire mipmap array, use an
	  image	array level greater than or equal to 1.

	  If target is GL_TEXTURE_2D, data is read from	pixels as a
	  sequence of signed or	unsigned bytes,	shorts,	or longs, or
	  single-precision floating-point values, depending on type.
	  These	values are grouped into	sets of	one, two, three, or
	  four values, depending on format, to form elements. If type
	  is GL_BITMAP,	the data is considered as a string of unsigned
	  bytes	(and format must be GL_COLOR_INDEX). Each data byte is
	  treated as eight 1-bit elements, with	bit ordering
	  determined by	GL_UNPACK_LSB_FIRST (see fglPixelStore).

	  The first element corresponds	to the lower left corner of
	  the texture image.  Subsequent elements progress left-to-
	  right	through	the remaining texels in	the lowest row of the
	  texture image, and then in successively higher rows of the
	  texture image.  The final element corresponds	to the upper
	  right	corner of the texture image.

	  format determines the	composition of each element in pixels.
	  It can assume	one of nine symbolic values:

	  GL_COLOR_INDEX
		    Each element is a single value, a color index. The
		    GL converts	it to fixed point (with	an unspecified
		    number of zero bits	to the right of	the binary
		    point), shifted left or right depending on the
		    value and sign of GL_INDEX_SHIFT, and added	to
		    GL_INDEX_OFFSET (see
		    fglPixelTransfer). The resulting index is
		    converted to a set of color	components using the
		    GL_PIXEL_MAP_I_TO_R, GL_PIXEL_MAP_I_TO_G,
		    GL_PIXEL_MAP_I_TO_B, and GL_PIXEL_MAP_I_TO_A
		    tables, and	clamped	to the range [0,1].

	  GL_RED    Each element is a single red component. The	GL
		    converts it	to floating point and assembles	it
		    into an RGBA element by attaching 0	for green and
		    blue, and 1	for alpha. Each	component is then
		    multiplied by the signed scale factor GL_c_SCALE,
		    added to the signed	bias GL_c_BIAS,	and clamped to
		    the	range [0,1] (see fglPixelTransfer).

	  GL_GREEN  Each element is a single green component. The GL
		    converts it	to floating point and assembles	it
		    into an RGBA element by attaching 0	for red	and
		    blue, and 1	for alpha. Each	component is then
		    multiplied by the signed scale factor GL_c_SCALE,
		    added to the signed	bias GL_c_BIAS,	and clamped to
		    the	range [0,1] (see fglPixelTransfer).

	  GL_BLUE   Each element is a single blue component. The GL
		    converts it	to floating point and assembles	it
		    into an RGBA element by attaching 0	for red	and
		    green, and 1 for alpha. Each component is then
		    multiplied by the signed scale factor GL_c_SCALE,
		    added to the signed	bias GL_c_BIAS,	and clamped to
		    the	range [0,1] (see fglPixelTransfer).

	  GL_ALPHA  Each element is a single alpha component. The GL
		    converts it	to floating point and assembles	it
		    into an RGBA element by attaching 0	for red,
		    green, and blue.  Each component is	then
		    multiplied by the signed scale factor GL_c_SCALE,
		    added to the signed	bias GL_c_BIAS,	and clamped to
		    the	range [0,1] (see fglPixelTransfer).

	  GL_RGB    Each element is an RGB triple.  The	GL converts it
		    to floating	point and assembles it into an RGBA
		    element by attaching 1 for alpha.  Each component
		    is then multiplied by the signed scale factor
		    GL_c_SCALE,	added to the signed bias GL_c_BIAS,
		    and	clamped	to the range [0,1] (see
		    fglPixelTransfer).

	  GL_RGBA   Each element contains all four components.	Each
		    component is multiplied by the signed scale	factor
		    GL_c_SCALE,	added to the signed bias GL_c_BIAS,
		    and	clamped	to the range [0,1] (see
		    fglPixelTransfer).

	  GL_LUMINANCE
		    Each element is a single luminance value.  The GL
		    converts it	to floating point, then	assembles it
		    into an RGBA element by replicating	the luminance
		    value three	times for red, green, and blue and
		    attaching 1	for alpha. Each	component is then
		    multiplied by the signed scale factor GL_c_SCALE,
		    added to the signed	bias GL_c_BIAS,	and clamped to
		    the	range [0,1] (see fglPixelTransfer).

	  GL_LUMINANCE_ALPHA
		    Each element is a luminance/alpha pair.  The GL
		    converts it	to floating point, then	assembles it
		    into an RGBA element by replicating	the luminance
		    value three	times for red, green, and blue.	 Each
		    component is then multiplied by the	signed scale
		    factor GL_c_SCALE, added to	the signed bias
		    GL_c_BIAS, and clamped to the range	[0,1] (see
		    fglPixelTransfer).

	  Refer	to the fglDrawPixels reference page for	a description
	  of the acceptable values for the type	parameter.

	  If an	application wants to store the texture at a certain
	  resolution or	in a certain format, it	can request the
	  resolution and format	with internalformat. The GL will
	  choose an internal representation that closely approximates
	  that requested by internalformat, but	it may not match
	  exactly.  (The representations specified by GL_LUMINANCE,
	  GL_LUMINANCE_ALPHA, GL_RGB, and GL_RGBA must match exactly.
	  The numeric values 1,	2, 3, and 4 may	also be	used to
	  specify the above representations.)

	  Use the GL_PROXY_TEXTURE_2D target to	try out	a resolution
	  and format. The implementation will update and recompute its
	  best match for the requested storage resolution and format.
	  To then query	this state, call fglGetTexLevelParameter.  If
	  the texture cannot be	accommodated, texture state is set to
	  0.

	  A one-component texture image	uses only the red component of
	  the RGBA color extracted from	pixels.	A two-component	image
	  uses the R and A values.  A three-component image uses the
	  R, G,	and B values.  A four-component	image uses all of the
	  RGBA components.

     NOTES
	  Texturing has	no effect in color index mode.

	  The texture image can	be represented by the same data
	  formats as the pixels	in a fglDrawPixels command, except
	  that GL_STENCIL_INDEX	and GL_DEPTH_COMPONENT cannot be used.
	  fglPixelStore	and fglPixelTransfer modes affect texture
	  images in exactly the	way they affect	fglDrawPixels.

	  fglTexImage2D	and GL_PROXY_TEXTURE_2D	are only available if
	  the GL version is 1.1	or greater.

	  Internal formats other than 1, 2, 3, or 4 may	only be	used
	  if the GL version is 1.1 or greater.

	  In GL	version	1.1 or greater,	pixels may be a	null pointer.
	  In this case texture memory is allocated to accommodate a
	  texture of width width and height height.  You can then
	  download subtextures to initialize this texture memory. The
	  image	is undefined if	the user tries to apply	an
	  uninitialized	portion	of the texture image to	a primitive.

     ERRORS
	  GL_INVALID_ENUM is generated if target is not	GL_TEXTURE_2D
	  or GL_PROXY_TEXTURE_2D.

	  GL_INVALID_ENUM is generated if format is not	an accepted
	  format constant.  Format constants other than
	  GL_STENCIL_INDEX and GL_DEPTH_COMPONENT are accepted.

	  GL_INVALID_ENUM is generated if type is not a	type constant.

	  GL_INVALID_ENUM is generated if type is GL_BITMAP and	format
	  is not GL_COLOR_INDEX.

	  GL_INVALID_VALUE is generated	if level is less than 0.

	  GL_INVALID_VALUE may be generated if level is	greater	than
	  log max, where max is	the returned value of
	  GL_MAX_TEXTURE_SIZE.

	  GL_INVALID_VALUE is generated	if internalformat is not 1, 2,
	  3, 4,	or one of the accepted resolution and format symbolic
	  constants.

	  GL_INVALID_VALUE is generated	if width or height is less
	  than 0 or greater than 2 + GL_MAX_TEXTURE_SIZE, or if	either
	  cannot be represented	as 2k+2(border)	for some integer value
	  of k.

	  GL_INVALID_VALUE is generated	if border is not 0 or 1.

	  GL_INVALID_OPERATION is generated if fglTexImage2D is
	  executed between the execution of fglBegin and the
	  corresponding	execution of fglEnd.

     ASSOCIATED	GETS
	  fglGetTexImage
	  fglIsEnabled with argument GL_TEXTURE_2D

     SEE ALSO
	  fglCopyPixels, fglCopyTexImage1D, fglCopyTexImage2D,
	  fglCopyTexSubImage1D,	fglCopyTexSubImage2D, fglDrawPixels,
	  fglPixelStore, fglPixelTransfer, fglTexEnv, fglTexGen,
	  fglTexImage1D, fglTexSubImage1D, fglTexSubImage2D,
	  fglTexParameter