1Name 2 3 ARB_get_texture_sub_image 4 5Name Strings 6 7 GL_ARB_get_texture_sub_image 8 9Contact 10 11 Brian Paul, VMware Inc. (brianp 'at' vmware.com) 12 13Contributors 14 15 Brian Paul 16 Daniel Koch, NVIDIA 17 18Notice 19 20 Copyright (c) 2014 The Khronos Group Inc. Copyright terms at 21 http://www.khronos.org/registry/speccopyright.html 22 23Specification Update Policy 24 25 Khronos-approved extension specifications are updated in response to 26 issues and bugs prioritized by the Khronos OpenGL Working Group. For 27 extensions which have been promoted to a core Specification, fixes will 28 first appear in the latest version of that core Specification, and will 29 eventually be backported to the extension document. This policy is 30 described in more detail at 31 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 32 33Status 34 35 Complete. 36 Approved by the ARB on June 26, 2014. 37 Ratified by the Khronos Board of Promoters on August 7, 2014. 38 39Version 40 41 Date: June 16, 2014 42 Revision: 7 43 44Number 45 46 ARB Extension #165 47 48Dependencies 49 50 OpenGL 2.0 is required 51 52 The extension is written against the OpenGL 4.4 Specification, Core 53 Profile, March 19, 2014. 54 55Overview 56 57 This extension adds a new function to get sub-regions of texture 58 images. 59 60IP Status 61 62 No known IP claims. 63 64New Procedures and Functions 65 66 void GetTextureSubImage(uint texture, int level, 67 int xoffset, int yoffset, int zoffset, 68 sizei width, sizei height, sizei depth, 69 enum format, enum type, 70 sizei bufSize, void *pixels); 71 72 void GetCompressedTextureSubImage(uint texture, 73 int level, int xoffset, 74 int yoffset, int zoffset, 75 sizei width, sizei height, 76 sizei depth, sizei bufSize, 77 void *pixels); 78 79New Types 80 81 None 82 83New Tokens 84 85 None 86 87Additions to Chapter 8 of the OpenGL 4.4 (Core Profile) Specification (Textures and Samplers) 88 89 Modify section 8.11.4, Texture Image Queries p. 224 90 91 (insert before the discussion of GetCompressedTexImage) 92 93 Sub-regions of a texture image may be obtained from a texture object 94 with the command 95 96 void GetTextureSubImage(uint texture, int level, 97 int xoffset, int yoffset, int zoffset, 98 sizei width, sizei height, sizei depth, 99 enum format, enum type, 100 sizei bufSize, void *pixels); 101 102 <texture> is the name of the source texture object. and must not be a 103 buffer or multisample texture. The effective <target> parameter is the 104 value of TEXTURE_TARGET for texture. <level>, <format>, <type> and 105 <pixels> have the same meaning as for GetTexImage. <bufSize> is the size 106 of the buffer to receive the retrieved pixel data. 107 108 For cube map textures, the behavior is as though GetTextureImage were 109 called, but only texels from the requested cube map faces (selected by 110 <zoffset> and <depth>, as described below) were returned. 111 112 <xoffset>, <yoffset> and <zoffset> values indicate the position of the 113 subregion to return. <width>, <height> and <depth> indicate the size of 114 the region to return. These parameters have the same meaning as for 115 TexSubImage3D, though for one- and two-dimensional textures there are 116 extra restrictions, described in the errors section below). 117 118 For one-dimensional array textures, <yoffset> is interpreted as the 119 first layer to access and <height> is the number of layers to access. 120 For two-dimensional array textures, <zoffset> is interpreted as the 121 first layer to access and <depth> is the number of layers to access. 122 Cube map textures are treated as an array of six slices in the 123 z-dimension, where the value of <zoffset> is interpreted as specifying 124 the cube map face for the corresponding layer in table 9.2 and <depth> 125 is the number of faces to access. For cube map array textures, <zoffset> 126 is the first layer-face to access, and <depth> is the number of layer- 127 faces to access. Each layer-face is translated into an array layer and a 128 cube map face as described for layer-face numbers in section 8.5.3. 129 130 Component groups from the specified sub-region are packed and placed 131 into memory as described for GetTextureImage, starting with the texel at 132 (<xoffset>, <yoffset>, <zoffset>). 133 134 Errors 135 136 An INVALID_OPERATION error is generated if <texture> is not the name of 137 an existing texture object. 138 139 An INVALID_OPERATION error is generated if <texture> is the name of a 140 buffer or multisample texture. 141 142 An INVALID_VALUE error is generated if <xoffset>, <yoffset> or <zoffset> 143 are negative. 144 145 An INVALID_VALUE error is generated by if <xoffset> + <width> is greater 146 than the texture level's width or if <yoffset> + <height> is greater 147 than the texture level's height or if <zoffset> + <depth> is greater 148 than the texture level's depth. 149 150 An INVALID_VALUE error is generated if the effective <target> is 151 TEXTURE_1D and either <yoffset> is not zero, or <height> is not one. 152 153 An INVALID_VALUE error is generated if the effective <target> is 154 TEXTURE_1D, TEXTURE_1D_ARRAY, TEXTURE_2D, or TEXTURE_RECTANGLE and 155 either <zoffset> is not zero, or <depth> is not one. 156 157 An INVALID_OPERATION error is generated if the buffer size required to 158 store the requested data is greater than <bufSize>. 159 160 161 (insert after the discussion of GetCompressedTexSubImage and before 162 section 8.12 begins) 163 164 If the compressed data are arranged into fixed-size blocks of texels, 165 the command 166 167 void GetCompressedTextureSubImage(uint texture, 168 int level, int xoffset, 169 int yoffset, int zoffset, 170 sizei width, sizei height, 171 sizei depth, sizei bufSize, 172 void *pixels); 173 174 can be used to obtain a sub-region of a compressed texture image instead 175 of the whole image. <texture> is the name of the source texture object, 176 and must not be a buffer or multisample texture. The effective <target> 177 is the value of TEXTURE_TARGET for <texture>. <level> and <pixels> have 178 the same meaning as the corresponding arguments CompressedTexSubImage3D. 179 <bufSize> indicates the size of the buffer to receive the retrieved 180 pixel data. 181 182 For cube map textures, the behavior is as though GetCompressedTexImage 183 were called once for each requested face (selected by <zoffset> and 184 <depth>, as described below) with <target> corresponding to the 185 requested texture cube map face as indicated by Table 9.2. <pixels> is 186 offset appropriately for each successive image. 187 188 <xoffset>, <yoffset> and <zoffset> indicate the position of the 189 subregion to return. <width>, <height> and <depth> indicate the size of 190 the region to return. These arguments have the same meaning as for 191 CompressedTexSubImage3D, though there are extra restrictions, described 192 in the errors section below. 193 194 The mapping between the <xoffset>, <yoffset>, <zoffset>, <width>, 195 <height>, and <depth> parameters and the faces, layers, and layer-faces 196 for cube map, array, and cube map array textures is the same as for 197 GetTextureSubImage. 198 199 The <xoffset>, <yoffset>, <zoffset>, <width>, <height> and <depth> 200 values and must be multiples of the values of 201 PACK_COMPRESSED_BLOCK_WIDTH, PACK_COMPRESSED_BLOCK_HEIGHT, and 202 PACK_COMPRESSED_BLOCK_DEPTH respectively, unless the offset is zero and 203 the corresponding size is the same as the texture size in that 204 dimension. 205 206 Pixel storage modes are treated as for GetCompressedTexSubImage. The 207 texel at (<xoffset>, <yoffset>, <zoffset>) will be stored at the 208 location indicated by <pixels> and the current pixel packing parameters. 209 210 Errors 211 212 In addition to the same errors generated by GetTextureSubImage with 213 corresponding parameters: 214 215 An INVALID_VALUE error is generated if <xoffset>, <yoffset> or <zoffset> 216 is not a multiple of the compressed block width, height or depth. 217 218 An INVALID_VALUE error is generated if <width>, <height> or <depth> is 219 not a multiple of the compressed block width, height or depth 220 respectively, unless the offset is zero and the size equals the texture 221 image size. 222 223Additions to the AGL/EGL/GLX/WGL Specifications 224 225 None 226 227Dependencies on GL and ES profiles, versions, and other extensions 228 229 If texture arrays are not supported, ignore references to 230 1D and 2D-array textures 231 232 If cube map textures are not supported, ignore references to 233 cube map textures. 234 235 If cube map arrays texture are not supported, ignore references to 236 cube map array textures. 237 238 If texture rectangles are not supported, ignore references to 239 rectangle textures. 240 241 If texture compression is not supported, ignore references to 242 GetCompressedTexSubImage. 243 244Dependencies on ARB_direct_state_access 245 246 If ARB_direct_state_access is not supported, the TEXTURE_TARGET 247 is the <target> that <texture> was initially bound with. 248 249New State 250 251 None. 252 253New Implementation Dependent State 254 255 None. 256 257Conformance Testing 258 259 1) For each type of texture, create a test texture. Read back the 260 whole texture into a buffer with glGet[Compressed]TexImage. Then 261 read back the whole texture into a second buffer, but in sub-image 262 pieces (ex: 4x4 grid). Then compare the two result buffers - they 263 should be identical. 264 265Issues 266 267 1) Why is this extension necessary? 268 269 RESOLVED: In some cases one can wrap a texture with an FBO and 270 read back sub-regions with glReadPixels. However, that doesn't 271 work for all texture formats (esp. compressed textures). 272 273 For some textures such as 2D array textures there's no way to obtain 274 just one slice of a texture. It's very inefficient to get the whole 275 texture when just one slice is needed. 276 277 An alternate approach to the problem of reading back sub textures 278 is with an extension such as GL_INTEL_map_texture. However, mapping 279 textures involves several difficult issues. Extending glGetTexImage 280 to handle sub-regions is much simpler. 281 282 2) What is the behavior of these commands if <bufSize> is exceeded 283 when a pixel pack buffer object is bound? 284 285 DISCUSSION: When client memory is being used, INVALID_OPERATION is 286 generated if writing more than <bufSize> bytes is necessary to return 287 all the requested data. Similarly, when a PBO is bound, 288 INVALID_OPERATION is generated if more than <bufSize> bytes are 289 required. Note that it can also be an error if *less* than <bufSize> 290 bytes would be required when using a PBO if the space between the 291 offset indicated by <pixels> and the end of the buffer is insufficient 292 for the requested data. This behavior is inherited from GetTexImage 293 and GetCompressedTexImage. 294 295 3) Is the <target> parameter needed? 296 297 RESOLVED. No. The target is determined by the texture type. 298 For cube map textures the face target is determined by the 299 <zoffset> and <depth> parameters by mapping layer numbers to 300 cube map texture faces as per Table 9.2. This is consisten 301 with the DSA variants of GetTextureImage in ARB_direct_state_access 302 which do not include it. 303 304Revision History 305 306 Revision 1, 2014/02/03 307 - Initial revision 308 309 Revision 2, 2014/04/10 310 - Converted GetTexSubImage and GetTexCompressedSubImage to 311 DSA (Direct State Access) style. 312 - Added bufSize parameter, per GL_ARB_robustness convention. 313 314 Revision 3, 2014/05/26 - dkoch 315 - convert to ARB extension 316 - make function naming and parameter lists consistent 317 - describe the <bufSize> parameter (issue 2). 318 - remove the <target> parameter (issue 3) and fallout. 319 - better describe valid texture types and parameter meanings 320 for the various texture types. 321 322 Revision 4, 2014/05/30 - dkoch 323 - describe implied <target> parameter for cube map textures 324 - fix remove incorrect <bufSize> language (Bug 12321) 325 - Add additional error language 326 - improve issues 2 and 3 327 328 Revision 5, 2014/06/03 - Jon Leech 329 - Use 'pixels' instead of 'img' as formal parameter name for 330 consistency with API spec / dsa. 331 332 Revision 6, 2014/06/12 - Jon Leech 333 - Sync with core API spec language and errors. 334 335 Revision 6, 2014/06/16 - Jon Leech 336 - Require GetTextureSubImage for cube map textures to respect the 337 three-dimensional pixel pack state, by referring to GetTextureImage 338 language (Bug 12329). 339