diff options
Diffstat (limited to 'nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/teximage2d.gl')
| -rw-r--r-- | nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/teximage2d.gl | 487 |
1 files changed, 487 insertions, 0 deletions
diff --git a/nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/teximage2d.gl b/nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/teximage2d.gl new file mode 100644 index 000000000..0e7203a99 --- /dev/null +++ b/nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/teximage2d.gl @@ -0,0 +1,487 @@ +_C_ License Applicability. Except to the extent portions of this file are +_C_ made subject to an alternative license as permitted in the SGI Free +_C_ Software License B, Version 1.1 (the "License"), the contents of this +_C_ file are subject only to the provisions of the License. You may not use +_C_ this file except in compliance with the License. You may obtain a copy +_C_ of the License at Silicon Graphics, Inc., attn: Legal Services, 1600 +_C_ Amphitheatre Parkway, Mountain View, CA 94043-1351, or at: +_C_ +_C_ http://oss.sgi.com/projects/FreeB +_C_ +_C_ Note that, as provided in the License, the Software is distributed on an +_C_ "AS IS" basis, with ALL EXPRESS AND IMPLIED WARRANTIES AND CONDITIONS +_C_ DISCLAIMED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES AND +_C_ CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A +_C_ PARTICULAR PURPOSE, AND NON-INFRINGEMENT. +_C_ +_C_ Original Code. The Original Code is: OpenGL Sample Implementation, +_C_ Version 1.2.1, released January 26, 2000, developed by Silicon Graphics, +_C_ Inc. The Original Code is Copyright (c) 1991-2000 Silicon Graphics, Inc. +_C_ Copyright in any portions created by third parties is as indicated +_C_ elsewhere herein. All Rights Reserved. +_C_ +_C_ Additional Notice Provisions: The application programming interfaces +_C_ established by SGI in conjunction with the Original Code are The +_C_ OpenGL(R) Graphics System: A Specification (Version 1.2.1), released +_C_ April 1, 1999; The OpenGL(R) Graphics System Utility Library (Version +_C_ 1.3), released November 4, 1998; and OpenGL(R) Graphics with the X +_C_ Window System(R) (Version 1.3), released October 19, 1998. This software +_C_ was created using the OpenGL(R) version 1.2.1 Sample Implementation +_C_ published by SGI, but has not been independently verified as being +_C_ compliant with the OpenGL(R) version 1.2.1 Specification. +_C_ +_C_ The first character in this file must be an '_'! +_C_ Anything on a line after _C_ is ignored +_define(_filters,eqn)_C_ +_C_ eqn is automatically replaced with neqn for nroff +_header(TexImage2D,specify a two-dimensional texture image) +_names(TexImage2D) +.EQ +delim $$ +.EN +.SH PARAMETERS +_phead(_param1) +Specifies the target texture. +Must be _const(TEXTURE_2D) or _const(PROXY_TEXTURE_2D). +_phead(_param2) +Specifies the level-of-detail number. +Level 0 is the base image level. +Level \f2n\fP is the \f2n\fPth mipmap reduction image. +_phead(_param3) +Specifies the number of color components in the texture. +Must be 1, 2, 3, or 4, or one of the following symbolic constants: +_const(ALPHA), +_const(ALPHA4), +_const(ALPHA8), +_const(ALPHA12), +_const(ALPHA16), +_const(LUMINANCE), +_const(LUMINANCE4), +_const(LUMINANCE8), +_const(LUMINANCE12), +_const(LUMINANCE16), +_const(LUMINANCE_ALPHA), +_const(LUMINANCE4_ALPHA4), +_const(LUMINANCE6_ALPHA2), +_const(LUMINANCE8_ALPHA8), +_const(LUMINANCE12_ALPHA4), +_const(LUMINANCE12_ALPHA12), +_const(LUMINANCE16_ALPHA16), +_const(INTENSITY), +_const(INTENSITY4), +_const(INTENSITY8), +_const(INTENSITY12), +_const(INTENSITY16), +_const(R3_G3_B2), +_const(RGB), +_const(RGB4), +_const(RGB5), +_const(RGB8), +_const(RGB10), +_const(RGB12), +_const(RGB16), +_const(RGBA), +_const(RGBA2), +_const(RGBA4), +_const(RGB5_A1), +_const(RGBA8), +_const(RGB10_A2), +_const(RGBA12), or +_const(RGBA16). +_phead(_param4) +Specifies the width of the texture image. +Must be $2 sup n ~+~ 2 ( _eqnparam6 )$ for some integer $n$. All +implementations support texture images that are at least 64 texels +wide. +_phead(_param5) +Specifies the height of the texture image. +Must be $2 sup m ~+~ 2 ( _eqnparam6 )$ for some integer $m$. All +implementations support texture images that are at least 64 texels +high. +_phead(_param6) +Specifies the width of the border. +Must be either 0 or 1. +_phead(_param7) +Specifies the format of the pixel data. +The following symbolic values are accepted: +_const(COLOR_INDEX), +_const(RED), +_const(GREEN), +_const(BLUE), +_const(ALPHA), +_const(RGB), +_const(BGR) +_const(RGBA), +_const(BGRA), +_C_ _const(ABGR_EXT), +_const(LUMINANCE), and +_const(LUMINANCE_ALPHA). +_phead(_param8) +Specifies the data type of the pixel data. +The following symbolic values are accepted: +_const(UNSIGNED_BYTE), +_const(BYTE), +_const(BITMAP), +_const(UNSIGNED_SHORT), +_const(SHORT), +_const(UNSIGNED_INT), +_const(INT), +_const(FLOAT), +_const(UNSIGNED_BYTE_3_3_2), +_const(UNSIGNED_BYTE_2_3_3_REV), +_const(UNSIGNED_SHORT_5_6_5), +_const(UNSIGNED_SHORT_5_6_5_REV), +_const(UNSIGNED_SHORT_4_4_4_4), +_const(UNSIGNED_SHORT_4_4_4_4_REV), +_const(UNSIGNED_SHORT_5_5_5_1), +_const(UNSIGNED_SHORT_1_5_5_5_REV), +_const(UNSIGNED_INT_8_8_8_8), +_const(UNSIGNED_INT_8_8_8_8_REV), +_const(UNSIGNED_INT_10_10_10_2), and +_const(UNSIGNED_INT_2_10_10_10_REV). +_phead(_param9) +Specifies a pointer to the image data in memory. +.SH 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 _cmnd(Enable) +and _cmnd(Disable) with argument _const(TEXTURE_2D). +.P +To define texture images, call _cmnd. +The arguments describe the parameters of the texture image, +such as height, +width, +width of the border, +level-of-detail number +(see _cmnd(TexParameter)), +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 _cmnd(DrawPixels). +.P +If _param1 is _const(PROXY_TEXTURE_2D), no data is read from _param9, 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 _cmnd(GetError)). To query for an +entire mipmap array, use an image array level greater than or equal to +1. +.P +If _param1 is _const(TEXTURE_2D), +data is read from _param9 as a sequence of signed or unsigned bytes, +shorts, +or longs, +or single-precision floating-point values, +depending on _param8. +These values are grouped into sets of one, +two, +three, +or four values, +depending on _param7, +to form elements. +If _param8 is _const(BITMAP), +the data is considered as a string of unsigned bytes (and +_param7 must be _const(COLOR_INDEX)). +.bp +Each data byte is treated as eight 1-bit elements, +with bit ordering determined by _const(UNPACK_LSB_FIRST) +(see _cmnd(PixelStore)). +.P +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. +.P +_param7 determines the composition of each element in _param9. +It can assume one of eleven symbolic values: +.TP 10 +_const(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 _const(INDEX_SHIFT), +and added to _const(INDEX_OFFSET) +(see +.br +_cmnd(PixelTransfer)). +The resulting index is converted to a set of color components +using the +_const(PIXEL_MAP_I_TO_R), +_const(PIXEL_MAP_I_TO_G), +_const(PIXEL_MAP_I_TO_B), and +_const(PIXEL_MAP_I_TO_A) tables, +and clamped to the range [0,1]. +.TP +_const(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 _const(c_SCALE), +added to the signed bias _const(c_BIAS), +and clamped to the range [0,1] +(see _cmnd(PixelTransfer)). +.TP +_const(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 _const(c_SCALE), +added to the signed bias _const(c_BIAS), +and clamped to the range [0,1] +(see _cmnd(PixelTransfer)). +.TP +_const(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 _const(c_SCALE), +added to the signed bias _const(c_BIAS), +and clamped to the range [0,1] +(see _cmnd(PixelTransfer)). +.TP +_const(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 _const(c_SCALE), +added to the signed bias _const(c_BIAS), +and clamped to the range [0,1] +(see _cmnd(PixelTransfer)). +.TP +_const(RGB) +.TP +_const(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 factor _const(c_SCALE), +added to the signed bias _const(c_BIAS), +and clamped to the range [0,1] +(see +.br +_cmnd(PixelTransfer)). +.TP +_const(RGBA) +.TP +_const(BGRA) +_C_ .TP +_C_ _const(ABGR_EXT) +Each element contains all four components. +Each component is multiplied by the signed scale factor _const(c_SCALE), +added to the signed bias _const(c_BIAS), +and clamped to the range [0,1] +(see _cmnd(PixelTransfer)). +.TP +_const(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 _const(c_SCALE), +added to the signed bias _const(c_BIAS), +and clamped to the range [0,1] +(see _cmnd(PixelTransfer)). +.TP +_const(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 _const(c_SCALE), +added to the signed bias _const(c_BIAS), +and clamped to the range [0,1] +(see +.br +_cmnd(PixelTransfer)). +.P +Refer to the _cmnd(DrawPixels) reference page for a description of +the acceptable values for the _param8 parameter. +.P +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 _param3. The GL will choose an internal +representation that closely approximates that requested by _param3, but +it may not match exactly. +(The representations specified by _const(LUMINANCE), +_const(LUMINANCE_ALPHA), _const(RGB), +and _const(RGBA) must match exactly. The numeric values 1, 2, 3, and 4 +may also be used to specify the above representations.) +.P +Use the _const(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 +_cmnd(GetTexLevelParameter). +If the texture cannot be accommodated, texture state is set to 0. +.P +A one-component texture image uses only the red component of the RGBA +color extracted from _param9. +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. +.SH NOTES +Texturing has no effect in color index mode. +.P +If the _arbstring(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]: +.TP 3 +1. Color component replacement by the color table specified for +_const(COLOR_TABLE), if enabled. See _cmnd(ColorTable). +.TP +2. Two-dimensional Convolution filtering, if enabled. See +_cmnd(ConvolutionFilter1D). +.IP +If a convolution filter changes the __width of the texture (by +processing with a _const(CONVOLUTION_BORDER_MODE) of _const(REDUCE), for +example), the _param4 must $2 sup n + 2 ( _eqnparam5 )$, for some +integer $n$, and _param5 must be $2 sup m + ( _eqnparam6 )$, for some +integer $m$, after filtering. +.TP +3. RGBA components may be multiplied by _const(POST_CONVOLUTION_c_SCALE), +and added to _const(POST_CONVOLUTION_c_BIAS), if enabled. See +_cmnd(PixelTransfer). +.TP +4. Color component replacement by the color table specified for +_const(POST_CONVOLUTION_COLOR_TABLE), if enabled. See _cmnd(ColorTable). +.TP +5. Transformation by the color matrix. See _cmnd(MatrixMode). +.TP +6. RGBA components may be multiplied by _const(POST_COLOR_MATRIX_c_SCALE), +and added to _const(POST_COLOR_MATRIX_c_BIAS), if enabled. See +_cmnd(PixelTransfer). +.TP +7. Color component replacement by the color table specified for +_const(POST_COLOR_MATRIX_COLOR_TABLE), if enabled. See +_cmnd(ColorTable). +.P +The texture image can be represented by the same data formats +as the pixels in a _cmnd(DrawPixels) command, +except that _const(STENCIL_INDEX) and _const(DEPTH_COMPONENT) +cannot be used. +_cmnd(PixelStore) and _cmnd(PixelTransfer) modes affect texture images +in exactly the way they affect _cmnd(DrawPixels). +.P +_C_ _const(ABGR_EXT) is +_C_ part of the _extname(EXT_abgr) extension, not part of +_C_ the core GL command set. If _extstring(EXT_abgr) is included +_C_ in the string returned by _cmnd(GetString), when called with +_C_ argument _const(EXTENSIONS), extension _extname(EXT_abgr) is +_C_ supported by the GL. +.P +_cmnd and _const(PROXY_TEXTURE_2D) are available only if the GL +version is 1.1 or greater. +.P +Internal formats other than 1, 2, 3, or 4 may be used only if the GL +version is 1.1 or greater. +.P +In GL version 1.1 or greater, _param9 may be a null pointer. +In this case texture memory is +allocated to accommodate a texture of width _param4 and height _param5. +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. +.P +Formats _const(BGR), and _const(BGRA) and types +_const(UNSIGNED_BYTE_3_3_2), +_const(UNSIGNED_BYTE_2_3_3_REV), +_const(UNSIGNED_SHORT_5_6_5), +_const(UNSIGNED_SHORT_5_6_5_REV), +_const(UNSIGNED_SHORT_4_4_4_4), +_const(UNSIGNED_SHORT_4_4_4_4_REV), +_const(UNSIGNED_SHORT_5_5_5_1), +_const(UNSIGNED_SHORT_1_5_5_5_REV), +_const(UNSIGNED_INT_8_8_8_8), +_const(UNSIGNED_INT_8_8_8_8_REV), +_const(UNSIGNED_INT_10_10_10_2), and +_const(UNSIGNED_INT_2_10_10_10_REV) are available only if the GL version +is 1.2 or greater. +.P +When the _arbstring(multitexture) extension is supported, _cmnd +specifies the two-dimensional texture for the current texture unit, +specified with _cmnd(ActiveTextureARB). +.SH ERRORS +_const(INVALID_ENUM) is generated if _param1 is not _const(TEXTURE_2D) +or _const(PROXY_TEXTURE_2D). +.P +_const(INVALID_ENUM) is generated if _param7 is not an accepted +format constant. +Format constants other than _const(STENCIL_INDEX) and _const(DEPTH_COMPONENT) +are accepted. +.P +_const(INVALID_ENUM) is generated if _param8 is not a type constant. +.P +_const(INVALID_ENUM) is generated if _param8 is _const(BITMAP) and +_param7 is not _const(COLOR_INDEX). +.P +_const(INVALID_VALUE) is generated if _param2 is less than 0. +.P +_const(INVALID_VALUE) may be generated if _param2 is greater than $log +sub 2$\f2max\fP, +where \f2max\fP is the returned value of _const(MAX_TEXTURE_SIZE). +.P +_const(INVALID_VALUE) is generated if _param3 is not 1, 2, 3, 4, or one of the +accepted resolution and format symbolic constants. +.P +_const(INVALID_VALUE) is generated if _param4 or _param5 is less than 0 +or greater than 2 + _const(MAX_TEXTURE_SIZE), +or if either cannot be represented as $2 sup k ~+~ 2(_eqnparam6)$ for some +integer value of \f2k\fP. +.P +_const(INVALID_VALUE) is generated if _param6 is not 0 or 1. +.P +_const(INVALID_OPERATION) is generated if _cmnd +is executed between the execution of _cmnd(Begin) +and the corresponding execution of _cmnd(End). +.P +_const(INVALID_OPERATION) is generated if _param8 is one of +_const(UNSIGNED_BYTE_3_3_2), +_const(UNSIGNED_BYTE_2_3_3_REV), +_const(UNSIGNED_SHORT_5_6_5), or +_const(UNSIGNED_SHORT_5_6_5_REV) +and _param7 is not _const(RGB). +.P +_const(INVALID_OPERATION) is generated if _param8 is one of +_const(UNSIGNED_SHORT_4_4_4_4), +_const(UNSIGNED_SHORT_4_4_4_4_REV), +_const(UNSIGNED_SHORT_5_5_5_1), +_const(UNSIGNED_SHORT_1_5_5_5_REV), +_const(UNSIGNED_INT_8_8_8_8), +_const(UNSIGNED_INT_8_8_8_8_REV), +_const(UNSIGNED_INT_10_10_10_2), or +_const(UNSIGNED_INT_2_10_10_10_REV) +and _param7 is neither _const(RGBA) nor _const(BGRA). +.SH ASSOCIATED GETS +_cmnd(GetTexImage) +.br +_cmnd(IsEnabled) with argument _const(TEXTURE_2D) +.SH SEE ALSO +_cmnd(ColorTable), +_cmnd(ConvolutionFilter2D), +_cmnd(CopyPixels), +_cmnd(CopyTexImage1D), +_cmnd(CopyTexImage2D), +_cmnd(CopyTexSubImage1D), +_cmnd(CopyTexSubImage2D), +_cmnd(CopyTexSubImage3D), +_cmnd(DrawPixels), +_cmnd(MatrixMode), +_cmnd(PixelStore), +_cmnd(PixelTransfer), +_cmnd(SeparableFilter2D), +_cmnd(TexEnv), +_cmnd(TexGen), +_cmnd(TexImage1D), +_cmnd(TexImage3D), +_cmnd(TexSubImage1D), +_cmnd(TexSubImage2D), +_cmnd(TexSubImage3D), +_cmnd(TexParameter) + |