1Name 2 3 NV_copy_image 4 5Name Strings 6 7 GL_NV_copy_image 8 WGL_NV_copy_image 9 GLX_NV_copy_image 10 11Contact 12 13 Michael Gold, NVIDIA Corporation (gold 'at' nvidia.com) 14 15Contributors 16 17 Jeff Bolz, NVIDIA Corporation (jbolz 'at' nvidia.com) 18 James Jones, NVIDIA Corporation (jajones 'at' nvidia.com) 19 Joe Kain, NVIDIA Corporation (jkain 'at' nvidia.com) 20 Benjamin Morris, NVIDIA Corporation (bmorris 'at' nvidia.com) 21 Michael Morrison, NVIDIA Corporation (mmorrison 'at' nvidia.com) 22 Aaron Plattner, NVIDIA Corporation (aplattner 'at' nvidia.com) 23 Thomas Volk, NVIDIA Corporation (tvolk 'at' nvidia.com) 24 Eric Werness, NVIDIA Corporation (ewerness 'at' nvidia.com) 25 Shazia Rahman, NVIDIA Corporation (srahman 'at' nvidia.com) 26 27Status 28 29 Shipping (July 2009, Release 190) 30 31Version 32 33 Last Modified Date: 8/7/2012 34 NVIDIA revision: 5 35 36Number 37 38 376 39 40Dependencies 41 42 OpenGL 1.1 is required. 43 44 The extension is written against the OpenGL 3.1 Specification. 45 46Overview 47 48 This extension enables efficient image data transfer between image 49 objects (i.e. textures and renderbuffers) without the need to bind 50 the objects or otherwise configure the rendering pipeline. The 51 WGL and GLX versions allow copying between images in different 52 contexts, even if those contexts are in different sharelists or 53 even on different physical devices. 54 55New Procedures and Functions 56 57 void CopyImageSubDataNV( 58 uint srcName, enum srcTarget, int srcLevel, 59 int srcX, int srcY, int srcZ, 60 uint dstName, enum dstTarget, int dstLevel, 61 int dstX, int dstY, int dstZ, 62 sizei width, sizei height, sizei depth); 63 64New Tokens 65 66 None 67 68Additions to Chapter 4 of the OpenGL 3.1 Specification (Per-Fragment 69Operations and the Frame Buffer) 70 71 Append to section 4.3.3: 72 73 The function 74 75 void CopyImageSubDataNV( 76 uint srcName, enum srcTarget, int srcLevel, 77 int srcX, int srcY, int srcZ, 78 uint dstName, enum dstTarget, int dstLevel, 79 int dstX, int dstY, int dstZ, 80 sizei width, sizei height, sizei depth); 81 82 may be used to copy a region of texel data between two image 83 objects. An image object may be either a texture or a 84 renderbuffer. 85 86 The source object is identified by <srcName> and <srcTarget>. 87 Similarly the destination object is identified by <dstName> and 88 <dstTarget>. The interpretation of the name depends on the value 89 of the corresponding target parameter. If the target parameter is 90 RENDERBUFFER, the name is interpreted as the name of a 91 renderbuffer object. If the target parameter is a texture target, 92 the name is interpreted as a texture object. All non-proxy 93 texture targets are accepted, with the exception of TEXTURE_BUFFER 94 and the cubemap face selectors described in table 3.23. 95 96 <srcLevel> and <dstLevel> identify the source and destination 97 level of detail. For textures, this must be a valid level of 98 detail in the texture object. For renderbuffers, this value must 99 be zero. 100 101 <srcX>, <srcY>, and <srcZ> specify the lower left texel 102 coordinates of a <width>-wide by <height>-high by <depth>-deep 103 rectangular subregion of the source texel array. Negative values 104 of <srcX>, <srcY>, and <srcZ> correspond to the coordinates of 105 border texels, addressed as in figure 3.10. Similarly, <dstX>, 106 <dstY> and <dstZ> specify the coordinates of a subregion of the 107 destination texel array. The source and destination subregions 108 must be contained entirely within the specified level of the 109 corresponding image objects. 110 111 Slices of a TEXTURE_1D_ARRAY, TEXTURE_2D_ARRAY, TEXTURE_3D and 112 faces of TEXTURE_CUBE_MAP are all compatible provided they share 113 an internal format, and multiple slices or faces may be copied 114 between these objects with a single call by specifying the 115 starting slice with <srcZ> and <dstZ>, and the number of slices to 116 be copied with <depth>. Cubemap textures always have six faces 117 which are selected by a zero-based face index, according to the 118 order specified in table 3.23. 119 120 CopyImageSubDataNV may fail with any of the following errors: 121 INVALID_ENUM is generated if either target is not RENDERBUFFER or 122 a valid non-proxy texture target, or is TEXTURE_BUFFER, or is one 123 of the cubemap face selectors described in table 3.23, or if the 124 target does not match the type of the object. INVALID_OPERATION 125 is generated if either object is a texture and the texture is not 126 consistent, or if the source and destination internal formats or 127 number of samples do not match. INVALID_VALUE is generated if 128 either name does not correspond to a valid renderbuffer or texture 129 object according to the corresponding target parameter, or if the 130 specified level is not a valid level for the image, or if the 131 dimensions of the either subregion exceeds the boundaries of the 132 corresponding image object, or if the image format is compressed 133 and the dimensions of the subregion fail to meet the alignment 134 constraints of the format. 135 136************************************************************************ 137 138Additions to the WGL Specification 139 140 The function 141 142 BOOL wglCopyImageSubDataNV( 143 HGLRC hSrcRC, uint srcName, enum srcTarget, int srcLevel, 144 int srcX, int srcY, int srcZ, 145 HGLRC hDstRC, uint dstName, enum dstTarget, int dstLevel, 146 int dstX, int dstY, int dstZ, 147 sizei width, sizei height, sizei depth); 148 149 behaves identically to the core function glCopyImageSubDataNV, 150 except that the <hSrcRC> and <hDstRC> parameters specify the 151 contexts in which to look up the source and destination objects, 152 respectively. A value of zero indicates that the currently bound 153 context should be used instead. 154 155 Upon success, the value TRUE is returned. Upon failure, the value 156 FALSE is returned, and the system error code will be set to one of 157 the following: 158 159 ERROR_INVALID_HANDLE indicates that either of <hSrcRC> or 160 <hDstRC> is non-zero and is not recognized by the 161 implementation as a valid context, or is zero and there is no 162 valid context bound in the current thread. 163 164 ERROR_INVALID_OPERATION indicates that the call failed, and if 165 either the source or the destination context is bound in the 166 current thread, a GL error code is set to indicate the cause. 167 This error code may be retrieved by calling glGetError(). If 168 neither the source nor the destination context is bound in the 169 current thread, no GL error is set. 170 171Additions to the GLX Specification 172 173 The function 174 175 void glXCopyImageSubDataNV(Display *dpy, 176 GLXContext srcCtx, uint srcName, enum srcTarget, int srcLevel, 177 int srcX, int srcY, int srcZ, 178 GLXContext dstCtx, uint dstName, enum dstTarget, int dstLevel, 179 int dstX, int dstY, int dstZ, 180 sizei width, sizei height, sizei depth); 181 182 behaves identically to the core function glCopyImageSubDataNV, 183 except that the <srcCtx> and <dstCtx> parameters specify the 184 contexts in which to look up the source and destination objects, 185 respectively. A value of NULL for either context indicates that 186 the value which is returned by glXGetCurrentContext() should be 187 used instead. Both contexts must share the same address space, as 188 described in section 2.3. 189 190 If either <srcCtx> or <dstCtx> is not a valid rendering context, 191 the error GLXBadContext is generated. 192 193 If the server portion of the contexts do not share the same 194 address space, the error BadMatch is generated. 195 196 If an error occurs due to GL parameter validation, the error 197 BadMatch will be generated. Additionally, if either the source or 198 destination context is bound to the current thread, a GL error is 199 set to indicate the cause. This error code may be retrieved by 200 calling glGetError(). If neither the source nor the destination 201 context is bound in the current thread, no GL error is set. 202 203GLX Protocol 204 205 One new GLX protocol command is added. 206 207 glXCopyImageSubDataNV 208 1 CARD8 opcode (X assigned) 209 1 16 GLX opcode (glXVendorPrivate) 210 2 20 request length 211 4 1360 vendor specific opcode 212 4 unused 213 4 GLX_CONTEXT src_context 214 4 CARD32 src_name 215 4 ENUM src_target 216 4 INT32 src_level 217 4 INT32 src_x 218 4 INT32 src_y 219 4 INT32 src_z 220 4 GLX_CONTEXT dst_context 221 4 CARD32 dst_name 222 4 ENUM dst_target 223 4 INT32 dst_level 224 4 INT32 dst_x 225 4 INT32 dst_y 226 4 INT32 dst_z 227 4 INT32 width 228 4 INT32 height 229 4 INT32 depth 230 231 The following rendering command is sent to the server as a part of 232 glXRender request: 233 234 CopyImageSubDataNV 235 2 64 rendering command length 236 2 4291 rendering command opcode 237 4 CARD32 src_name 238 4 ENUM src_target 239 4 INT32 src_level 240 4 INT32 src_x 241 4 INT32 src_y 242 4 INT32 src_z 243 4 CARD32 dst_name 244 4 ENUM dst_target 245 4 INT32 dst_level 246 4 INT32 dst_x 247 4 INT32 dst_y 248 4 INT32 dst_z 249 4 INT32 width 250 4 INT32 height 251 4 INT32 depth 252 253Dependencies on EXT_extension_name 254 255 The list of supported image targets depends on the availability of 256 such targets in the implementation. 257 258Errors 259 260 CopyImageSubDataNV may fail with any of the following errors: 261 INVALID_ENUM is generated if either target is not RENDERBUFFER or 262 a valid non-proxy texture target, or is TEXTURE_BUFFER, or is one 263 of the cubemap face selectors described in table 3.23, or if the 264 target does not match the type of the object. INVALID_OPERATION 265 is generated if either object is a texture and the texture is not 266 consistent, or if the source and destination internal formats or 267 number of samples do not match. INVALID_VALUE is generated if 268 either name does not correspond to a valid renderbuffer or texture 269 object according to the corresponding target parameter, or if the 270 specified level is not a valid level for the image, or if the 271 dimensions of the either subregion exceeds the boundaries of the 272 corresponding image object, or if the image format is compressed 273 and the dimensions of the subregion fail to meet the alignment 274 constraints of the format. 275 276Sample Code 277 278 TBD 279 280Issues 281 2821) Should there be a single function for all image types, or 283 "per-dimensional" functions? 284 285 Resolved. 286 287 A single function can support all image types. Not only are 288 per-dimensional functions an unnecessary convenience, they also 289 restrict some of the flexibility offered by this extension, 290 e.g. copying a slice of data between a 2D and a 3D image. 291 2922) Should the extension support "deep copies", i.e. multiple slices of 293 a 3D texture, a 2D array texture, or a cubemap? 294 295 Resolved. 296 297 Yes, there may be performance advantages in copying a multiple 298 slices in a single call. 299 3003) Should renderbuffers be supported by the same function as textures? 301 302 Resolved. 303 304 Yes, there is no fundamental difference between the two object 305 classes, and allowing them to be used interchangeably has the 306 advantage of allowing data transfers between them. 307 3084) Is the "target" parameter necessary? 309 310 Resolved. 311 312 Yes, given the current object model and texture API, there are two 313 obvious applications of the target parameter: 314 315 1) Allows the selection of a single cubemap face. 316 2) Differentiate between TEXTURE and RENDERBUFFER targets. 317 3185) Should the target TEXTURE_CUBE_MAP be supported, and with what 319 behavior? 320 321 Resolved. 322 323 Given the resolution of issue 7, this is moot. The 324 TEXTURE_CUBE_MAP token is the only way to access a cubemap. 325 3266) Should the "extra" parameters for a given dimension be ignored, or 327 should there be required values? 328 329 Resolved. 330 331 All parameters are required to have sensible values, for the 332 simple reason that future extensions may give meaning to these 333 values. For dimensions which are currently superfluous, the 334 offset must be zero and the size must be one, e.g. if the target 335 is TEXTURE_2D, z must be 0 and depth must be 1. 336 3377) Should the per-face cubemap targets be accepted at all? Why not 338 use Z as the selector? 339 340 Resolved. 341 342 The existing per-face targets effectively define the face order: 343 344 face_index = face_target - TEXTURE_CUBE_MAP_POSITIVE_X; 345 346 Therefore it makes sense to generalize a cubemap as an array of 347 size 6, and use the Z parameter to select the face(s). 348 3498) Should the WGL/GLX functions accept a source context as well as a 350 destination context? 351 352 Resolved. 353 354 Yes, the symmetry and flexibility this offers has advantages, and 355 there is no obvious technical reason to disallow this. 356 357Revision History 358 359 Rev. Date Author Changes 360 ---- -------- -------- ----------------------------------------- 361 1 gold Internal revisions. 362 2 09/09/09 mjk Assign number 363 3 09/16/09 Jon Leech Fix hDstRC->hSrcRC in prototype. 364 4 10/13/11 srahman Added protocol for the GL command. 365 5 08/07/12 pbrown Fix the GLX protocol section to clarify that 366 the first set of protocol is for 367 glXCopyImageSubDataNV and not the GL command. 368