1Name 2 3 ARB_invalidate_subdata 4 5Name Strings 6 7 GL_ARB_invalidate_subdata 8 9Contact 10 11 Jeff Bolz, NVIDIA Corporation (jbolz 'at' nvidia.com) 12 13Contributors 14 15 Michael Gold, NVIDIA Corporation 16 Bruce Merry 17 Pat Brown, NVIDIA Corporation 18 19Notice 20 21 Copyright (c) 2012-2013 The Khronos Group Inc. Copyright terms at 22 http://www.khronos.org/registry/speccopyright.html 23 24Specification Update Policy 25 26 Khronos-approved extension specifications are updated in response to 27 issues and bugs prioritized by the Khronos OpenGL Working Group. For 28 extensions which have been promoted to a core Specification, fixes will 29 first appear in the latest version of that core Specification, and will 30 eventually be backported to the extension document. This policy is 31 described in more detail at 32 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 33 34Status 35 36 Complete. 37 Approved by the ARB on 2012/06/12. 38 39Version 40 41 Last Modified Date: July 30, 2012 42 Revision: 5 43 44Number 45 46 ARB Extension #132 47 48Dependencies 49 50 This extension is written against the OpenGL 3.2 specification 51 (Compatibility profile). 52 53 OpenGL 2.0 is required. 54 55 This extension interacts with OpenGL ES 2.0. 56 57 58Overview 59 60 This extension adds a mechanism for an application to tell the GL that 61 the previous contents of a subregion of an image or a range of a buffer 62 may be invalidated. 63 64 GL implementations often include several memory spaces, each with 65 distinct performance characteristics, and the implementations 66 transparently move allocations between memory spaces. With this 67 extension, an application can tell the GL that the contents of a texture 68 or buffer are no longer needed, and the implementation can avoid 69 transferring the data unnecessarily. 70 71 Examples of when this may be useful include: 72 73 (1) invalidating a multisample texture after resolving it into a non- 74 multisample texture. 75 76 (2) invalidating depth/stencil buffers after using them to generate a color 77 buffer. 78 79 (3) invalidating a subregion of a framebuffer rather than clearing it 80 before rendering to it, when the whole subregion will be overwritten. 81 82 (4) invalidating dynamically generated data (e.g. textures written by FBO 83 rendering or CopyTexSubImage, buffers written by transform feedback, 84 etc.) after it is no longer needed but before the end of the frame. 85 86 It is expected that the situations in which the GL will take advantage of 87 this knowledge and achieve increased performance as a result of its use 88 will be implementation-dependent. The first three examples may show 89 benefit on tiled renderers where some data won't need to be copied into 90 or out of on-chip memory. The fourth example may show a benefit in multi- 91 GPU systems where some data won't need to be copied between GPUs. 92 93 This extension is a superset of the EXT_discard_framebuffer extension 94 with the following additions: 95 96 - The parameters to InvalidateFramebufferEXT are extended for MRT support 97 and Desktop-GL-only buffer enums. 98 99 - New functions to invalidate a region of a texture image or buffer object 100 data store. 101 102 103New Procedures and Functions 104 105 void InvalidateTexSubImage(uint texture, int level, 106 int xoffset, int yoffset, int zoffset, 107 sizei width, sizei height, sizei depth); 108 void InvalidateTexImage(uint texture, int level); 109 110 void InvalidateBufferSubData(uint buffer, intptr offset, sizeiptr length); 111 void InvalidateBufferData(uint buffer); 112 113 void InvalidateFramebuffer(enum target, 114 sizei numAttachments, 115 const enum *attachments); 116 void InvalidateSubFramebuffer(enum target, 117 sizei numAttachments, 118 const enum *attachments, 119 int x, int y, sizei width, sizei height); 120 121 122New Tokens 123 124 None. 125 126 127Additions to Chapter 2 of the OpenGL 3.2 Specification (OpenGL Operation) 128 129 Add a new Section 2.9.X (Invalidating Buffer Data) 130 131 Invalidating Buffer Data 132 133 All or part of the data store of a buffer object may be invalidated by 134 calling 135 136 void InvalidateBufferSubData(uint buffer, intptr offset, sizeiptr length); 137 138 with <buffer> set to the name of the buffer whose data store is being 139 invalidated. <offset> and <length> specify the range of the data in the 140 buffer object that is to be invalidated. If <buffer> is zero or is not the 141 name of a buffer, the error INVALID_VALUE is generated. An INVALID_VALUE 142 error is generated if <offset> or <length> is negative, or if <offset> + 143 <length> is greater than the value of BUFFER_SIZE. An INVALID_OPERATION 144 error is generated if the buffer is currently mapped by MapBuffer, or if 145 the invalidate range intersects the range currently mapped by 146 MapBufferRange. After this command, data in the specified range have 147 undefined values. 148 149 The command 150 151 void InvalidateBufferData(uint buffer); 152 153 is equivalent to calling InvalidateBufferSubData with <offset> equal to 154 zero and <length> equal to the value of BUFFER_SIZE. 155 156 157Additions to Chapter 3 of the OpenGL 3.2 Specification (Rasterization) 158 159 Add a new Section 3.9.X (Invalidating Texture Image Data) 160 161 Invalidating Texture Image Data 162 163 All or part of a texture image may be invalidated by calling 164 165 void InvalidateTexSubImage(uint texture, int level, 166 int xoffset, int yoffset, int zoffset, 167 sizei width, sizei height, sizei depth); 168 169 with <texture> and <level> indicating which texture image is being 170 invalidated. After this command, data in that subregion have undefined 171 values. <xoffset>, <yoffset>, <zoffset>, <width>, <height>, and <depth> 172 are interpreted as they are in TexSubImage3D. For texture targets that 173 don't have certain dimensions, this command treats those dimensions as 174 having a size of 1. For example, to invalidate a portion of a two- 175 dimensional texture, the application would use <zoffset> equal to zero and 176 <depth> equal to one. Cube map textures are treated as an array of six 177 slices in the z-dimension, where a value of <zoffset> is interpreted as 178 specifying face TEXTURE_CUBE_MAP_POSITIVE_X + <zoffset>. 179 180 If <level> is less than zero or greater than the base 2 logarithm of the 181 maximum texture width, height, or depth, the error INVALID_VALUE is 182 generated. The arguments <xoffset>, <yoffset>, <zoffset>, <width>, 183 <height>, and <depth> generate the same errors as in the TexSubImage 184 commands. That is, the specified subregion must be between -<b> and 185 <dim>+<b> where <dim> is the size of the dimension of the texture image, 186 and <b> is the size of the border of that texture image, otherwise 187 INVALID_VALUE is generated (border is not applied to dimensions that don't 188 exist in a given texture target). If <texture> is zero or is not the name 189 of a texture, the error INVALID_VALUE is generated. It is not possible to 190 invalidate a portion of a default texture. If the target of <texture> is 191 TEXTURE_RECTANGLE, TEXTURE_BUFFER, TEXTURE_2D_MULTISAMPLE, or 192 TEXTURE_2D_MULTISAMPLE_ARRAY, and <level> is not zero, the error 193 INVALID_VALUE is generated. 194 195 The command 196 197 void InvalidateTexImage(uint texture, int level); 198 199 is equivalent to calling InvalidateTexSubImage with <xoffset>, <yoffset>, 200 and <zoffset> equal to <-b> and <width>, <height>, and <depth> equal to 201 the dimensions of the texture image plus 2*<b> (or zero and one for 202 dimensions the texture doesn't have). 203 204 205Additions to Chapter 4 of the OpenGL 3.2 Specification (Per-Fragment Operations 206and the Frame Buffer) 207 208 Add a new section 4.5 (Invalidating Framebuffer Contents) 209 210 The GL provides a means for invalidating portions of every pixel or a 211 subregion of pixels in a particular buffer, effectively leaving their 212 contents undefined. The command 213 214 void InvalidateSubFramebuffer(enum target, 215 sizei numAttachments, 216 const enum *attachments 217 int x, int y, sizei width, sizei height); 218 219 effectively signals to the GL that it need not preserve all contents of 220 a bound framebuffer object. <numAttachments> indicates how many 221 attachments are supplied in the <attachments> list. If <numAttachments> 222 is less than zero, the error INVALID_VALUE is generated. If an attachment 223 is specified that does not exist in the framebuffer bound to <target>, it 224 is ignored. <target> must be FRAMEBUFFER, DRAW_FRAMEBUFFER, or 225 READ_FRAMEBUFFER. FRAMEBUFFER is treated as DRAW_FRAMEBUFFER. <x> and <y> 226 are the origin (with lower left-hand corner at (0,0)) and <width> and 227 <height> are the width and height, respectively, of the pixel rectangle to 228 be invalidated. Any of these pixels lying outside of the window allocated 229 to the current GL context, or outside of the attachments of the currently 230 bound framebuffer object, are ignored. 231 232 If a framebuffer object is bound to <target>, then elements of 233 <attachments> must be COLOR_ATTACHMENTi, DEPTH_ATTACHMENT, or 234 STENCIL_ATTACHMENT, otherwise the error INVALID_ENUM is generated. If the 235 framebuffer object is not complete, InvalidateFramebuffer may be ignored. 236 If <attachments> contains COLOR_ATTACHMENTm and m is greater than or equal to 237 the value of MAX_COLOR_ATTACHMENTS, then the error INVALID_OPERATION is 238 generated. 239 240 If the default framebuffer is bound to <target>, then elements of 241 <attachments> must be any of: 242 243 - FRONT_LEFT, FRONT_RIGHT, BACK_LEFT, BACK_RIGHT, AUXi, and ACCUM, 244 identifying that specific buffer; 245 - COLOR, which is treated as BACK_LEFT for a double-buffered context 246 and FRONT_LEFT for a single-buffered context; 247 - DEPTH, identifying the depth buffer; 248 - STENCIL, identifying the stencil buffer; 249 250 otherwise the error INVALID_ENUM is generated. 251 252 The command 253 254 void InvalidateFramebuffer(enum target, 255 sizei numAttachments, 256 const enum *attachments); 257 258 is equivalent to the command InvalidateSubFramebuffer with <x>, 259 <y>, <width>, <height> equal to 0, 0, <MAX_VIEWPORT_DIMS[0]>, 260 <MAX_VIEWPORT_DIMS[1]> respectively. 261 262 263Additions to Chapter 5 of the OpenGL 3.2 Specification (Special Functions) 264 265 None. 266 267Additions to Chapter 6 of the OpenGL 3.2 Specification (State and 268State Requests) 269 270 None. 271 272Additions to the OpenGL Shading Language Specification 273 274 None. 275 276Additions to the AGL/GLX/WGL Specifications 277 278 None. 279 280Errors 281 282 XXX TODO 283 284 285Dependencies on OpenGL ES 2.0 286 287 If this extension is implemented on OpenGL ES 2.0, the following 288 simplifications apply: 289 290 - Only COLOR_ATTACHMENT0, DEPTH_ATTACHMENT, STENCIL_ATTACHMENT, COLOR_EXT, 291 DEPTH_EXT, and STENCIL_EXT are accepted in InvalidateSubFramebuffer and 292 InvalidateFramebuffer. COLOR_EXT, DEPTH_EXT, and STENCIL_EXT are defined 293 by EXT_discard_framebuffer. 294 295 - Bordered textures are not supported, so the subregion in 296 InvalidateTexSubImage must be between 0 and <dim>. 297 298 - 3D textures are not supported, so that language in InvalidateTexSubImage 299 doesn't apply. 300 301 - MapBuffer(Range) are not supported, so that error check is removed from 302 InvalidateBufferSubData and InvalidateBufferData. 303 304 - READ_FRAMEBUFFER/DRAW_FRAMEBUFFER are not accepted by 305 Invalidate(Sub)Framebuffer. 306 307New State 308 309 None. 310 311New Implementation Dependent State 312 313 None. 314 315Examples 316 317 XXX TODO 318 319 320Issues 321 322 (1) Should these commands use <target> or <name> to specify the object? 323 324 RESOLVED: Use <name> for textures and buffers, to avoid requiring the 325 application to disturb any bindings in order to use it. 326 Invalidate(Sub)Framebuffer only applies to the currently bound draw or 327 read framebuffers. 328 329 (2) Should Invalidate(Sub)Framebuffer have any accommodations for 330 invalidating a range in the z-dimension for a 3D or layered texture? 331 332 RESOLVED: No, all layers are invalidated, the same behavior as a Clear. 333 An application can use InvalidateTexSubImage to invalidate a subregion in 334 the z-dimension. 335 336 (3) Should Invalidate(Sub)Framebuffer be able to use the READ_FRAMEBUFFER 337 binding? 338 339 RESOLVED: Yes. One common use case for Invalidate(Sub)Framebuffer is to 340 invalidate the contents of a multisample buffer immediately after using 341 BlitFramebuffer to resolve it. At this point, the multisample buffer will 342 be attached to the current READ_FRAMEBUFFER, so invalidating it is as easy 343 as 344 345 InvalidateFramebuffer(READ_FRAMEBUFFER, 1, [COLOR_ATTACHMENTi]); 346 347 This is a superset of the EXT_discard_framebuffer extension which only 348 allowed FRAMEBUFFER since GLES 2.0 does not support separate read/draw 349 targets. 350 351 (4) Should there be special handling for mapped buffers or buffers in use 352 by transform feedback? These are two cases where a buffer is being 353 written to over a period of time. 354 355 RESOLVED: Raise an error for Invalidate on mapped buffers, but not for 356 transform feedback. 357 358 For mapped buffers, the GL doesn't know the order of the CPU writes 359 versus the invalidate. i.e. it can't distinguish between "write then 360 Invalidate then Unmap" vs "Invalidate then write then Unmap". Trying to order 361 Invalidates against CPU writes would additionally require Invalidates to be 362 processed synchronously. Mapped buffers already provide a means to 363 invalidate via the ARB_map_buffer_range extension. 364 365 For transform feedback, the GL is in control of when writes occur to the 366 attached buffers, and therefore knows when writes occur relative to the 367 Invalidate commands. So Invalidates are well-defined in this case. It's 368 desirable to have this resolved in the same way as textures bound to an 369 FBO, which we also leave as well-defined. 370 371 (5) Should we have a way to invalidate renderbuffers by name? 372 373 RESOLVED: No. 374 375 OpenGL 3.2 adds support for multisample textures, so there isn't any 376 reason for renderbuffers to exist anymore. However, some GL ES 377 implementations may wish to implement this extension in an environment 378 where ARB_texture_multisample is not supported and renderbuffers are the 379 only way to get a multisample image. There are multiple options here: 380 381 - Add a new command for invalidating contents of a renderbuffer. 382 383 - Add a <target> parameter to Invalidate*Image to distinguish between 384 texture names and renderbuffer names. 385 386 - Hope that Invalidate(Sub)Framebuffer is sufficient, which it is at 387 least for the use case described in issue (3). 388 389 We choose the third option, and recommend using multisample textures 390 going forward. 391 392 (6) Should the subregion for InvalidateSubFramebuffer be explicitly 393 specified, or re-use the Scissor? 394 395 RESOLVED: Explicitly specified in coordinates similar to Scissor, but 396 not reusing the Scissor state. The Scissor is a fragment operation and 397 InvalidateSubFramebuffer does not generate fragments, so it's more 398 logical to have a separate rectangle. 399 400 (7) Do we need Sub/non-Sub versions of InvalidateFramebuffer? 401 402 RESOLVED: Yes, to make this extension a superset of 403 EXT_discard_framebuffer. Strictly speaking the answer is "no", because 404 an application can use values of (0,0,maxViewport[0],maxViewport[1]) to 405 invalidate entire images. This is in contrast to the buffer and texture 406 commands that error-check the parameters against the size of the data 407 store. 408 409 Since window-system framebuffers can change size asynchronously, we don't 410 want to error-check the parameters of InvalidateSubFramebuffer. However, 411 InvalidateBufferSubData and InvalidateTexSubImage should error-check to 412 be consistent with MapBufferRange and TexSubImage. 413 414 415Revision History 416 417 Rev. Date Author Changes 418 ---- -------- -------- ----------------------------------------- 419 1 10/01/10 jbolz Internal revisions. 420 2 01/12/12 jbolz Updates to match ES. 421 3 04/16/12 pbrown Fix the error for <level>!=0 on rectangle, 422 buffer and multisample textures to refer to 423 the target of <texture> instead of a <target> 424 parameter. 425 4 05/08/12 pbrown Fix typo in spec language describing the 426 interpretation of <zoffset> for cube maps. 427 5 07/30/12 jbolz Add missing error for <buffer>==0. 428 429