*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> OpenGL/glteximage3d (3)              
Title
Content
Arch
Section
 

Contents


glTexImage3D(3G)	       OpenGL Reference		      glTexImage3D(3G)


NAME    [Toc]    [Back]

     glTexImage3D - specify a three-dimensional	texture	image

C SPECIFICATION    [Toc]    [Back]

     void glTexImage3D(	GLenum target,
			GLint level,
			GLenum internalformat,
			GLsizei	width,
			GLsizei	height,
			GLsizei	depth,
			GLint border,
			GLenum format,
			GLenum type,
			const GLvoid *pixels )

PARAMETERS    [Toc]    [Back]

     target	     Specifies the target texture.  Must be GL_TEXTURE_3D or
		     GL_PROXY_TEXTURE_3D.

     level	     Specifies the level-of-detail number.  Level 0 is the
							th
		     base image	level.	Level n	is the n   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
		      n
		     2	+ 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
		      m
		     2	+ 2(border) for	some integer m.	All implementations
		     support texture images that are at	least 64 texels	high.

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





									Page 1






glTexImage3D(3G)	       OpenGL Reference		      glTexImage3D(3G)



     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_BGR, GL_RGBA,
		     GL_BGRA, GL_ABGR_EXT, 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, GL_FLOAT GL_UNSIGNED_BYTE_3_3_2,
		     GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5,
		     GL_UNSIGNED_SHORT_5_6_5_REV, GL_UNSIGNED_SHORT_4_4_4_4,
		     GL_UNSIGNED_SHORT_4_4_4_4_REV, GL_UNSIGNED_SHORT_5_5_5_1,
		     GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8,
		     GL_UNSIGNED_INT_8_8_8_8_REV, GL_UNSIGNED_INT_10_10_10_2,
		     and GL_UNSIGNED_INT_2_10_10_10_REV.

     pixels	     Specifies a pointer to the	image data in memory.

DESCRIPTION    [Toc]    [Back]

     Texturing maps a portion of a specified texture image onto	each graphical
     primitive for which texturing is enabled.	To enable and disable threedimensional
 texturing, call glEnable and glDisable	with argument
     GL_TEXTURE_3D.

     To	define texture images, call glTexImage3D. The arguments	describe the
     parameters	of the texture image, such as height, width, depth, 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_3D, 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 glGetError).	To
     query for an entire mipmap	array, use an image array level	greater	than
     or	equal to 1.

     If	target is GL_TEXTURE_3D, 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).




									Page 2






glTexImage3D(3G)	       OpenGL Reference		      glTexImage3D(3G)



     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 eleven symbolic values:

     GL_COLOR_INDEX    [Toc]    [Back]
	       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 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 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. 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 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 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. 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    [Toc]    [Back]

     GL_BGR    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



									Page 3






glTexImage3D(3G)	       OpenGL Reference		      glTexImage3D(3G)



	       factor GL_c_SCALE, added	to the signed bias GL_c_BIAS, and
	       clamped to the range [0,1] (see glPixelTransfer).

     GL_RGBA    [Toc]    [Back]

     GL_BGRA    [Toc]    [Back]

     GL_ABGR_EXT    [Toc]    [Back]
	       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    [Toc]    [Back]
	       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    [Toc]    [Back]
	       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
     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_3D 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
     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 fourcomponent
 image uses all of the RGBA components.



									Page 4






