X-Git-Url: http://git.hcoop.net/clinton/guile-figl.git/blobdiff_plain/b002944dd992dc5a273e0067504beb48e1ae3d1c..a6a00658f26c164551287799b194cc2f07eb78be:/upstream-doc/man4/glGetTexImage.xml diff --git a/upstream-doc/man4/glGetTexImage.xml b/upstream-doc/man4/glGetTexImage.xml new file mode 100644 index 0000000..37f5b9a --- /dev/null +++ b/upstream-doc/man4/glGetTexImage.xml @@ -0,0 +1,314 @@ + + + + + + + 1991-2006 + Silicon Graphics, Inc. + + + glGetTexImage + 3G + + + glGetTexImage + return a texture image + + C Specification + + + void glGetTexImage + GLenum target + GLint level + GLenum format + GLenum type + GLvoid * img + + + + + Parameters + + + target + + + Specifies which texture is to be obtained. + GL_TEXTURE_1D, + GL_TEXTURE_2D, + GL_TEXTURE_3D, + GL_TEXTURE_1D_ARRAY, + GL_TEXTURE_2D_ARRAY, + GL_TEXTURE_RECTANGLE, + GL_TEXTURE_CUBE_MAP_POSITIVE_X, + GL_TEXTURE_CUBE_MAP_NEGATIVE_X, + GL_TEXTURE_CUBE_MAP_POSITIVE_Y, + GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, + GL_TEXTURE_CUBE_MAP_POSITIVE_Z, and + GL_TEXTURE_CUBE_MAP_NEGATIVE_Z + 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_STENCIL_INDEX, + GL_DEPTH_COMPONENT, + GL_DEPTH_STENCIL, + GL_RED, + GL_GREEN, + GL_BLUE, + GL_RG, + GL_RGB, + GL_RGBA, + GL_BGR, + GL_BGRA, + GL_RED_INTEGER, + GL_GREEN_INTEGER, + GL_BLUE_INTEGER, + GL_RG_INTEGER, + GL_RGB_INTEGER, + GL_RGBA_INTEGER, + GL_BGR_INTEGER, + GL_BGRA_INTEGER. + + + + + 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, + GL_HALF_FLOAT, + 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, + GL_UNSIGNED_INT_2_10_10_10_REV, + GL_UNSIGNED_INT_24_8, + GL_UNSIGNED_INT_10F_11F_11F_REV, + GL_UNSIGNED_INT_5_9_9_9_REV, and + GL_FLOAT_32_UNSIGNED_INT_24_8_REV. + + + + + img + + + Returns the texture image. + Should be a pointer to an array of the type specified by type. + + + + + + Description + + glGetTexImage returns a texture image into img. + target specifies whether the desired texture image is one specified by + glTexImage1D (GL_TEXTURE_1D), + glTexImage2D (GL_TEXTURE_1D_ARRAY, GL_TEXTURE_RECTANGLE, + GL_TEXTURE_2D or any of + GL_TEXTURE_CUBE_MAP_*), + or + glTexImage3D (GL_TEXTURE_2D_ARRAY, + GL_TEXTURE_3D). + level specifies the level-of-detail number of the desired image. + format and type specify the format and type of the desired image array. + See the reference page for glTexImage1D + for a description of the acceptable values for the format and type + parameters, respectively. + + + If a non-zero named buffer object is bound to the GL_PIXEL_PACK_BUFFER target + (see glBindBuffer) while a texture image is + requested, img is treated as a byte offset into the buffer object's data store. + + + To understand the operation of glGetTexImage, consider 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, + with the exception that no pixel transfer operations are performed, + when called with the same format and type, + with x and y set to 0, + width set to the width of the texture image + and height set to 1 for 1D images, + or to the height of the texture image + for 2D images. + + + 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, + green set to 0, blue set to 0, and alpha set to 1. + 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 0. + 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 1. + + + To determine the required size of img, + use glGetTexLevelParameter to determine 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 img. + + + glGetTexImage returns the texture image for the active texture unit. + + + 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 0. + + + GL_INVALID_VALUE may be generated if level is greater + than + + + + log + 2 + + ⁡ + + max + + + , + where + max + is the returned value of GL_MAX_TEXTURE_SIZE. + + + GL_INVALID_OPERATION is returned if type is one of + 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, or + GL_UNSIGNED_INT_10F_11F_11F_REV and format is not GL_RGB. + + + GL_INVALID_OPERATION is returned 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, + GL_UNSIGNED_INT_2_10_10_10_REV, or + GL_UNSIGNED_INT_5_9_9_9_REV and format is neither GL_RGBA + or GL_BGRA. + + + GL_INVALID_OPERATION is generated if a non-zero buffer object name is bound to the + GL_PIXEL_PACK_BUFFER target and the buffer object's data store is currently mapped. + + + GL_INVALID_OPERATION is generated if a non-zero buffer object name is bound to the + GL_PIXEL_PACK_BUFFER target and the data would be packed to the buffer + object such that the memory writes required would exceed the data store size. + + + GL_INVALID_OPERATION is generated if a non-zero buffer object name is bound to the + GL_PIXEL_PACK_BUFFER target and img is not evenly divisible + into the number of bytes needed to store in memory a datum indicated by type. + + + Associated Gets + + glGetTexLevelParameter with argument GL_TEXTURE_WIDTH + + + glGetTexLevelParameter with argument GL_TEXTURE_HEIGHT + + + glGetTexLevelParameter with argument GL_TEXTURE_INTERNAL_FORMAT + + + glGet with arguments GL_PACK_ALIGNMENT and others + + + glGet with argument GL_PIXEL_PACK_BUFFER_BINDING + + + See Also + + glActiveTexture, + glReadPixels, + glTexImage1D, + glTexImage2D, + glTexImage3D, + glTexSubImage1D, + glTexSubImage2D, + glTexSubImage3D, + glTexParameter + + + Copyright + + Copyright 1991-2006 + Silicon Graphics, Inc. Copyright 2010 + Khronos Group. This document is licensed under the SGI + Free Software B License. For details, see + http://oss.sgi.com/projects/FreeB/. + + +