glTexImage1D.3gl

OpenGL man pages

glTexImage1D.3gl

Name

  glTexImage1D - specify a one-dimensional texture image

C Specification

  void glTexImage1D( GLenum target,
		     GLint level,
		     GLint components,
		     GLsizei width,
		     GLint border,
		     GLenum format,
		     GLenum type,
		     const GLvoid *pixels )

Parameters


  target      Specifies	the target texture.  Must be GL_TEXTURE_1D.

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

  components  Specifies	the number of color components in the texture.	Must
	      be 1, 2, 3, or 4.

                                                                  n
  width	      Specifies	the width of the texture image.	 Must be 2 +2(border)
	      for some integer n.  The height of the texture image is 1.

  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.  One-dimensional texturing is
  enabled and disabled using glEnable and glDisable with argument
  GL_TEXTURE_1D.

  Texture images are defined with glTexImage1D.	 The arguments describe	the
  parameters of	the texture image, such	as width, width	of the border,
  level-of-detail number (see glTexParameter), and number of color components
  provided.  The last three arguments describe the way the image is
  represented in memory, and they are identical	to the pixel formats used for
  glDrawPixels.

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

  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. It is converted 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. It is converted to
	    floating point and assembled into an RGBA element by attaching
	    0.0	for green and blue, and	1.0 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_GREEN  Each element is a single green component. It is converted to
	    floating point and assembled into an RGBA element by attaching
	    0.0	for red	and blue, and 1.0 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_BLUE   Each element is a single blue component. It	is converted to
	    floating point and assembled into an RGBA element by attaching
	    0.0	for red	and green, and 1.0 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_ALPHA  Each element is a single alpha component. It is converted to
	    floating point and assembled into an RGBA element by attaching
	    0.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.  It is converted to floating	point
	    and	assembled into an RGBA element by attaching 1.0	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 is a complete RGBA element.  It is converted to
	    floating point.  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
	    Each element is a single luminance value.  It is converted to
	    floating point, then assembled into	an RGBA	element	by
	    replicating	the luminance value three times	for red, green,	and
	    blue and attaching 1.0 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.  It	is converted to
	    floating point, then assembled 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).

  A texture image can have up to four components per texture element,
  depending on components.  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 glDrawPixels.

  A texture image with zero width indicates the	null texture.  If the null
  texture is specified for level-of-detail 0, it is as if texturing were
  disabled.

Errors

  GL_INVALID_ENUM is generated when target is not GL_TEXTURE_1D.

  GL_INVALID_ENUM is generated when 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 when 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 zero or greater than
  log max, where max is	the returned value of GL_MAX_TEXTURE_SIZE.
     2
  GL_INVALID_VALUE is generated	if components is not 1, 2, 3, or 4.

  GL_INVALID_VALUE is generated	if width is less than zero or greater than
                                                              n
  2 + GL_MAX_TEXTURE_SIZE, or if it cannot be represented as 2 +2(border) for
  some integer value of	n.

  GL_INVALID_VALUE is generated	if border is not 0 or 1.

  GL_INVALID_OPERATION is generated if glTexImage1D is executed	between	the
  execution of glBegin and the corresponding execution of glEnd.

Associated Gets

  glGetTexImage
  glIsEnabled with argument GL_TEXTURE_1D

glTexImage1D.3gl

glTexImage1D.3gl

Name

C Specification

Parameters

Description

Notes

Errors

Associated Gets

See Also