glTexImage3D(3G)	       OpenGL Reference		      glTexImage3D(3G)



     Normally glTexImage3D is synchronous: OpenGL executes a glTexImage3D
     command in	the order it is	issued in the OpenGL command stream.  Calling
     glEnable with parameter GL_ASYNC_TEX_IMAGE_SGIX causes subsequent
     glTexImage3D commands to be asynchronous as defined by the	SGIX_async
     extension.	 An asynchronous glTexImage3D command samples the OpenGL state
     vector at the point in the	OpenGL command stream where the	command	is
     issued, but the results of	the command (e.g. availability of texels for
     use in rasterization) do not happen until some unspecified	time in	the
     future.  In particular, the order of the asynchronous command relative to
     other OpenGL commands issued later	in the command stream is undefined.
     An	implementation may choose to execute asynchronous commands in parallel
     with the normal command stream or at some convenient time in the future.

     Calling glDisable with parameter GL_ASYNC_TEX_IMAGE_SGIX restores the
     default synchronous behavior for subsequent glTexImage3D commands.	 It
     does not affect any pending asynchronous glTexImage commands, or wait for
     their completion.

     When an asynchronous glTexImage3D command is issued, it is	associated
     with the current value of GL_ASYNC_MARKER_SGIX as defined by the
     SGIX_async	extension.  A program can determine if an asynchronous
     glTexImage3D command has completed	by using the glFinishAsyncSGIX or
     glPollAsyncSGIX commands.

     There is a	maximum	number of asynchronous glTexImage commands that	can be
     outstanding at any	one time, defined by the implementation.  This value
     can be queried with glGetIntegerv with argument
     GL_MAX_ASYNC_TEX_IMAGE_SGIX.

NOTES    [Toc]    [Back]

     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.

     GL_ABGR_EXT is part of the	EXT_abgr extension, not	part of	the core GL
     command set.  If GL_EXT_abgr is included in the string returned by
     glGetString, when called with argument GL_EXTENSIONS, extension EXT_abgr
     is	supported by the GL.

     glTexImage3D is available only if the GL version is 1.2 or	greater.

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

     pixels may	be a null pointer. In this case	texture	memory is allocated to
     accommodate a texture of width width, height height, and depth depth.
     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.



									Page 5






glTexImage3D(3G)	       OpenGL Reference		      glTexImage3D(3G)



     Formats GL_BGR, and GL_BGRA and types GL_UNSIGNED_BYTE_3_3_2,
     GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5,
     GL_UNSIGNED_SHORT_5_6_5_REV, GL_UNSIGNED_SHORT_4_4_4_4,
     GL_UNSIGNED_SHORT_4_4_4_4_REV, GL_UNSIGNED_SHORT_5_5_5_1,
     GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8,
     GL_UNSIGNED_INT_8_8_8_8_REV, GL_UNSIGNED_INT_10_10_10_2, and
     GL_UNSIGNED_INT_2_10_10_10_REV are	available only if the GL version is
     1.2 or greater.

     If	the GL_ARB_imaging extension is	supported, RGBA	elements may also be
     processed by the imaging pipeline.	 The following stages may be applied
     to	an RGBA	color before color component clamping to the range [0, 1]:

     1.	Color component	replacement by the color table specified for
	GL_COLOR_TABLE,	if enabled. See	glColorTable.

     2.	Color component	replacement by the color table specified for
	GL_POST_CONVOLUTION_COLOR_TABLE, if enabled.  See glColorTable.

     3.	Transformation by the color matrix.  See glMatrixMode.

     4.	RGBA components	may be multiplied by GL_POST_COLOR_MATRIX_c_SCALE,
	and added to GL_POST_COLOR_MATRIX_c_BIAS, if enabled.  See
	glPixelTransfer.

     5.	Color component	replacement by the color table specified for
	GL_POST_COLOR_MATRIX_COLOR_TABLE, if enabled.  See glColorTable.

ERRORS    [Toc]    [Back]

     GL_INVALID_ENUM is	generated if target is not GL_TEXTURE_3D or
     GL_PROXY_TEXTURE_3D.

     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
								   2
     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, height, or	depth is less than 0
     or	greater	than 2 + GL_MAX_TEXTURE_SIZE, or if either cannot be
		     k
     represented as 2  + 2(border) for some integer value of k.



									Page 6






glTexImage3D(3G)	       OpenGL Reference		      glTexImage3D(3G)



     GL_INVALID_VALUE is generated if border is	not 0 or 1.

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

     GL_INVALID_OPERATION is generated if type is one of
     GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV,
     GL_UNSIGNED_SHORT_5_6_5, or GL_UNSIGNED_SHORT_5_6_5_REV and format	is not
     GL_RGB.

     GL_INVALID_OPERATION is generated if type is one of
     GL_UNSIGNED_SHORT_4_4_4_4,	GL_UNSIGNED_SHORT_4_4_4_4_REV,
     GL_UNSIGNED_SHORT_5_5_5_1,	GL_UNSIGNED_SHORT_1_5_5_5_REV,
     GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV,
     GL_UNSIGNED_INT_10_10_10_2, or GL_UNSIGNED_INT_2_10_10_10_REV and format
     is	not GL_RGBA, GL_BGRA or	GL_ABGR_EXT.

     GL_INVALID_OPERATION is generated if GL_ASYNC_TEX_IMAGE_SGIX is enabled
     and the number of asynchronous glTexImage commands	that have been issued
     but not queried (using glFinishAsyncSGIX or glPollAsyncSGIX) exceeds
     GL_MAX_ASYNC_TEX_IMAGE_SGIX.

