glGetTexImage.3gl

Name

  glGetTexImage	- return a texture image

C Specification

  void glGetTexImage( GLenum target,
		      GLint level,
		      GLenum format,
		      GLenum type,
		      GLvoid *pixels )

Parameters

  target  Specifies which texture is to	be obtained.  GL_TEXTURE_1D and
	  GL_TEXTURE_2D	are accepted.

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

  format  Specifies a pixel format for the returned data.  The supported
	  formats are GL_RED, GL_GREEN,	GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA,
	  GL_LUMINANCE,	and GL_LUMINANCE_ALPHA.

  type	  Specifies a pixel type for the returned data.	 The supported types
	  are GL_UNSIGNED_BYTE,	GL_BYTE, GL_UNSIGNED_SHORT, GL_SHORT,
	  GL_UNSIGNED_INT, GL_INT, and GL_FLOAT.

  pixels  Returns the texture image.  Should be	a pointer to an	array of the
	  type specified by type.

Description

  glGetTexImage	returns	a texture image	into pixels.  target specifies
  whether the desired texture image is one specified by	glTexImage1D
  (GL_TEXTURE_1D) or by	glTexImage2D (GL_TEXTURE_2D).  level specifies the
  level-of-detail number of the	desired	image.	format and type	specify	the
  format and type of the desired image array.  Please see the reference	pages
  glTexImage1D and glDrawPixels	for a description of the acceptable values
  for the format and type parameters, respectively.

  Operation of glGetTexImage is	best understood	by considering the selected
  internal four-component texture image	to be an RGBA color buffer the size
  of the image.	 The semantics of glGetTexImage	are then identical to those
  of glReadPixels called with the same format and type,	with x and y set to
  zero,	width set to the width of the texture image (including border if one
  was specified), and height set to one	for 1-D	images,	or to the height of
  the texture image (including border if one was specified) for	2-D images.
  Because the internal texture image is	an RGBA	image, pixel formats
  GL_COLOR_INDEX, GL_STENCIL_INDEX, and	GL_DEPTH_COMPONENT are not accepted,
  and pixel type GL_BITMAP is not accepted.

  If the selected texture image	does not contain four components, the
  following mappings are applied.  Single-component textures are treated as
  RGBA buffers with red	set to the single-component value, and green, blue,
  and alpha set	to zero.  Two-component	textures are treated as	RGBA buffers
  with red set to the value of component zero, alpha set to the	value of
  component one, and green and blue set	to zero.  Finally, three-component
  textures are treated as RGBA buffers with red	set to component zero, green
  set to component one,	blue set to component two, and alpha set to zero.

  To determine the required size of pixels, use	glGetTexLevelParameter to
  ascertain the	dimensions of the internal texture image, then scale the
  required number of pixels by the storage required for	each pixel, based on
  format and type.  Be sure to take the	pixel storage parameters into
  account, especially GL_PACK_ALIGNMENT.

Notes

  If an	error is generated, no change is made to the contents of pixels.

Errors

  GL_INVALID_ENUM is generated if target, format, or type is not an accepted
  value.

  GL_INVALID_VALUE is generated	if level is less than zero or greater than
  log max, where max is	the returned value of GL_MAX_TEXTURE_SIZE.
     2
  GL_INVALID_OPERATION is generated if glGetTexImage is	executed between the
  execution of glBegin and the corresponding execution of glEnd.

Associated Gets

  glGetTexLevelParameter with argument GL_TEXTURE_WIDTH
  glGetTexLevelParameter with argument GL_TEXTURE_HEIGHT
  glGetTexLevelParameter with argument GL_TEXTURE_BORDER
  glGetTexLevelParameter with argument GL_TEXTURE_COMPONENTS
  glGet	with arguments GL_PACK_ALIGNMENT and others

See Also

  glDrawPixels,	glReadPixels, glTexImage1D, glTexImage2D

Introduction | Alphabetic | Specification

Last Edited: Fri Dec 6 11:18:03 EST 1996 by AFV
Look here for legal stuff: Legal