1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/gfx/angle/extensions/ANGLE_framebuffer_blit.txt Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,437 @@
1.4 +Name
1.5 +
1.6 + ANGLE_framebuffer_blit
1.7 +
1.8 +Name Strings
1.9 +
1.10 + GL_ANGLE_framebuffer_blit
1.11 +
1.12 +Contributors
1.13 +
1.14 + Contributors to EXT_framebuffer_blit
1.15 + Daniel Koch, TransGaming Inc.
1.16 + Shannon Woods, TransGaming Inc.
1.17 + Kenneth Russell, Google Inc.
1.18 + Vangelis Kokkevis, Google Inc.
1.19 +
1.20 +Contact
1.21 +
1.22 + Daniel Koch, TransGaming Inc. (daniel 'at' transgaming 'dot' com)
1.23 +
1.24 +Status
1.25 +
1.26 + Implemented in ANGLE ES2
1.27 +
1.28 +Version
1.29 +
1.30 + Last Modified Date: Sept 22, 2012
1.31 + Author Revision: 4
1.32 +
1.33 +Number
1.34 +
1.35 + OpenGL ES Extension #83
1.36 +
1.37 +Dependencies
1.38 +
1.39 + OpenGL ES 2.0 is required.
1.40 +
1.41 + The extension is written against the OpenGL ES 2.0 specification.
1.42 +
1.43 + OES_texture_3D affects the definition of this extension.
1.44 +
1.45 +Overview
1.46 +
1.47 + This extension modifies framebuffer objects by splitting the
1.48 + framebuffer object binding point into separate DRAW and READ
1.49 + bindings. This allows copying directly from one framebuffer to
1.50 + another. In addition, a new high performance blit function is
1.51 + added to facilitate these blits and perform some data conversion
1.52 + where allowed.
1.53 +
1.54 +IP Status
1.55 +
1.56 + No known IP claims.
1.57 +
1.58 +New Procedures and Functions
1.59 +
1.60 + void BlitFramebufferANGLE(int srcX0, int srcY0, int srcX1, int srcY1,
1.61 + int dstX0, int dstY0, int dstX1, int dstY1,
1.62 + bitfield mask, enum filter);
1.63 +
1.64 +New Tokens
1.65 +
1.66 + Accepted by the <target> parameter of BindFramebuffer,
1.67 + CheckFramebufferStatus, FramebufferTexture2D, FramebufferTexture3DOES,
1.68 + FramebufferRenderbuffer, and
1.69 + GetFramebufferAttachmentParameteriv:
1.70 +
1.71 + // (reusing the tokens from EXT_framebuffer_blit)
1.72 + READ_FRAMEBUFFER_ANGLE 0x8CA8
1.73 + DRAW_FRAMEBUFFER_ANGLE 0x8CA9
1.74 +
1.75 + Accepted by the <pname> parameters of GetIntegerv and GetFloatv:
1.76 +
1.77 + // (reusing the tokens from EXT_framebuffer_blit)
1.78 + DRAW_FRAMEBUFFER_BINDING_ANGLE 0x8CA6 // alias FRAMEBUFFER_BINDING
1.79 + READ_FRAMEBUFFER_BINDING_ANGLE 0x8CAA
1.80 +
1.81 +
1.82 +Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization)
1.83 +
1.84 + Change the last paragraph of section 3.7.2 (Alternate Texture Image
1.85 + Specification Commands) to:
1.86 +
1.87 + "Calling CopyTexSubImage3DOES, CopyTexImage2D or CopyTexSubImage2D will
1.88 + result in an INVALID_FRAMEBUFFER_OPERATION error if the object bound
1.89 + to READ_FRAMEBUFFER_BINDING_ANGLE is not "framebuffer complete"
1.90 + (section 4.4.4.2)."
1.91 +
1.92 +Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment
1.93 +Operations and the Framebuffer)
1.94 +
1.95 + Change the first word of Chapter 4 from "The" to "A".
1.96 +
1.97 + Append to the introduction of Chapter 4:
1.98 +
1.99 + "Conceptually, the GL has two active framebuffers; the draw
1.100 + framebuffer is the destination for rendering operations, and the
1.101 + read framebuffer is the source for readback operations. The same
1.102 + framebuffer may be used for both drawing and reading. Section
1.103 + 4.4.1 describes the mechanism for controlling framebuffer usage."
1.104 +
1.105 + Modify the first sentence of the last paragraph of section 4.1.1 as follows:
1.106 +
1.107 + "While an application-created framebuffer object is bound to
1.108 + DRAW_FRAMEBUFFER_ANGLE, the pixel ownership test always passes."
1.109 +
1.110 + Add to 4.3.1 (Reading Pixels), right before the subsection titled
1.111 + "Obtaining Pixels from the Framebuffer":
1.112 +
1.113 + "Calling ReadPixels generates INVALID_FRAMEBUFFER_OPERATION if
1.114 + the object bound to READ_FRAMEBUFFER_BINDING_ANGLE is not "framebuffer
1.115 + complete" (section 4.4.4.2). GetIntegerv generates an INVALID_OPERATION
1.116 + error if the object bound to READ_FRAMEBUFFER_BINDING_ANGLE is not
1.117 + framebuffer complete, or if the GL is using a framebuffer object
1.118 + (i.e. READ_FRAMEBUFFER_BINDING_ANGLE is non-zero) and there is no color
1.119 + attachment."
1.120 +
1.121 + Insert a new section 4.3.2 titled "Copying Pixels" and renumber the
1.122 + subsequent sections. Add the following text:
1.123 +
1.124 + "BlitFramebufferANGLE transfers a rectangle of pixel values from one
1.125 + region of the read framebuffer to another in the draw framebuffer.
1.126 +
1.127 + BlitFramebufferANGLE(int srcX0, int srcY0, int srcX1, int srcY1,
1.128 + int dstX0, int dstY0, int dstX1, int dstY1,
1.129 + bitfield mask, enum filter);
1.130 +
1.131 + <mask> is the bitwise OR of a number of values indicating which
1.132 + buffers are to be copied. The values are COLOR_BUFFER_BIT,
1.133 + DEPTH_BUFFER_BIT, and STENCIL_BUFFER_BIT, which are described in
1.134 + section 4.2.3. The pixels corresponding to these buffers are
1.135 + copied from the source rectangle, bound by the locations (srcX0,
1.136 + srcY0) and (srcX1, srcY1), to the destination rectangle, bound by
1.137 + the locations (dstX0, dstY0) and (dstX1, dstY1). The lower bounds
1.138 + of the rectangle are inclusive, while the upper bounds are
1.139 + exclusive.
1.140 +
1.141 + The actual region taken from the read framebuffer is limited to the
1.142 + intersection of the source buffers being transferred, which may include
1.143 + the color buffer, the depth buffer, and/or the stencil buffer depending on
1.144 + <mask>. The actual region written to the draw framebuffer is limited to the
1.145 + intersection of the destination buffers being written, which may include
1.146 + the color buffer, the depth buffer, and/or the stencil buffer
1.147 + depending on <mask>. Whether or not the source or destination regions are
1.148 + altered due to these limits, the offset applied to pixels being transferred
1.149 + is performed as though no such limits were present.
1.150 +
1.151 + Stretching and scaling during a copy are not supported. If the source
1.152 + and destination rectangle dimensions do not match, no copy is
1.153 + performed and an INVALID_OPERATION error is generated.
1.154 + Because stretching is not supported, <filter> must be NEAREST and
1.155 + no filtering is applied.
1.156 +
1.157 + Flipping during a copy is not supported. If either the source or
1.158 + destination rectangle specifies a negative dimension, the error
1.159 + INVALID_OPERATION is generated. If both the source and
1.160 + destination rectangles specify a negative dimension for the same
1.161 + direction, no reversal is required and the operation is supported.
1.162 +
1.163 + If the source and destination buffers are identical, and the
1.164 + source and destination rectangles overlap, the result of the blit
1.165 + operation is undefined.
1.166 +
1.167 + The pixel copy bypasses the fragment pipeline. The only fragment
1.168 + operations which affect the blit are the pixel ownership test and
1.169 + the scissor test.
1.170 +
1.171 + If a buffer is specified in <mask> and does not exist in both the
1.172 + read and draw framebuffers, the corresponding bit is silently
1.173 + ignored.
1.174 +
1.175 + Calling BlitFramebufferANGLE will result in an
1.176 + INVALID_FRAMEBUFFER_OPERATION error if the objects bound to
1.177 + DRAW_FRAMEBUFFER_BINDING_ANGLE and READ_FRAMEBUFFER_BINDING_ANGLE are
1.178 + not "framebuffer complete" (section 4.4.4.2)."
1.179 +
1.180 + Calling BlitFramebufferANGLE will result in an INVALID_OPERATION
1.181 + error if <mask> includes COLOR_BUFFER_BIT and the source and
1.182 + destination color formats to not match.
1.183 +
1.184 + Calling BlitFramebufferANGLE will result in an INVALID_OPERATION
1.185 + error if <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT
1.186 + and the source and destination depth and stencil buffer formats do
1.187 + not match.
1.188 +
1.189 + If <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT, only
1.190 + complete buffers can be copied. If the source rectangle does not
1.191 + specify the complete source buffer or the destination rectangle
1.192 + (after factoring the scissor region, if applicable) does not specify
1.193 + the complete destination buffer, an INVALID_OPERATION
1.194 + error is generated.
1.195 +
1.196 + Modify the beginning of section 4.4.1 as follows:
1.197 +
1.198 + "The default framebuffer for rendering and readback operations is
1.199 + provided by the windowing system. In addition, named framebuffer
1.200 + objects can be created and operated upon. The namespace for
1.201 + framebuffer objects is the unsigned integers, with zero reserved
1.202 + by the GL for the default framebuffer.
1.203 +
1.204 + A framebuffer object is created by binding an unused name to
1.205 + DRAW_FRAMEBUFFER_ANGLE or READ_FRAMEBUFFER_ANGLE. The binding is
1.206 + effected by calling
1.207 +
1.208 + void BindFramebuffer(enum target, uint framebuffer);
1.209 +
1.210 + with <target> set to the desired framebuffer target and
1.211 + <framebuffer> set to the unused name. The resulting framebuffer
1.212 + object is a new state vector, comprising one set of the state values
1.213 + listed in table 6.23 for each attachment point of the
1.214 + framebuffer, set to the same initial values. There is one
1.215 + color attachment point, plus one each
1.216 + for the depth and stencil attachment points.
1.217 +
1.218 + BindFramebuffer may also be used to bind an existing
1.219 + framebuffer object to DRAW_FRAMEBUFFER_ANGLE or
1.220 + READ_FRAMEBUFFER_ANGLE. If the bind is successful no change is made
1.221 + to the state of the bound framebuffer object, and any previous
1.222 + binding to <target> is broken.
1.223 +
1.224 + If a framebuffer object is bound to DRAW_FRAMEBUFFER_ANGLE or
1.225 + READ_FRAMEBUFFER_ANGLE, it becomes the target for rendering or
1.226 + readback operations, respectively, until it is deleted or another
1.227 + framebuffer is bound to the corresponding bind point. Calling
1.228 + BindFramebuffer with <target> set to FRAMEBUFFER binds the
1.229 + framebuffer to both DRAW_FRAMEBUFFER_ANGLE and READ_FRAMEBUFFER_ANGLE.
1.230 +
1.231 + While a framebuffer object is bound, GL operations on the target
1.232 + to which it is bound affect the images attached to the bound
1.233 + framebuffer object, and queries of the target to which it is bound
1.234 + return state from the bound object. Queries of the values
1.235 + specified in table 6.20 (Implementation Dependent Pixel Depths)
1.236 + and table 6.yy (Framebuffer Dependent Values) are
1.237 + derived from the framebuffer object bound to DRAW_FRAMEBUFFER_ANGLE.
1.238 +
1.239 + The initial state of DRAW_FRAMEBUFFER_ANGLE and READ_FRAMEBUFFER_ANGLE
1.240 + refers to the default framebuffer provided by the windowing
1.241 + system. In order that access to the default framebuffer is not
1.242 + lost, it is treated as a framebuffer object with the name of 0.
1.243 + The default framebuffer is therefore rendered to and read from
1.244 + while 0 is bound to the corresponding targets. On some
1.245 + implementations, the properties of the default framebuffer can
1.246 + change over time (e.g., in response to windowing system events
1.247 + such as attaching the context to a new windowing system drawable.)"
1.248 +
1.249 + Change the description of DeleteFramebuffers as follows:
1.250 +
1.251 + "<framebuffers> contains <n> names of framebuffer objects to be
1.252 + deleted. After a framebuffer object is deleted, it has no
1.253 + attachments, and its name is again unused. If a framebuffer that
1.254 + is currently bound to one or more of the targets
1.255 + DRAW_FRAMEBUFFER_ANGLE or READ_FRAMEBUFFER_ANGLE is deleted, it is as
1.256 + though BindFramebuffer had been executed with the corresponding
1.257 + <target> and <framebuffer> zero. Unused names in <framebuffers>
1.258 + are silently ignored, as is the value zero."
1.259 +
1.260 +
1.261 + In section 4.4.3 (Renderbuffer Objects), modify the first two sentences
1.262 + of the description of FramebufferRenderbuffer as follows:
1.263 +
1.264 + "<target> must be DRAW_FRAMEBUFFER_ANGLE, READ_FRAMEBUFFER_ANGLE, or
1.265 + FRAMEBUFFER. If <target> is FRAMEBUFFER, it behaves as
1.266 + though DRAW_FRAMEBUFFER_ANGLE was specified. The INVALID_OPERATION
1.267 + error is generated if the value of the corresponding binding is zero."
1.268 +
1.269 + In section 4.4.3 (Renderbuffer Objects), modify the first two sentences
1.270 + of the description of FramebufferTexture2D as follows:
1.271 +
1.272 + "<target> must be DRAW_FRAMEBUFFER_ANGLE,
1.273 + READ_FRAMEBUFFER_ANGLE, or FRAMEBUFFER. If <target> is
1.274 + FRAMEBUFFER, it behaves as though DRAW_FRAMEBUFFER_ANGLE was
1.275 + specified. The INVALID_OPERATION error is generated if the value of the
1.276 + corresponding binding is zero."
1.277 +
1.278 + In section 4.4.5 (Framebuffer Completeness), modify the first sentence
1.279 + of the description of CheckFramebufferStatus as follows:
1.280 +
1.281 + "If <target> is not DRAW_FRAMEBUFFER_ANGLE, READ_FRAMEBUFFER_ANGLE or
1.282 + FRAMEBUFFER, the error INVALID_ENUM is generated. If <target> is
1.283 + FRAMEBUFFER, it behaves as though DRAW_FRAMEBUFFER_ANGLE was
1.284 + specified."
1.285 +
1.286 + Modify the first sentence of the subsection titled "Effects of Framebuffer
1.287 + Completeness on Framebuffer Operations" to be:
1.288 +
1.289 + "Attempting to render to or read from a framebuffer which is not
1.290 + framebuffer complete will generate an
1.291 + INVALID_FRAMEBUFFER_OPERATION error."
1.292 +
1.293 +
1.294 +
1.295 +Additions to Chapter 6 of the OpenGL 1.5 Specification (State and State
1.296 +Requests)
1.297 +
1.298 + In section 6.1.3, modify the first sentence of the description of
1.299 + GetFramebufferAttachmentParameteriv as follows:
1.300 +
1.301 + "<target> must be DRAW_FRAMEBUFFER_ANGLE, READ_FRAMEBUFFER_ANGLE or
1.302 + FRAMEBUFFER. If <target> is FRAMEBUFFER, it behaves as
1.303 + though DRAW_FRAMEBUFFER_ANGLE was specified."
1.304 +
1.305 + Modify the title of Table 6.23 (Framebuffer State) to be "Framebuffer
1.306 + (state per attachment point)".
1.307 +
1.308 +
1.309 +Dependencies on OES_texture_3D
1.310 +
1.311 + On an OpenGL ES implementation, in the absense of OES_texture_3D,
1.312 + omit references to FramebufferTexture3DOES and CopyTexSubImage3DOES.
1.313 +
1.314 +Errors
1.315 +
1.316 + The error INVALID_FRAMEBUFFER_OPERATION is generated if
1.317 + BlitFramebufferANGLE is called while the
1.318 + draw framebuffer is not framebuffer complete.
1.319 +
1.320 + The error INVALID_FRAMEBUFFER_OPERATION is generated if
1.321 + BlitFramebufferANGLE, ReadPixels, CopyTex{Sub}Image*, is called while the
1.322 + read framebuffer is not framebuffer complete.
1.323 +
1.324 + The error INVALID_OPERATION is generated if GetIntegerv is called
1.325 + while the read framebuffer is not framebuffer complete, or if there
1.326 + is no color attachment present on the read framebuffer object.
1.327 +
1.328 + The error INVALID_VALUE is generated by BlitFramebufferANGLE if
1.329 + <mask> has any bits set other than those named by
1.330 + COLOR_BUFFER_BIT, DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT.
1.331 +
1.332 + The error INVALID_OPERATION is generated if BlitFramebufferANGLE is
1.333 + called and <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT
1.334 + and the source and destination depth or stencil buffer formats do
1.335 + not match.
1.336 +
1.337 + The error INVALID_OPERATION is generated if BlitFramebufferANGLE is
1.338 + called and any of the following conditions are true:
1.339 + - the source and destination rectangle dimensions do not match
1.340 + (ie scaling or flipping is required).
1.341 + - <mask> includes COLOR_BUFFER_BIT and the source and destination
1.342 + buffer formats do not match.
1.343 + - <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT and the
1.344 + source or destination rectangles do not specify the entire source
1.345 + or destination buffer (after applying any scissor region).
1.346 +
1.347 + The error INVALID_ENUM is generated by BlitFramebufferANGLE if
1.348 + <filter> is not NEAREST.
1.349 +
1.350 + The error INVALID_ENUM is generated if BindFramebuffer,
1.351 + CheckFramebufferStatus, FramebufferTexture{2D|3DOES},
1.352 + FramebufferRenderbuffer, or
1.353 + GetFramebufferAttachmentParameteriv is called and <target> is
1.354 + not DRAW_FRAMEBUFFER_ANGLE, READ_FRAMEBUFFER_ANGLE or FRAMEBUFFER.
1.355 +
1.356 +New State
1.357 +
1.358 + (Add a new table 6.xx, "Framebuffer (state per framebuffer target binding point)")
1.359 +
1.360 + Get Value Type Get Command Initial Value Description Section
1.361 + ------------------------------ ---- ----------- -------------- ------------------- ------------
1.362 + DRAW_FRAMEBUFFER_BINDING_ANGLE Z+ GetIntegerv 0 framebuffer object bound 4.4.1
1.363 + to DRAW_FRAMEBUFFER_ANGLE
1.364 + READ_FRAMEBUFFER_BINDING_ANGLE Z+ GetIntegerv 0 framebuffer object 4.4.1
1.365 + to READ_FRAMEBUFFER_ANGLE
1.366 +
1.367 + Remove reference to FRAMEBUFFER_BINDING from Table 6.23.
1.368 +
1.369 + (Add a new table 6.yy, "Framebuffer Dependent Values")
1.370 +
1.371 + Get Value Type Get Command Initial Value Description Section
1.372 + ---------------------------- ---- ----------- -------------- ------------------- ------------
1.373 + SAMPLE_BUFFERS Z+ GetIntegerv 0 Number of multisample 3.2
1.374 + buffers
1.375 + SAMPLES Z+ GetIntegerv 0 Coverage mask size 3.2
1.376 +
1.377 + Remove the references to SAMPLE_BUFFERS and SAMPLES from Table 6.17.
1.378 +
1.379 +
1.380 +Issues
1.381 +
1.382 + 1) What should we call this extension?
1.383 +
1.384 + Resolved: ANGLE_framebuffer_blit.
1.385 +
1.386 + This extension is a result of a collaboration between Google and
1.387 + TransGaming for the open-source ANGLE project. Typically one would
1.388 + label a multi-vendor extension as EXT, but EXT_framebuffer_blit
1.389 + is already the name for this on Desktop GL. Additionally this
1.390 + isn't truely a multi-vendor extension because there is only one
1.391 + implementation of this. We'll follow the example of the open-source
1.392 + MESA project which uses the project name for the vendor suffix.
1.393 +
1.394 + 2) Why is this done as a separate extension instead of just supporting
1.395 + EXT_framebuffer_blit?
1.396 +
1.397 + To date, EXT_framebuffer_blit has not had interactions with OpenGL ES
1.398 + specified and, as far as we know, it has not previously been exposed on
1.399 + an ES 1.1 or ES 2.0 implementation. Because there are enough
1.400 + differences between Desktop GL and OpenGL ES, and since OpenGL ES 2.0
1.401 + has already subsumed the EXT_framebuffer_object functionality (with
1.402 + some changes) it was deemed a worthwhile exercise to fully specify the
1.403 + interactions. Additionally, some of the choices in exactly which
1.404 + functionality is supported by BlitFramebufferANGLE is dictated by
1.405 + what is reasonable to support on a implementation which is
1.406 + layered on Direct3D9. It is not expected that other implementations
1.407 + will necessary have the same set of restrictions or requirements.
1.408 +
1.409 + 3) How does this extension differ from EXT_framebuffer_blit?
1.410 +
1.411 + This extension is designed to be a pure subset of the
1.412 + EXT_framebuffer_blit functionality as applicable to OpenGL ES 2.0.
1.413 +
1.414 + Functionality that is unchanged:
1.415 + - the split DRAW and READ framebuffer attachment points and related sematics.
1.416 + - the token values for the DRAW/READ_FRAMEBUFFER and DRAW/READ_FRAMBUFFER_BINDING
1.417 + - the signature of the BlitFramebuffer entry-point.
1.418 +
1.419 + Additional restrictions imposed by BlitFramebufferANGLE:
1.420 + - no color conversions are supported
1.421 + - no scaling, stretching or flipping are supported
1.422 + - no filtering is supported (a consequence of no stretching)
1.423 + - only whole depth and/or stencil buffers can be copied
1.424 +
1.425 +Revision History
1.426 +
1.427 + Revision 1, 2010/07/06
1.428 + - copied from revision 15 of EXT_framebuffer_object
1.429 + - removed language that was clearly not relevant to ES2
1.430 + - rebased changes against the OpenGL ES 2.0 specification
1.431 + - added ANGLE-specific restrictions
1.432 + Revision 2, 2010/07/15
1.433 + - clarifications of implicit clamping to buffer sizes (from ARB_fbo)
1.434 + - clarify that D/S restricts apply after the scissor is applied
1.435 + - improve some error language
1.436 + Revision 3, 2010/08/06
1.437 + - add additional contributors, update implementation status
1.438 + Revision 4, 2012/09/22
1.439 + - document errors for GetIntegerv.
1.440 +
