Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GLTEXIMAGE2D()							GLTEXIMAGE2D()

NAME
       glTexImage2D - specify a	two-dimensional	texture	image

C SPECIFICATION
       void glTexImage2D( GLenum target,
			  GLint	level,
			  GLint	internalformat,
			  GLsizei width,
			  GLsizei height,
			  GLint	border,
			  GLenum format,
			  GLenum type,
			  const	GLvoid *pixels )

       delim $$

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  tex-
		       ture.   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_LUMI-
		       NANCE_ALPHA,   GL_LUMINANCE4_ALPHA4,  GL_LUMINANCE6_AL-
		       PHA2,   GL_LUMINANCE8_ALPHA8,	GL_LUMINANCE12_ALPHA4,
		       GL_LUMINANCE12_ALPHA12,	GL_LUMINANCE16_ALPHA16,	GL_IN-
		       TENSITY,	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  $2
		       sup  n  + 2 ( "border" )$ for some integer $n$. All im-
		       plementations support texture images that are at	 least
		       64 texels wide.

       height	       Specifies  the height of	the texture image.  Must be $2
		       sup m + 2 ( "border" )$ for some	integer	$m$.  All  im-
		       plementations  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_LUMI-
		       NANCE, and GL_LUMINANCE_ALPHA.

       type	       Specifies the data type of the pixel data.  The follow-
		       ing  symbolic  values  are  accepted: GL_UNSIGNED_BYTE,
		       GL_BYTE,	GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT,	GL_UN-
		       SIGNED_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 graphi-
       cal primitive for which texturing is enabled.  To  enable  and  disable
       two-dimensional	texturing,  call  glEnable and glDisable with argument
       GL_TEXTURE_2D.

       To define texture images, call glTexImage2D.   The  arguments  describe
       the  parameters	of  the	texture	image, such as height, width, width of
       the border, level-of-detail number (see glTexParameter),	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	glDrawPixels.

       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 implemen-
       tation 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
       glGetError). 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	float-
       ing-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_UN-
       PACK_LSB_FIRST (see glPixelStore).

       The first element corresponds to	the lower left corner of  the  texture
       image.	Subsequent elements progress left-to-right through the remain-
       ing texels in the lowest	row of the texture image, and then in  succes-
       sively 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 con-
		 verts 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
		 glPixelTransfer).   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	compo-
		 nent	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 glPixelTransfer).

       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	compo-
		 nent  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 glPixelTransfer).

       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	compo-
		 nent	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 glPixelTransfer).

       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 glPixelTransfer).

       GL_RGB	 Each element is an RGB	triple.	 The GL	converts it to	float-
		 ing  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
		 glPixelTransfer).

       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 glPixelTransfer).

       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 glPixelTransfer).

       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
		 glPixelTransfer).

       Refer to	the glDrawPixels reference page	for a description of  the  ac-
       ceptable	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  in-
       ternalformat.  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_LU-
       MINANCE_ALPHA, GL_RGB, and GL_RGBA must match exactly. The numeric val-
       ues  1,	2,  3, and 4 may also be used to specify the above representa-
       tions.)

       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 re-
       quested storage resolution and format. To then query this  state,  call
       glGetTexLevelParameter.	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 glDrawPixels	 command,  except  that	 GL_STENCIL_INDEX  and
       GL_DEPTH_COMPONENT  cannot  be  used.  glPixelStore and glPixelTransfer
       modes affect texture images in exactly the way they  affect  glDrawPix-
       els.

       glTexImage2D  and GL_PROXY_TEXTURE_2D are only available	if the GL ver-
       sion 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 initial-
       ize 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  con-
       stant.	Format constants other than GL_STENCIL_INDEX and GL_DEPTH_COM-
       PONENT 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 sub
       2$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	repre-
       sented as $2 sup	k + 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 glTexImage2D is executed between
       the execution of	glBegin	and the	corresponding execution	of glEnd.

ASSOCIATED GETS
       glGetTexImage
       glIsEnabled with	argument GL_TEXTURE_2D

SEE ALSO
       glCopyPixels, glCopyTexImage1D, glCopyTexImage2D,  glCopyTexSubImage1D,
       glCopyTexSubImage2D,  glDrawPixels,  glPixelStore, glPixelTransfer, gl-
       TexEnv, glTexGen, glTexImage1D, glTexSubImage1D,	glTexSubImage2D,
       glTexParameter

								GLTEXIMAGE2D()

NAME | C SPECIFICATION | PARAMETERS | DESCRIPTION | NOTES | ERRORS | ASSOCIATED GETS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=glTexImage2D&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help