1GLGETTEXIMAGE(3G) [FIXME: manual] GLGETTEXIMAGE(3G)
2
6 glGetTexImage, glGetnTexImage, glGetTextureImage - return a texture
7 image
8
10 void glGetTexImage(GLenum target, GLint level, GLenum format,
11 GLenum type, GLvoid * pixels);
12 void glGetnTexImage(GLenum target, GLint level, GLenum format,
14 GLenum type, GLsizei bufSize, void *pixels);
15 void glGetTextureImage(GLuint texture, GLint level, GLenum format,
17 GLenum type, GLsizei bufSize, void *pixels);
18
20 target
21 Specifies the target to which the texture is bound for
22 glGetTexImage and glGetnTexImage functions. GL_TEXTURE_1D,
23 GL_TEXTURE_2D, GL_TEXTURE_3D, GL_TEXTURE_1D_ARRAY,
24 GL_TEXTURE_2D_ARRAY, GL_TEXTURE_RECTANGLE,
25 GL_TEXTURE_CUBE_MAP_POSITIVE_X, GL_TEXTURE_CUBE_MAP_NEGATIVE_X,
26 GL_TEXTURE_CUBE_MAP_POSITIVE_Y, GL_TEXTURE_CUBE_MAP_NEGATIVE_Y,
27 GL_TEXTURE_CUBE_MAP_POSITIVE_Z, GL_TEXTURE_CUBE_MAP_NEGATIVE_Z, and
28 GL_TEXTURE_CUBE_MAP_ARRAY are acceptable.
29 texture
31 Specifies the texture object name.
32 level
34 Specifies the level-of-detail number of the desired image. Level 0
35 is the base image level. Level n is the nth mipmap reduction image.
36 format
38 Specifies a pixel format for the returned data. The supported
39 formats are GL_STENCIL_INDEX, GL_DEPTH_COMPONENT, GL_DEPTH_STENCIL,
40 GL_RED, GL_GREEN, GL_BLUE, GL_RG, GL_RGB, GL_RGBA, GL_BGR, GL_BGRA,
41 GL_RED_INTEGER, GL_GREEN_INTEGER, GL_BLUE_INTEGER, GL_RG_INTEGER,
42 GL_RGB_INTEGER, GL_RGBA_INTEGER, GL_BGR_INTEGER, GL_BGRA_INTEGER.
43 type
45 Specifies a pixel type for the returned data. The supported types
46 are GL_UNSIGNED_BYTE, GL_BYTE, GL_UNSIGNED_SHORT, GL_SHORT,
47 GL_UNSIGNED_INT, GL_INT, GL_HALF_FLOAT, GL_FLOAT,
48 GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV,
49 GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_5_6_5_REV,
50 GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_4_4_4_4_REV,
51 GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_1_5_5_5_REV,
52 GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV,
53 GL_UNSIGNED_INT_10_10_10_2, GL_UNSIGNED_INT_2_10_10_10_REV,
54 GL_UNSIGNED_INT_24_8, GL_UNSIGNED_INT_10F_11F_11F_REV,
55 GL_UNSIGNED_INT_5_9_9_9_REV, and GL_FLOAT_32_UNSIGNED_INT_24_8_REV.
56 bufSize
58 Specifies the size of the buffer pixels for glGetnTexImage and
59 glGetTextureImage functions.
60 pixels
62 Returns the texture image. Should be a pointer to an array of the
63 type specified by type.
64
66 glGetTexImage, glGetnTexImage and glGetTextureImage functions return a
67 texture image into pixels. For glGetTexImage and glGetnTexImage, target
68 specifies whether the desired texture image is one specified by
69 glTexImage1D() (GL_TEXTURE_1D), glTexImage2D() (GL_TEXTURE_1D_ARRAY,
70 GL_TEXTURE_RECTANGLE, GL_TEXTURE_2D or any of GL_TEXTURE_CUBE_MAP_*),
71 or glTexImage3D() (GL_TEXTURE_2D_ARRAY, GL_TEXTURE_3D,
72 GL_TEXTURE_CUBE_MAP_ARRAY). For glGetTextureImage, texture specifies
73 the texture object name. In addition to types of textures accepted by
74 glGetTexImage and glGetnTexImage, the function also accepts cube map
75 texture objects (with effective target GL_TEXTURE_CUBE_MAP). level
76 specifies the level-of-detail number of the desired image. format and
77 type specify the format and type of the desired image array. See the
78 reference page for glTexImage1D() for a description of the acceptable
79 values for the format and type parameters, respectively. For
80 glGetnTexImage and glGetTextureImage functions, bufSize tells the size
81 of the buffer to receive the retrieved pixel data. glGetnTexImage and
82 glGetTextureImage do not write more than bufSize bytes into pixels.
83 If a non-zero named buffer object is bound to the GL_PIXEL_PACK_BUFFER
85 target (see glBindBuffer()) while a texture image is requested, pixels
86 is treated as a byte offset into the buffer object's data store.
87 To understand the operation of glGetTexImage, consider the selected
89 internal four-component texture image to be an RGBA color buffer the
90 size of the image. The semantics of glGetTexImage are then identical to
91 those of glReadPixels(), with the exception that no pixel transfer
92 operations are performed, when called with the same format and type,
93 with x and y set to 0, width set to the width of the texture image and
94 height set to 1 for 1D images, or to the height of the texture image
95 for 2D images.
96 If the selected texture image does not contain four components, the
98 following mappings are applied. Single-component textures are treated
99 as RGBA buffers with red set to the single-component value, green set
100 to 0, blue set to 0, and alpha set to 1. Two-component textures are
101 treated as RGBA buffers with red set to the value of component zero,
102 alpha set to the value of component one, and green and blue set to 0.
103 Finally, three-component textures are treated as RGBA buffers with red
104 set to component zero, green set to component one, blue set to
105 component two, and alpha set to 1.
106 To determine the required size of pixels, use glGetTexLevelParameter()
108 to determine the dimensions of the internal texture image, then scale
109 the required number of pixels by the storage required for each pixel,
110 based on format and type. Be sure to take the pixel storage parameters
111 into account, especially GL_PACK_ALIGNMENT.
112 If glGetTextureImage is used against a cube map texture object, the
114 texture is treated as a three-dimensional image of a depth of 6, where
115 the cube map faces are ordered as image layers, in an order presented
116 in the table below:
117 ┌─────────────┬────────────────────────────────┐
119 │Layer number │ Cube Map Face │
120 ├─────────────┼────────────────────────────────┤
121 │0 │ GL_TEXTURE_CUBE_MAP_POSITIVE_X │
122 ├─────────────┼────────────────────────────────┤
123 │1 │ GL_TEXTURE_CUBE_MAP_NEGATIVE_X │
124 ├─────────────┼────────────────────────────────┤
125 │2 │ GL_TEXTURE_CUBE_MAP_POSITIVE_Y │
126 ├─────────────┼────────────────────────────────┤
127 │3 │ GL_TEXTURE_CUBE_MAP_NEGATIVE_Y │
128 ├─────────────┼────────────────────────────────┤
129 │4 │ GL_TEXTURE_CUBE_MAP_POSITIVE_Z │
130 ├─────────────┼────────────────────────────────┤
131 │5 │ GL_TEXTURE_CUBE_MAP_NEGATIVE_Z │
132 └─────────────┴────────────────────────────────┘
133
135 If an error is generated, no change is made to the contents of pixels.
136 glGetTexImage and glGetnTexImage return the texture image for the
138 active texture unit.
139 GL_STENCIL_INDEX is accepted for format only if the GL version is 4.4
141 or greater.
142
144 GL_INVALID_ENUM is generated by glGetTexImage and glGetnTexImage
145 functions if target is not an accepted value. These include:
146 · GL_TEXTURE_1D, GL_TEXTURE_2D, GL_TEXTURE_3D, GL_TEXTURE_1D_ARRAY,
148 GL_TEXTURE_2D_ARRAY, GL_TEXTURE_CUBE_MAP_ARRAY,
149 GL_TEXTURE_RECTANGLE, GL_TEXTURE_CUBE_MAP_POSITIVE_X,
150 GL_TEXTURE_CUBE_MAP_NEGATIVE_X, GL_TEXTURE_CUBE_MAP_POSITIVE_Y,
151 GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, GL_TEXTURE_CUBE_MAP_POSITIVE_Z, and
152 GL_TEXTURE_CUBE_MAP_NEGATIVE_Z for glGetTexImage and glGetnTexImage
153 functions.
154 · GL_TEXTURE_1D, GL_TEXTURE_2D, GL_TEXTURE_3D, GL_TEXTURE_1D_ARRAY,
156 GL_TEXTURE_2D_ARRAY, GL_TEXTURE_CUBE_MAP_ARRAY,
157 GL_TEXTURE_RECTANGLE, and GL_TEXTURE_CUBE_MAP for glGetTextureImage
158 function.
159 GL_INVALID_OPERATION is generated by glGetTextureImage if texture is
161 not the name of an existing texture object.
162 GL_INVALID_ENUM is generated if format, or type is not an accepted
164 value.
165 GL_INVALID_VALUE is generated if level is less than 0.
167 GL_INVALID_VALUE may be generated if level is greater than log 2 max,
169 where max is the returned value of GL_MAX_TEXTURE_SIZE.
170 GL_INVALID_VALUE is generated if level is non-zero and the effective
172 target is GL_TEXTURE_RECTANGLE.
173 GL_INVALID_OPERATION is generated if type is one of
175 GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV,
176 GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_5_6_5_REV, or
177 GL_UNSIGNED_INT_10F_11F_11F_REV and format is not GL_RGB.
178 GL_INVALID_OPERATION is generated if type is one of
180 GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_4_4_4_4_REV,
181 GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_1_5_5_5_REV,
182 GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV,
183 GL_UNSIGNED_INT_10_10_10_2, GL_UNSIGNED_INT_2_10_10_10_REV, or
184 GL_UNSIGNED_INT_5_9_9_9_REV and format is neither GL_RGBA or GL_BGRA.
185 GL_INVALID_OPERATION is generated if format is GL_STENCIL_INDEX and the
187 base internal format is not GL_STENCIL_INDEX or GL_DEPTH_STENCIL.
188 GL_INVALID_OPERATION is generated if a non-zero buffer object name is
190 bound to the GL_PIXEL_PACK_BUFFER target and the buffer object's data
191 store is currently mapped.
192 GL_INVALID_OPERATION is generated if a non-zero buffer object name is
194 bound to the GL_PIXEL_PACK_BUFFER target and the data would be packed
195 to the buffer object such that the memory writes required would exceed
196 the data store size.
197 GL_INVALID_OPERATION is generated if a non-zero buffer object name is
199 bound to the GL_PIXEL_PACK_BUFFER target and pixels is not evenly
200 divisible into the number of bytes needed to store in memory a datum
201 indicated by type.
202 GL_INVALID_OPERATION is generated by glGetTextureImage and
204 glGetnTexImage if the buffer size required to store the requested data
205 is greater than bufSize.
206
208 glGetTexLevelParameter() with argument GL_TEXTURE_WIDTH
209 glGetTexLevelParameter() with argument GL_TEXTURE_HEIGHT
211 glGetTexLevelParameter() with argument GL_TEXTURE_INTERNAL_FORMAT
213 glGet() with arguments GL_PACK_ALIGNMENT and others
215 glGet() with argument GL_PIXEL_PACK_BUFFER_BINDING
217
219 ┌──────────────────┬───────────────────────────────────────────────────────────────────────┐
220 │ │ OpenGL Version │
221 ├──────────────────┼─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┤
222 │Function │ 2.0 │ 2.1 │ 3.0 │ 3.1 │ 3.2 │ 3.3 │ 4.0 │ 4.1 │ 4.2 │ 4.3 │ 4.4 │ 4.5 │
223 │/ │ │ │ │ │ │ │ │ │ │ │ │ │
224 │Feature │ │ │ │ │ │ │ │ │ │ │ │ │
225 │Name │ │ │ │ │ │ │ │ │ │ │ │ │
226 ├──────────────────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤
227 │glGetTexImage │ ✔ │ ✔ │ ✔ │ ✔ │ ✔ │ ✔ │ ✔ │ ✔ │ ✔ │ ✔ │ ✔ │ ✔ │
228 ├──────────────────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤
229 │glGetTextureImage │ - │ - │ - │ - │ - │ - │ - │ - │ - │ - │ - │ ✔ │
230 ├──────────────────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤
231 │glGetnTexImage │ - │ - │ - │ - │ - │ - │ - │ - │ - │ - │ - │ ✔ │
232 └──────────────────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘
233
235 glActiveTexture(), glReadPixels(), glTexImage1D(), glTexImage2D(),
236 glTexImage3D(), glTexSubImage1D(), glTexSubImage2D(),
237 glTexSubImage3D(), glTexParameter()
238
240 Copyright © 1991-2006 Silicon Graphics, Inc. Copyright © 2010-2014
241 Khronos Group. This document is licensed under the SGI Free Software B
242 License. For details, see http://oss.sgi.com/projects/FreeB/.
243
245 Copyright © 1991-2006 Silicon Graphics, Inc.
246 Copyright © 2010-2014 Khronos Group
247[FIXME: source] 07/13/2018 GLGETTEXIMAGE(3G)