diff options
Diffstat (limited to 'nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/teximage1d.gl')
| -rw-r--r-- | nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/teximage1d.gl | 461 |
1 files changed, 461 insertions, 0 deletions
diff --git a/nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/teximage1d.gl b/nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/teximage1d.gl new file mode 100644 index 000000000..e93a63ac5 --- /dev/null +++ b/nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/teximage1d.gl @@ -0,0 +1,461 @@ +_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,tbl|eqn)_C_ +_C_ eqn is automatically replaced with neqn for nroff +_header(TexImage1D,specify a one-dimensional texture image) +_names(TexImage1D) +.EQ +delim $$ +.EN +.SH PARAMETERS +_phead(_param1) +Specifies the target texture. +Must be _const(TEXTURE_1D) or _const(PROXY_TEXTURE_1D). +_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(RGB), +_const(R3_G3_B2), +_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 ( _eqnparam5 )$ for some integer $n$. All +implementations support texture images that are at least 64 texels +wide. The height of the 1D texture image is 1. +_phead(_param5) +Specifies the width of the border. +Must be either 0 or 1. +_phead(_param6) +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(_param7) +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(_param8) +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 one-dimensional texturing, call _cmnd(Enable) +and _cmnd(Disable) with argument _const(TEXTURE_1D). +.P +Texture images are defined with _cmnd. +The arguments describe the parameters of the texture image, +such as width, +width of the border, +level-of-detail number +(see _cmnd(TexParameter)), +and the internal resolution and format used to store the image. +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_1D), no data is read from _param8, 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_1D), +data is read from _param8 as a sequence of signed or unsigned bytes, +shorts, +or longs, +or single-precision floating-point values, +depending on _param7. +These values are grouped into sets of one, +two, +three, +or four values, +depending on _param6, +to form elements. +If _param7 is _const(BITMAP), +the data is considered as a string of unsigned bytes +(and _param6 must be _const(COLOR_INDEX)). +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 left end of the texture array. +Subsequent elements progress left-to-right through the remaining texels +in the texture array. +The final element corresponds to the right end of the texture array. +.P +_param6 determines the composition of each element in _param8. +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 _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 _cmnd(PixelTransfer)). +.TP +_const(RGBA) +.TP +_const(BGRA) +_C_ .TP +_C_ _const(ABGR_EXT) +Each element contains all four components. +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) +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 _cmnd(PixelTransfer)). +.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 preceding representations.) +.P +Use the _const(PROXY_TEXTURE_1D) 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 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 from _param8. +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. One-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$, 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 connection. +_C_ .P +_const(PROXY_TEXTURE_1D) may be used 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, +_param8 may be a null pointer. In this case texture memory is +allocated to accommodate a texture of width _param4. +You can then download subtextures to initialize the +texture memory. The image is undefined if the program 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 one-dimensional texture for the current texture unit, +specified with _cmnd(ActiveTextureARB). +.SH ERRORS +_const(INVALID_ENUM) is generated if _param1 is not _const(TEXTURE_1D) +or _const(PROXY_TEXTURE_1D). +.P +_const(INVALID_ENUM) is generated if _param6 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 _param7 is not a type constant. +.P +_const(INVALID_ENUM) is generated if _param7 is _const(BITMAP) and +_param6 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 is less than 0 +or greater than 2 + _const(MAX_TEXTURE_SIZE), +or if it cannot be represented as $2 sup n ~+~ 2(_eqnparam5)$ +for some integer value of \f2n\fP. +.P +_const(INVALID_VALUE) is generated if _param5 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 _param7 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 _param6 is not _const(RGB). +.P +_const(INVALID_OPERATION) is generated if _param7 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 _param6 is neither _const(RGBA) nor _const(BGRA). +.SH ASSOCIATED GETS +_cmnd(GetTexImage) +.br +_cmnd(IsEnabled) with argument _const(TEXTURE_1D) +.SH SEE ALSO +_cmnd(ActiveTextureARB), +_cmnd(ColorTable), +_cmnd(ConvolutionFilter1D), +_cmnd(CopyPixels), +_cmnd(CopyTexImage1D), +_cmnd(CopyTexImage2D), +_cmnd(CopyTexSubImage1D), +_cmnd(CopyTexSubImage2D), +_cmnd(CopyTexSubImage3D), +_cmnd(DrawPixels), +_cmnd(MatrixMode), +_cmnd(PixelStore), +_cmnd(PixelTransfer), +_cmnd(TexEnv), +_cmnd(TexGen), +_cmnd(TexImage2D), +_cmnd(TexImage3D), +_cmnd(TexSubImage1D), +_cmnd(TexSubImage2D), +_cmnd(TexSubImage3D), +_cmnd(TexParameter) + |