ASSOCIATED GETS    [Toc]    [Back]

     glGetTexImage
     glIsEnabled with argument GL_TEXTURE_3D


MACHINE	DEPENDENCIES
     The SGIX_async and	SGIX_async_pixel extensions are	implemented only on
     Octane2 VPro systems.

     On	RealityEngine, RealityEngine2, and VTX systems,	the following
     restrictions apply	to 3D texturing:

	  1.  The texture environment must be defined and texturing must be
	      enabled before loading a texture.

	  2.  Texture formats composed only of alpha are not supported.

	  3.  Borders are not supported; hence the border width	must be	0.

	  4.  Proxy textures are not supported.

	  5.  3D mipmaps are not supported. Hence, the minifying function must
	      be set to	GL_NEAREST or GL_LINEAR	(see glTexParameter).

	  6   3D texturing when	rendering to pixmaps is	not supported.

	  7.  GL_INTERLACE_SGIX	is not supported (see glEnable).






									Page 7






glTexImage3D(3G)	       OpenGL Reference		      glTexImage3D(3G)



     On	High Impact and	Maximum	Impact systems,	the following restrictions
     apply to 3D texturing:

	  1.  Perspective views	are not	supported.

	  2.  Borders are not supported; hence the border width	must be	0.

	  3.  3D mipmaps are not supported. Hence, the minifying function must
	      be set to	GL_NEAREST or GL_LINEAR	(see glTexParameter), and the
	      level parameter must be 0.

	  4.  Textures that have a width of 16 or less will not	render
	      correctly	at the wrap_s boundary.
     On	Octane2	VPro systems, 3D mipmapping is not supported.  However,	all
     OpenGL state related to the GL_TEXTURE_3D target is correctly errorchecked
 and queryable.  For example, an incomplete	mipmap stack results
     in	disabling 3D texturing,	just as	if 3D mipmapping were supported.  The
     only restriction is that, during rasterization, only the base level of
     the texture is sampled.  (The GL_TEXTURE_BASE_LEVEL parameter may be used
     to	establish the base level of the	texture; it need not be	level 0.)  For
     3D	texturing at rasterization time, the mipmapping	forms of the
     GL_TEXTURE_MIN_FILTER parameter are synonymous with the equivalent	nonmipmapping
	form.

SEE ALSO    [Toc]    [Back]

      
      
     glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D,
     glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawPixels, glPixelStore,
     glPixelTransfer, glTexEnv,	glTexGen, glTexImage1D,	glTexImage2D,
     glTexSubImage1D, glTexSubImage2D, glTexSubImage3D,	glTexParameter,
     glAsyncMarkerSGIX,	glDeleteAsyncMarkersSGIX, glFinishAsyncSGIX,
     glGenAsyncMarkersSGIX, glIsAsyncMarkerSGIX, glPollAsyncSGIX


									PPPPaaaaggggeeee 8888
[ Back ]
 Similar pages
Name OS Title
glTexImage1D Tru64 specify a one-dimensional texture image
glteximage2d IRIX specify a two-dimensional texture image
glteximage1d IRIX specify a one-dimensional texture image
glTexImage2D Tru64 specify a two-dimensional texture image
glteximage4dext IRIX specify a four-dimensional texture image
texdef3d IRIX convert a 3-dimensional image into a texture
texdef2d IRIX convert a 2-dimensional image into a texture
texdef IRIX convert a 2-dimensional image into a texture
gltexsubimage2d IRIX specify a two-dimensional texture subimage
glTexSubImage1D Tru64 specify a one-dimensional texture subimage
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service