1Name 2 3 ARB_copy_image 4 5Name Strings 6 7 GL_ARB_copy_image 8 9Contact 10 11 Michael Gold, NVIDIA Corporation (gold 'at' nvidia.com) 12 Graham Sellers, AMD (graham.sellers 'at' amd.com) 13 14Contributors 15 16 Jeff Bolz, NVIDIA Corporation (jbolz 'at' nvidia.com) 17 James Jones, NVIDIA Corporation (jajones 'at' nvidia.com) 18 Joe Kain, NVIDIA Corporation (jkain 'at' nvidia.com) 19 Benjamin Morris, NVIDIA Corporation (bmorris 'at' nvidia.com) 20 Michael Morrison, NVIDIA Corporation (mmorrison 'at' nvidia.com) 21 Aaron Plattner, NVIDIA Corporation (aplattner 'at' nvidia.com) 22 Mathias Schott, NVIDIA Corporation (mschott 'at' nvidia.com) 23 Thomas Volk, NVIDIA Corporation (tvolk 'at' nvidia.com) 24 Eric Werness, NVIDIA Corporation (ewerness 'at' nvidia.com) 25 Daniel Koch, TransGaming Inc. (daniel 'at' transgaming.com) 26 27Notice 28 29 Copyright (c) 2012-2013 The Khronos Group Inc. Copyright terms at 30 http://www.khronos.org/registry/speccopyright.html 31 32Specification Update Policy 33 34 Khronos-approved extension specifications are updated in response to 35 issues and bugs prioritized by the Khronos OpenGL Working Group. For 36 extensions which have been promoted to a core Specification, fixes will 37 first appear in the latest version of that core Specification, and will 38 eventually be backported to the extension document. This policy is 39 described in more detail at 40 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 41 42Status 43 44 Complete. 45 Approved by the ARB on 2012/06/12. 46 47Version 48 49 Last Modified Date: May 10, 2012 50 Revision: 3 51 52Number 53 54 ARB Extension #123 55 56Dependencies 57 58 OpenGL 1.1 is required. 59 60 The extension is written against the OpenGL 4.2 (Core Profile) Specification. 61 62 This extension interacts with OpenGL 4.3 and ARB_texture_view. 63 64 This extension interacts with the Compatibility Profile. 65 66 This extension interacts with EXT_texture_compression_s3tc. 67 68 This extension interacts with OpenGL 3.0 and ARB_texture_compression_rgtc. 69 70 This extension interacts with OpenGL 4.2 and ARB_texture_compression_bptc. 71 72Overview 73 74 This extension enables efficient image data transfer between image 75 objects (i.e. textures and renderbuffers) without the need to bind 76 the objects or otherwise configure the rendering pipeline. 77 78 This is accomplised by adding a new entry-point CopyImageSubData, 79 which takes a named source and destination. 80 81 CopyImageSubData does not perform general-purpose conversions 82 such as scaling, resizing, blending, color-space, or format 83 conversions. It should be considered to operate in a manner 84 similar to a CPU memcpy, but using the GPU for the copy. 85 86 CopyImageSubData supports copies between images with different 87 internal formats, if the formats are compatible for TextureViews. 88 89 CopyImageSubData also supports copying between compressed and 90 uncompressed images if the compressed block / uncompressed texel 91 sizes are the same. 92 93New Procedures and Functions 94 95 void CopyImageSubData( 96 uint srcName, enum srcTarget, int srcLevel, 97 int srcX, int srcY, int srcZ, 98 uint dstName, enum dstTarget, int dstLevel, 99 int dstX, int dstY, int dstZ, 100 sizei srcWidth, sizei srcHeight, sizei srcDepth); 101 102New Tokens 103 104 None 105 106Additions to Chapter 4 of the OpenGL 4.2 (Core Profile) Specification (Per-Fragment 107Operations and the Frame Buffer) 108 109 Append to section 4.3.2 (Copying Pixels): 110 111 The function 112 113 void CopyImageSubData( 114 uint srcName, enum srcTarget, int srcLevel, 115 int srcX, int srcY, int srcZ, 116 uint dstName, enum dstTarget, int dstLevel, 117 int dstX, int dstY, int dstZ, 118 sizei srcWidth, sizei srcHeight, sizei srcDepth); 119 120 may be used to copy a region of texel data between two image 121 objects. An image object may be either a texture or a 122 renderbuffer. 123 124 CopyImageSubData does not perform general-purpose conversions 125 such as scaling, resizing, blending, color-space, or format 126 conversions. It should be considered to operate in a manner 127 similar to a CPU memcpy. CopyImageSubData can copy between 128 images with different internal formats, provided 129 the formats are compatible. 130 131 CopyImageSubData also allows copying between certain 132 types of compressed and uncompressed internal formats as detailed 133 in Table 4.X.1. This copy does not perform on-the-fly compression 134 or decompression. When copying from an uncompressed internal format 135 to a compressed internal format, each texel of uncompressed data 136 becomes a single block of compressed data. When copying from a 137 compressed internal format to an uncompressed internal format, 138 a block of compressed data becomes a single texel of uncompressed 139 data. The texel size of the uncompressed format must be the same 140 size the block size of the compressed formats. Thus it is permitted 141 to copy between a 128-bit uncompressed format and a compressed 142 format which uses 8-bit 4x4 blocks, or between a 64-bit uncompressed 143 format and a compressed format which uses 4-bit 4x4 blocks. 144 INVALID_OPERATION is generated if the texel size of 145 the uncompressed image is not equal to the block size of the 146 compressed image. 147 148 The source object is identified by <srcName> and <srcTarget>. 149 Similarly the destination object is identified by <dstName> and 150 <dstTarget>. The interpretation of the name depends on the value 151 of the corresponding target parameter. If the target parameter is 152 RENDERBUFFER, the name is interpreted as the name of a 153 renderbuffer object. If the target parameter is a texture target, 154 the name is interpreted as a texture object. All non-proxy 155 texture targets are accepted, with the exception of TEXTURE_BUFFER 156 and the cubemap face selectors described in table 3.17. 157 INVALID_ENUM is generated if either target is not RENDERBUFFER 158 or a valid non-proxy texture target, or is TEXTURE_BUFFER, or is one 159 of the cubemap face selectors described in table 3.17, or if the 160 target does not match the type of the object. INVALID_OPERATION 161 is generated if either object is a texture and the texture is 162 not complete (as defined in section 3.9.14), if the source and 163 destination internal formats are not compatible (see below), 164 or if the number of samples do not match. 165 INVALID_VALUE is generated if either name does not correspond to a 166 valid renderbuffer or texture object according to the corresponding 167 target parameter. 168 169 <srcLevel> and <dstLevel> identify the source and destination 170 level of detail. For textures, this must be a valid level of 171 detail in the texture object. For renderbuffers, this value must 172 be zero. INVALID_VALUE is generated if the specified level is not 173 a valid level for the image. 174 175 <srcX>, <srcY>, and <srcZ> specify the lower left texel 176 coordinates of a <srcWidth>-wide by <srcHeight>-high by 177 <srcDepth>-deep rectangular subregion of the source texel array. 178 (Compatibility Only: Negative values 179 of <srcX>, <srcY>, and <srcZ> correspond to the coordinates of 180 border texels, addressed as in figure 3.10.) Similarly, <dstX>, 181 <dstY> and <dstZ> specify the coordinates of a subregion of the 182 destination texel array. The source and destination subregions 183 must be contained entirely within the specified level of the 184 corresponding image objects. 185 The dimensions are always specified in texels, even for compressed 186 texture formats. But it should be noted that if only one of the 187 source and destination textures is compressed then the number of 188 texels touched in the compressed image will be a factor of the 189 block size larger than in the uncompressed image. 190 INVALID_VALUE is generated if the 191 dimensions of the either subregion exceeds the boundaries of the 192 corresponding image object, or if the image format is compressed 193 and the dimensions of the subregion fail to meet the alignment 194 constraints of the format. 195 196 Slices of a TEXTURE_1D_ARRAY, TEXTURE_2D_ARRAY, TEXTURE_CUBE_MAP_ARRAY 197 TEXTURE_3D and faces of TEXTURE_CUBE_MAP are all compatible provided 198 they share a compatible internal format, and multiple slices or faces 199 may be copied between these objects with a single call by specifying the 200 starting slice with <srcZ> and <dstZ>, and the number of slices to 201 be copied with <srcDepth>. Cubemap textures always have six faces 202 which are selected by a zero-based face index, according to the 203 order specified in table 3.17. 204 205 For the purposes of CopyImageSubData, two internal formats 206 are considered compatible if any of the following conditions are 207 met: 208 * the formats are the same, 209 * the formats are considered compatible according to the 210 compatibility rules used for texture views as defined in 211 section 3.9.X. In particular, if both internal formats are listed 212 in the same entry of Table 3.X.2, they are considered compatible, or 213 * one format is compressed and the other is uncompressed and 214 Table 4.X.1 lists the two formats in the same row. 215 If the formats are not compatible INVALID_OPERATION is generated. 216 217 ------------------------------------------------------------------------ 218 | Texel / | Uncompressed | | 219 | Block | internal format | Compressed internal format | 220 | size | | | 221 ------------------------------------------------------------------------ 222 | 128-bit | RGBA32UI, | COMPRESSED_RGBA_S3TC_DXT3_EXT, | 223 | | RGBA32I, | COMPRESSED_SRGB_ALPHA_S3TC_DXT3_EXT,| 224 | | RGBA32F | COMPRESSED_RGBA_S3TC_DXT5_EXT, | 225 | | | COMPRESSED_SRGB_ALPHA_S3TC_DXT5_EXT,| 226 | | | COMPRESSED_RG_RGTC2, | 227 | | | COMPRESSED_SIGNED_RG_RGTC2, | 228 | | | COMPRESSED_RGBA_BPTC_UNORM, | 229 | | | COMPRESSED_SRGB_ALPHA_BPTC_UNORM, | 230 | | | COMPRESSED_RGB_BPTC_SIGNED_FLOAT, | 231 | | | COMPRESSED_RGB_BPTC_UNSIGNED_FLOAT | 232 ------------------------------------------------------------------------ 233 | 64-bit | RGBA16F, RG32F, | COMPRESSED_RGB_S3TC_DXT1_EXT, | 234 | | RGBA16UI, RG32UI, | COMPRESSED_SRGB_S3TC_DXT1_EXT, | 235 | | RGBA16I, RG32I, | COMPRESSED_RGBA_S3TC_DXT1_EXT, | 236 | | RGBA16, RGBA16_SNORM | COMPRESSED_SRGB_ALPHA_S3TC_DXT1_EXT,| 237 | | | COMPRESSED_RED_RGTC1, | 238 | | | COMPRESSED_SIGNED_RED_RGTC1 | 239 ------------------------------------------------------------------------ 240 241 Table 4.X.1: Compatible internal formats for copying between 242 compressed and uncompressed internal formats with CopyImageSubData. 243 Formats in the same row can be copied between each other. 244 245 246Dependencies on OpenGL 4.3 and ARB_texture_view: 247 248 If OpenGL 4.3 or later and ARB_texture_view are not supported, 249 any references to view-compatible image formats should be removed. 250 251Dependencies on the Compatibility Profile: 252 253 If the Compatibility Profile is not supported, remove any 254 references to negative values for the source dimensions and 255 to border texels. 256 257Dependencies on EXT_texture_compression_s3tc: 258 259 If EXT_texture_compression_s3tc is not supported, remove any 260 references to S3TC compressed texture formats. 261 262Dependencies on OpenGL 3.0 and ARB_texture_compression_rgtc: 263 264 If OpenGL 3.0 or later, and ARB_texture_compression_rgtc is not 265 supported, remove any references to the RGTC compressed texture 266 formats. 267 268Dependencies on OpenGL 4.2 and ARB_texture_compression_bptc: 269 270 If OpenGL 4.2 or later, and ARB_texture_compression_bptc is not 271 supported, remove any references to the BPTC compressed texture 272 formats. 273 274Errors 275 276 CopyImageSubData may fail with any of the following errors: 277 278 INVALID_ENUM is generated 279 * if either <srcTarget> or <dstTarget> 280 - is not RENDERBUFFER or a valid non-proxy texture target 281 - is TEXTURE_BUFFER, or 282 - is one of the cubemap face selectors described in table 3.17, 283 * if the target does not match the type of the object. 284 285 INVALID_OPERATION is generated 286 * if either object is a texture and the texture is not complete, 287 * if the source and destination formats are not compatible, 288 * if the source and destination number of samples do not match, 289 * if one image is compressed and the other is uncompressed and the 290 block size of compressed image is not equal to the texel size 291 of the compressed image. 292 293 INVALID_VALUE is generated 294 * if either <srcName> or <dstName> does not correspond to a valid 295 renderbuffer or texture object according to the corresponding 296 target parameter, or 297 * if the specified level is not a valid level for the image, or 298 * if the dimensions of the either subregion exceeds the boundaries 299 of the corresponding image object, or 300 * if the image format is compressed and the dimensions of the 301 subregion fail to meet the alignment constraints of the format. 302 303Sample Code 304 305 TBD 306 307Issues 308 309 1) Should there be a single function for all image types, or 310 "per-dimensional" functions? 311 312 RESOLVED: A single function can support all image types. Not only are 313 per-dimensional functions an unnecessary convenience, they also 314 restrict some of the flexibility offered by this extension, 315 e.g. copying a slice of data between a 2D and a 3D image. 316 317 2) Should the extension support "deep copies", i.e. multiple slices of 318 a 3D texture, a 2D array texture, or a cubemap? 319 320 RESOLVED: Yes, there may be performance advantages in copying a multiple 321 slices in a single call. 322 323 3) Should renderbuffers be supported by the same function as textures? 324 325 RESOLVED: Yes, there is no fundamental difference between the two object 326 classes, and allowing them to be used interchangeably has the 327 advantage of allowing data transfers between them. 328 329 4) Is the "target" parameter necessary? 330 331 RESOLVED: Yes, given the current object model and texture API, there are 332 two obvious applications of the target parameter: 333 334 1) Allows the selection of a single cubemap face. 335 2) Differentiate between TEXTURE and RENDERBUFFER targets. 336 337 5) Should the target TEXTURE_CUBE_MAP be supported, and with what 338 behavior? 339 340 RESOLVED: Given the resolution of issue 7, this is moot. The 341 TEXTURE_CUBE_MAP token is the only way to access a cubemap. 342 343 6) Should the "extra" parameters for a given dimension be ignored, or 344 should there be required values? 345 346 Resolved. 347 348 All parameters are required to have sensible values, for the 349 simple reason that future extensions may give meaning to these 350 values. For dimensions which are currently superfluous, the 351 offset must be zero and the size must be one, e.g. if the target 352 is TEXTURE_2D, z must be 0 and depth must be 1. 353 354 7) Should the per-face cubemap targets be accepted at all? Why not 355 use Z as the selector? 356 357 Resolved. 358 359 The existing per-face targets effectively define the face order: 360 361 face_index = face_target - TEXTURE_CUBE_MAP_POSITIVE_X; 362 363 Therefore it makes sense to generalize a cubemap as an array of 364 size 6, and use the Z parameter to select the face(s). 365 366 8) How is this extension different from NV_copy_image? 367 368 RESOLVED: This extension does not include the WGL/GLX windowing- 369 layer copy functions. This extension adds the ability to copy 370 between images which have different formats where the formats 371 are compatible for texture views. This extension adds the ability 372 to copy between uncompressed and compressed images if the texel 373 and block sizes are the same. 374 375 9) Please explain copying between compressed and uncompressed images. 376 Is the copy doing compression/decompression on the fly? 377 378 DISCUSSION. The CopyImageSubData does NOT provide any on-the-fly 379 compression, decompression, or even any format conversions. 380 Instead, it provides the ability for an application to implement 381 it's own compressor in a shader by constructing the blocks and 382 writing them out as texels and then copying them to a compressed 383 texture so that it can in turn be used for sampling. 384 385 (10) Is copying from/to images with ETC2/EAC compressed texture formats 386 defined? 387 388 RESOLVED: Only when the source and destination formats are identical, 389 because texture view classes for ETC2/EAC are not defined (see issue 13 390 of the ARB_texture_view specification). 391 392Revision History 393 394 Rev. Date Author Changes 395 ---- -------- -------- ----------------------------------------- 396 1 04/26/2012 gsellers Initial revision based on NV_copy_image. 397 2 05/08/2012 dgkoch Update some references for 4.2 spec 398 Allow copies between view-compatible images. 399 Allow copies between compressed/uncompressed images. 400 Clarify errors, updated overview. 401 3 05/10/2012 dgkoch Clarify dimensions refer to texels in the src image. 402 Re-order/reflow text to make it read better. 403 Add mention of TEXTURE_CUBE_MAP_ARRAY. 404 4 10/08/2013 Jon Leech Add issue 10 discussing why copying 405 involving conversions between ETC2/EAC 406 compressed formats is not supported (Bug 407 11011). 408