1 Name 2 3 ANGLE_framebuffer_blit 4 5 Name Strings 6 7 GL_ANGLE_framebuffer_blit 8 9 Contributors 10 11 Contributors to EXT_framebuffer_blit 12 Daniel Koch, TransGaming Inc. 13 Shannon Woods, TransGaming Inc. 14 Kenneth Russell, Google Inc. 15 Vangelis Kokkevis, Google Inc. 16 17 Contact 18 19 Daniel Koch, TransGaming Inc. (daniel 'at' transgaming 'dot' com) 20 21 Status 22 23 Implemented in ANGLE ES2 24 25 Version 26 27 Last Modified Date: Sept 22, 2012 28 Author Revision: 4 29 30 Number 31 32 OpenGL ES Extension #83 33 34 Dependencies 35 36 OpenGL ES 2.0 is required. 37 38 The extension is written against the OpenGL ES 2.0 specification. 39 40 OES_texture_3D affects the definition of this extension. 41 42 Overview 43 44 This extension modifies framebuffer objects by splitting the 45 framebuffer object binding point into separate DRAW and READ 46 bindings. This allows copying directly from one framebuffer to 47 another. In addition, a new high performance blit function is 48 added to facilitate these blits and perform some data conversion 49 where allowed. 50 51 IP Status 52 53 No known IP claims. 54 55 New Procedures and Functions 56 57 void BlitFramebufferANGLE(int srcX0, int srcY0, int srcX1, int srcY1, 58 int dstX0, int dstY0, int dstX1, int dstY1, 59 bitfield mask, enum filter); 60 61 New Tokens 62 63 Accepted by the <target> parameter of BindFramebuffer, 64 CheckFramebufferStatus, FramebufferTexture2D, FramebufferTexture3DOES, 65 FramebufferRenderbuffer, and 66 GetFramebufferAttachmentParameteriv: 67 68 // (reusing the tokens from EXT_framebuffer_blit) 69 READ_FRAMEBUFFER_ANGLE 0x8CA8 70 DRAW_FRAMEBUFFER_ANGLE 0x8CA9 71 72 Accepted by the <pname> parameters of GetIntegerv and GetFloatv: 73 74 // (reusing the tokens from EXT_framebuffer_blit) 75 DRAW_FRAMEBUFFER_BINDING_ANGLE 0x8CA6 // alias FRAMEBUFFER_BINDING 76 READ_FRAMEBUFFER_BINDING_ANGLE 0x8CAA 77 78 79 Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization) 80 81 Change the last paragraph of section 3.7.2 (Alternate Texture Image 82 Specification Commands) to: 83 84 "Calling CopyTexSubImage3DOES, CopyTexImage2D or CopyTexSubImage2D will 85 result in an INVALID_FRAMEBUFFER_OPERATION error if the object bound 86 to READ_FRAMEBUFFER_BINDING_ANGLE is not "framebuffer complete" 87 (section 4.4.4.2)." 88 89 Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment 90 Operations and the Framebuffer) 91 92 Change the first word of Chapter 4 from "The" to "A". 93 94 Append to the introduction of Chapter 4: 95 96 "Conceptually, the GL has two active framebuffers; the draw 97 framebuffer is the destination for rendering operations, and the 98 read framebuffer is the source for readback operations. The same 99 framebuffer may be used for both drawing and reading. Section 100 4.4.1 describes the mechanism for controlling framebuffer usage." 101 102 Modify the first sentence of the last paragraph of section 4.1.1 as follows: 103 104 "While an application-created framebuffer object is bound to 105 DRAW_FRAMEBUFFER_ANGLE, the pixel ownership test always passes." 106 107 Add to 4.3.1 (Reading Pixels), right before the subsection titled 108 "Obtaining Pixels from the Framebuffer": 109 110 "Calling ReadPixels generates INVALID_FRAMEBUFFER_OPERATION if 111 the object bound to READ_FRAMEBUFFER_BINDING_ANGLE is not "framebuffer 112 complete" (section 4.4.4.2). GetIntegerv generates an INVALID_OPERATION 113 error if the object bound to READ_FRAMEBUFFER_BINDING_ANGLE is not 114 framebuffer complete, or if the GL is using a framebuffer object 115 (i.e. READ_FRAMEBUFFER_BINDING_ANGLE is non-zero) and there is no color 116 attachment." 117 118 Insert a new section 4.3.2 titled "Copying Pixels" and renumber the 119 subsequent sections. Add the following text: 120 121 "BlitFramebufferANGLE transfers a rectangle of pixel values from one 122 region of the read framebuffer to another in the draw framebuffer. 123 124 BlitFramebufferANGLE(int srcX0, int srcY0, int srcX1, int srcY1, 125 int dstX0, int dstY0, int dstX1, int dstY1, 126 bitfield mask, enum filter); 127 128 <mask> is the bitwise OR of a number of values indicating which 129 buffers are to be copied. The values are COLOR_BUFFER_BIT, 130 DEPTH_BUFFER_BIT, and STENCIL_BUFFER_BIT, which are described in 131 section 4.2.3. The pixels corresponding to these buffers are 132 copied from the source rectangle, bound by the locations (srcX0, 133 srcY0) and (srcX1, srcY1), to the destination rectangle, bound by 134 the locations (dstX0, dstY0) and (dstX1, dstY1). The lower bounds 135 of the rectangle are inclusive, while the upper bounds are 136 exclusive. 137 138 The actual region taken from the read framebuffer is limited to the 139 intersection of the source buffers being transferred, which may include 140 the color buffer, the depth buffer, and/or the stencil buffer depending on 141 <mask>. The actual region written to the draw framebuffer is limited to the 142 intersection of the destination buffers being written, which may include 143 the color buffer, the depth buffer, and/or the stencil buffer 144 depending on <mask>. Whether or not the source or destination regions are 145 altered due to these limits, the offset applied to pixels being transferred 146 is performed as though no such limits were present. 147 148 Stretching and scaling during a copy are not supported. If the source 149 and destination rectangle dimensions do not match, no copy is 150 performed and an INVALID_OPERATION error is generated. 151 Because stretching is not supported, <filter> must be NEAREST and 152 no filtering is applied. 153 154 Flipping during a copy is not supported. If either the source or 155 destination rectangle specifies a negative dimension, the error 156 INVALID_OPERATION is generated. If both the source and 157 destination rectangles specify a negative dimension for the same 158 direction, no reversal is required and the operation is supported. 159 160 If the source and destination buffers are identical, and the 161 source and destination rectangles overlap, the result of the blit 162 operation is undefined. 163 164 The pixel copy bypasses the fragment pipeline. The only fragment 165 operations which affect the blit are the pixel ownership test and 166 the scissor test. 167 168 If a buffer is specified in <mask> and does not exist in both the 169 read and draw framebuffers, the corresponding bit is silently 170 ignored. 171 172 Calling BlitFramebufferANGLE will result in an 173 INVALID_FRAMEBUFFER_OPERATION error if the objects bound to 174 DRAW_FRAMEBUFFER_BINDING_ANGLE and READ_FRAMEBUFFER_BINDING_ANGLE are 175 not "framebuffer complete" (section 4.4.4.2)." 176 177 Calling BlitFramebufferANGLE will result in an INVALID_OPERATION 178 error if <mask> includes COLOR_BUFFER_BIT and the source and 179 destination color formats to not match. 180 181 Calling BlitFramebufferANGLE will result in an INVALID_OPERATION 182 error if <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT 183 and the source and destination depth and stencil buffer formats do 184 not match. 185 186 If <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT, only 187 complete buffers can be copied. If the source rectangle does not 188 specify the complete source buffer or the destination rectangle 189 (after factoring the scissor region, if applicable) does not specify 190 the complete destination buffer, an INVALID_OPERATION 191 error is generated. 192 193 Modify the beginning of section 4.4.1 as follows: 194 195 "The default framebuffer for rendering and readback operations is 196 provided by the windowing system. In addition, named framebuffer 197 objects can be created and operated upon. The namespace for 198 framebuffer objects is the unsigned integers, with zero reserved 199 by the GL for the default framebuffer. 200 201 A framebuffer object is created by binding an unused name to 202 DRAW_FRAMEBUFFER_ANGLE or READ_FRAMEBUFFER_ANGLE. The binding is 203 effected by calling 204 205 void BindFramebuffer(enum target, uint framebuffer); 206 207 with <target> set to the desired framebuffer target and 208 <framebuffer> set to the unused name. The resulting framebuffer 209 object is a new state vector, comprising one set of the state values 210 listed in table 6.23 for each attachment point of the 211 framebuffer, set to the same initial values. There is one 212 color attachment point, plus one each 213 for the depth and stencil attachment points. 214 215 BindFramebuffer may also be used to bind an existing 216 framebuffer object to DRAW_FRAMEBUFFER_ANGLE or 217 READ_FRAMEBUFFER_ANGLE. If the bind is successful no change is made 218 to the state of the bound framebuffer object, and any previous 219 binding to <target> is broken. 220 221 If a framebuffer object is bound to DRAW_FRAMEBUFFER_ANGLE or 222 READ_FRAMEBUFFER_ANGLE, it becomes the target for rendering or 223 readback operations, respectively, until it is deleted or another 224 framebuffer is bound to the corresponding bind point. Calling 225 BindFramebuffer with <target> set to FRAMEBUFFER binds the 226 framebuffer to both DRAW_FRAMEBUFFER_ANGLE and READ_FRAMEBUFFER_ANGLE. 227 228 While a framebuffer object is bound, GL operations on the target 229 to which it is bound affect the images attached to the bound 230 framebuffer object, and queries of the target to which it is bound 231 return state from the bound object. Queries of the values 232 specified in table 6.20 (Implementation Dependent Pixel Depths) 233 and table 6.yy (Framebuffer Dependent Values) are 234 derived from the framebuffer object bound to DRAW_FRAMEBUFFER_ANGLE. 235 236 The initial state of DRAW_FRAMEBUFFER_ANGLE and READ_FRAMEBUFFER_ANGLE 237 refers to the default framebuffer provided by the windowing 238 system. In order that access to the default framebuffer is not 239 lost, it is treated as a framebuffer object with the name of 0. 240 The default framebuffer is therefore rendered to and read from 241 while 0 is bound to the corresponding targets. On some 242 implementations, the properties of the default framebuffer can 243 change over time (e.g., in response to windowing system events 244 such as attaching the context to a new windowing system drawable.)" 245 246 Change the description of DeleteFramebuffers as follows: 247 248 "<framebuffers> contains <n> names of framebuffer objects to be 249 deleted. After a framebuffer object is deleted, it has no 250 attachments, and its name is again unused. If a framebuffer that 251 is currently bound to one or more of the targets 252 DRAW_FRAMEBUFFER_ANGLE or READ_FRAMEBUFFER_ANGLE is deleted, it is as 253 though BindFramebuffer had been executed with the corresponding 254 <target> and <framebuffer> zero. Unused names in <framebuffers> 255 are silently ignored, as is the value zero." 256 257 258 In section 4.4.3 (Renderbuffer Objects), modify the first two sentences 259 of the description of FramebufferRenderbuffer as follows: 260 261 "<target> must be DRAW_FRAMEBUFFER_ANGLE, READ_FRAMEBUFFER_ANGLE, or 262 FRAMEBUFFER. If <target> is FRAMEBUFFER, it behaves as 263 though DRAW_FRAMEBUFFER_ANGLE was specified. The INVALID_OPERATION 264 error is generated if the value of the corresponding binding is zero." 265 266 In section 4.4.3 (Renderbuffer Objects), modify the first two sentences 267 of the description of FramebufferTexture2D as follows: 268 269 "<target> must be DRAW_FRAMEBUFFER_ANGLE, 270 READ_FRAMEBUFFER_ANGLE, or FRAMEBUFFER. If <target> is 271 FRAMEBUFFER, it behaves as though DRAW_FRAMEBUFFER_ANGLE was 272 specified. The INVALID_OPERATION error is generated if the value of the 273 corresponding binding is zero." 274 275 In section 4.4.5 (Framebuffer Completeness), modify the first sentence 276 of the description of CheckFramebufferStatus as follows: 277 278 "If <target> is not DRAW_FRAMEBUFFER_ANGLE, READ_FRAMEBUFFER_ANGLE or 279 FRAMEBUFFER, the error INVALID_ENUM is generated. If <target> is 280 FRAMEBUFFER, it behaves as though DRAW_FRAMEBUFFER_ANGLE was 281 specified." 282 283 Modify the first sentence of the subsection titled "Effects of Framebuffer 284 Completeness on Framebuffer Operations" to be: 285 286 "Attempting to render to or read from a framebuffer which is not 287 framebuffer complete will generate an 288 INVALID_FRAMEBUFFER_OPERATION error." 289 290 291 292 Additions to Chapter 6 of the OpenGL 1.5 Specification (State and State 293 Requests) 294 295 In section 6.1.3, modify the first sentence of the description of 296 GetFramebufferAttachmentParameteriv as follows: 297 298 "<target> must be DRAW_FRAMEBUFFER_ANGLE, READ_FRAMEBUFFER_ANGLE or 299 FRAMEBUFFER. If <target> is FRAMEBUFFER, it behaves as 300 though DRAW_FRAMEBUFFER_ANGLE was specified." 301 302 Modify the title of Table 6.23 (Framebuffer State) to be "Framebuffer 303 (state per attachment point)". 304 305 306 Dependencies on OES_texture_3D 307 308 On an OpenGL ES implementation, in the absense of OES_texture_3D, 309 omit references to FramebufferTexture3DOES and CopyTexSubImage3DOES. 310 311 Errors 312 313 The error INVALID_FRAMEBUFFER_OPERATION is generated if 314 BlitFramebufferANGLE is called while the 315 draw framebuffer is not framebuffer complete. 316 317 The error INVALID_FRAMEBUFFER_OPERATION is generated if 318 BlitFramebufferANGLE, ReadPixels, CopyTex{Sub}Image*, is called while the 319 read framebuffer is not framebuffer complete. 320 321 The error INVALID_OPERATION is generated if GetIntegerv is called 322 while the read framebuffer is not framebuffer complete, or if there 323 is no color attachment present on the read framebuffer object. 324 325 The error INVALID_VALUE is generated by BlitFramebufferANGLE if 326 <mask> has any bits set other than those named by 327 COLOR_BUFFER_BIT, DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT. 328 329 The error INVALID_OPERATION is generated if BlitFramebufferANGLE is 330 called and <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT 331 and the source and destination depth or stencil buffer formats do 332 not match. 333 334 The error INVALID_OPERATION is generated if BlitFramebufferANGLE is 335 called and any of the following conditions are true: 336 - the source and destination rectangle dimensions do not match 337 (ie scaling or flipping is required). 338 - <mask> includes COLOR_BUFFER_BIT and the source and destination 339 buffer formats do not match. 340 - <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT and the 341 source or destination rectangles do not specify the entire source 342 or destination buffer (after applying any scissor region). 343 344 The error INVALID_ENUM is generated by BlitFramebufferANGLE if 345 <filter> is not NEAREST. 346 347 The error INVALID_ENUM is generated if BindFramebuffer, 348 CheckFramebufferStatus, FramebufferTexture{2D|3DOES}, 349 FramebufferRenderbuffer, or 350 GetFramebufferAttachmentParameteriv is called and <target> is 351 not DRAW_FRAMEBUFFER_ANGLE, READ_FRAMEBUFFER_ANGLE or FRAMEBUFFER. 352 353 New State 354 355 (Add a new table 6.xx, "Framebuffer (state per framebuffer target binding point)") 356 357 Get Value Type Get Command Initial Value Description Section 358 ------------------------------ ---- ----------- -------------- ------------------- ------------ 359 DRAW_FRAMEBUFFER_BINDING_ANGLE Z+ GetIntegerv 0 framebuffer object bound 4.4.1 360 to DRAW_FRAMEBUFFER_ANGLE 361 READ_FRAMEBUFFER_BINDING_ANGLE Z+ GetIntegerv 0 framebuffer object 4.4.1 362 to READ_FRAMEBUFFER_ANGLE 363 364 Remove reference to FRAMEBUFFER_BINDING from Table 6.23. 365 366 (Add a new table 6.yy, "Framebuffer Dependent Values") 367 368 Get Value Type Get Command Initial Value Description Section 369 ---------------------------- ---- ----------- -------------- ------------------- ------------ 370 SAMPLE_BUFFERS Z+ GetIntegerv 0 Number of multisample 3.2 371 buffers 372 SAMPLES Z+ GetIntegerv 0 Coverage mask size 3.2 373 374 Remove the references to SAMPLE_BUFFERS and SAMPLES from Table 6.17. 375 376 377 Issues 378 379 1) What should we call this extension? 380 381 Resolved: ANGLE_framebuffer_blit. 382 383 This extension is a result of a collaboration between Google and 384 TransGaming for the open-source ANGLE project. Typically one would 385 label a multi-vendor extension as EXT, but EXT_framebuffer_blit 386 is already the name for this on Desktop GL. Additionally this 387 isn't truely a multi-vendor extension because there is only one 388 implementation of this. We'll follow the example of the open-source 389 MESA project which uses the project name for the vendor suffix. 390 391 2) Why is this done as a separate extension instead of just supporting 392 EXT_framebuffer_blit? 393 394 To date, EXT_framebuffer_blit has not had interactions with OpenGL ES 395 specified and, as far as we know, it has not previously been exposed on 396 an ES 1.1 or ES 2.0 implementation. Because there are enough 397 differences between Desktop GL and OpenGL ES, and since OpenGL ES 2.0 398 has already subsumed the EXT_framebuffer_object functionality (with 399 some changes) it was deemed a worthwhile exercise to fully specify the 400 interactions. Additionally, some of the choices in exactly which 401 functionality is supported by BlitFramebufferANGLE is dictated by 402 what is reasonable to support on a implementation which is 403 layered on Direct3D9. It is not expected that other implementations 404 will necessary have the same set of restrictions or requirements. 405 406 3) How does this extension differ from EXT_framebuffer_blit? 407 408 This extension is designed to be a pure subset of the 409 EXT_framebuffer_blit functionality as applicable to OpenGL ES 2.0. 410 411 Functionality that is unchanged: 412 - the split DRAW and READ framebuffer attachment points and related sematics. 413 - the token values for the DRAW/READ_FRAMEBUFFER and DRAW/READ_FRAMBUFFER_BINDING 414 - the signature of the BlitFramebuffer entry-point. 415 416 Additional restrictions imposed by BlitFramebufferANGLE: 417 - no color conversions are supported 418 - no scaling, stretching or flipping are supported 419 - no filtering is supported (a consequence of no stretching) 420 - only whole depth and/or stencil buffers can be copied 421 422 Revision History 423 424 Revision 1, 2010/07/06 425 - copied from revision 15 of EXT_framebuffer_object 426 - removed language that was clearly not relevant to ES2 427 - rebased changes against the OpenGL ES 2.0 specification 428 - added ANGLE-specific restrictions 429 Revision 2, 2010/07/15 430 - clarifications of implicit clamping to buffer sizes (from ARB_fbo) 431 - clarify that D/S restricts apply after the scissor is applied 432 - improve some error language 433 Revision 3, 2010/08/06 434 - add additional contributors, update implementation status 435 Revision 4, 2012/09/22 436 - document errors for GetIntegerv. 437 438
