1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/gfx/angle/extensions/ANGLE_framebuffer_multisample.txt Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,363 @@
1.4 +Name
1.5 +
1.6 + ANGLE_framebuffer_multisample
1.7 +
1.8 +Name Strings
1.9 +
1.10 + GL_ANGLE_framebuffer_multisample
1.11 +
1.12 +Contributors
1.13 +
1.14 + Contributors to EXT_framebuffer_multisample
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 +Contacts
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: Aug 6, 2010
1.31 + Author Revision: #3
1.32 +
1.33 +Number
1.34 +
1.35 + OpenGL ES Extension #84
1.36 +
1.37 +Dependencies
1.38 +
1.39 + Requires OpenGL ES 2.0.
1.40 +
1.41 + Requires GL_ANGLE_framebuffer_blit (or equivalent functionality).
1.42 +
1.43 + The extension is written against the OpenGL ES 2.0 specification.
1.44 +
1.45 + OES_texture_3D affects the definition of this extension.
1.46 +
1.47 +Overview
1.48 +
1.49 + This extension extends the framebuffer object framework to
1.50 + enable multisample rendering.
1.51 +
1.52 + The new operation RenderbufferStorageMultisampleANGLE() allocates
1.53 + storage for a renderbuffer object that can be used as a multisample
1.54 + buffer. A multisample render buffer image differs from a
1.55 + single-sample render buffer image in that a multisample image has a
1.56 + number of SAMPLES that is greater than zero. No method is provided
1.57 + for creating multisample texture images.
1.58 +
1.59 + All of the framebuffer-attachable images attached to a framebuffer
1.60 + object must have the same number of SAMPLES or else the framebuffer
1.61 + object is not "framebuffer complete". If a framebuffer object with
1.62 + multisample attachments is "framebuffer complete", then the
1.63 + framebuffer object behaves as if SAMPLE_BUFFERS is one.
1.64 +
1.65 + The resolve operation is affected by calling
1.66 + BlitFramebufferANGLE (provided by the ANGLE_framebuffer_blit
1.67 + extension) where the source is a multisample application-created
1.68 + framebuffer object and the destination is a single-sample
1.69 + framebuffer object (either application-created or window-system
1.70 + provided).
1.71 +
1.72 +New Procedures and Functions
1.73 +
1.74 + void RenderbufferStorageMultisampleANGLE(
1.75 + enum target, sizei samples,
1.76 + enum internalformat,
1.77 + sizei width, sizei height);
1.78 +
1.79 +New Types
1.80 +
1.81 + None.
1.82 +
1.83 +New Tokens
1.84 +
1.85 + Accepted by the <pname> parameter of GetRenderbufferParameteriv:
1.86 +
1.87 + RENDERBUFFER_SAMPLES_ANGLE 0x8CAB
1.88 +
1.89 + Returned by CheckFramebufferStatus:
1.90 +
1.91 + FRAMEBUFFER_INCOMPLETE_MULTISAMPLE_ANGLE 0x8D56
1.92 +
1.93 + Accepted by the <pname> parameter of GetBooleanv, GetIntegerv,
1.94 + and GetFloatv:
1.95 +
1.96 + MAX_SAMPLES_ANGLE 0x8D57
1.97 +
1.98 +Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL Operation)
1.99 +
1.100 +Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization)
1.101 +
1.102 + Add to the last paragraph of 3.7.2 (Alternate Texture Image Specification)
1.103 + (as modified by ANGLE_framebuffer_blit) the following:
1.104 +
1.105 + "Calling CopyTexSubImage3DOES, CopyTexImage2D or CopyTexSubImage2D will
1.106 + result in INVALID_OPERATION being generated if the object bound to
1.107 + READ_FRAMEBUFFER_BINDING_ANGLE is "framebuffer complete" and the value
1.108 + of SAMPLE_BUFFERS is greater than zero."
1.109 +
1.110 +Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment
1.111 +Operations and the Framebuffer)
1.112 +
1.113 + Add to 4.3.1 (Reading Pixels), right before the subsection titled
1.114 + "Obtaining Pixels from the Framebuffer":
1.115 +
1.116 + "ReadPixels generates INVALID_OPERATION if READ_FRAMEBUFFER_BINDING_ANGLE
1.117 + (section 4.4) is non-zero, the read framebuffer is framebuffer
1.118 + complete, and the value of SAMPLE_BUFFERS for the read framebuffer
1.119 + is greater than zero."
1.120 +
1.121 + In 4.3.2 (Copying Pixels), add to the section describing BlitFramebuffer
1.122 + that was added by ANGLE_framebuffer_blit.
1.123 +
1.124 + "If SAMPLE_BUFFERS for the read framebuffer is greater than zero and
1.125 + SAMPLE_BUFFERS for the draw framebuffer is zero, the samples
1.126 + corresponding to each pixel location in the source are converted to
1.127 + a single sample before being written to the destination.
1.128 +
1.129 + If SAMPLE_BUFFERS for the draw framebuffer is greater than zero,
1.130 + no copy is performed and an INVALID_OPERATION error is generated.
1.131 +
1.132 + If SAMPLE_BUFFERS for the read framebuffer is greater than zero and
1.133 + <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT, no copy is
1.134 + performed and an INVALID_OPERATION error is generated.
1.135 +
1.136 + If SAMPLE_BUFFERS for the read framebuffer is greater than zero and
1.137 + the format of the read and draw framebuffers are not identical, no
1.138 + copy is performed and an INVALID_OPERATION error is generated.
1.139 +
1.140 + If SAMPLE_BUFFERS for the read framebuffer is greater than zero, the
1.141 + dimensions of the source and destination rectangles provided to
1.142 + BlitFramebufferANGLE must be identical and must specify the complete
1.143 + source and destination buffers, otherwise no copy is performed and
1.144 + an INVALID_OPERATION error is generated."
1.145 +
1.146 + Modification to 4.4.3 (Renderbuffer Objects)
1.147 +
1.148 + Add, just above the definition of RenderbufferStorage:
1.149 +
1.150 + "The command
1.151 +
1.152 + void RenderbufferStorageMultisampleANGLE(
1.153 + enum target, sizei samples,
1.154 + enum internalformat,
1.155 + sizei width, sizei height);
1.156 +
1.157 + establishes the data storage, format, dimensions, and number of
1.158 + samples of a renderbuffer object's image. <target> must be
1.159 + RENDERBUFFER. <internalformat> must be one of the color-renderable,
1.160 + depth-renderable, or stencil-renderable formats described in table 4.5.
1.161 + <width> and <height> are the dimensions in pixels of the renderbuffer. If
1.162 + either <width> or <height> is greater than the value of
1.163 + MAX_RENDERBUFFER_SIZE, or if <samples> is greater than MAX_SAMPLES_ANGLE,
1.164 + then the error INVALID_VALUE is generated. If OpenGL ES is unable to
1.165 + create a data store of the requested size, the error OUT_OF_MEMORY
1.166 + is generated.
1.167 +
1.168 + Upon success, RenderbufferStorageMultisampleANGLE deletes any existing
1.169 + data store for the renderbuffer image and the contents of the data
1.170 + store after calling RenderbufferStorageMultisampleANGLE are undefined.
1.171 + RENDERBUFFER_WIDTH is set to <width>, RENDERBUFFER_HEIGHT is
1.172 + set to <height>, and RENDERBUFFER_INTERNAL_FORMAT is set to
1.173 + <internalformat>.
1.174 +
1.175 + If <samples> is zero, then RENDERBUFFER_SAMPLES_ANGLE is set to zero.
1.176 + Otherwise <samples> represents a request for a desired minimum
1.177 + number of samples. Since different implementations may support
1.178 + different sample counts for multisampled rendering, the actual
1.179 + number of samples allocated for the renderbuffer image is
1.180 + implementation dependent. However, the resulting value for
1.181 + RENDERBUFFER_SAMPLES_ANGLE is guaranteed to be greater than or equal
1.182 + to <samples> and no more than the next larger sample count supported
1.183 + by the implementation.
1.184 +
1.185 + An OpenGL ES implementation may vary its allocation of internal component
1.186 + resolution based on any RenderbufferStorageMultisampleANGLE parameter (except
1.187 + target), but the allocation and chosen internal format must not be a
1.188 + function of any other state and cannot be changed once they are
1.189 + established. The actual resolution in bits of each component of the
1.190 + allocated image can be queried with GetRenderbufferParameteriv."
1.191 +
1.192 + Modify the definiton of RenderbufferStorage as follows:
1.193 +
1.194 + "The command
1.195 +
1.196 + void RenderbufferStorage(enum target, enum internalformat,
1.197 + sizei width, sizei height);
1.198 +
1.199 + is equivalent to calling RenderbufferStorageMultisampleANGLE with
1.200 + <samples> equal to zero."
1.201 +
1.202 + In section 4.4.5 (Framebuffer Completeness) in the subsection
1.203 + titled "Framebuffer Completeness" add an entry to the bullet list:
1.204 +
1.205 + * The value of RENDERBUFFER_SAMPLES_ANGLE is the same for all attached
1.206 + images.
1.207 + { FRAMEBUFFER_INCOMPLETE_MULTISAMPLE_ANGLE }
1.208 +
1.209 + Also add a paragraph to the end of the section after the definition
1.210 + of CheckFramebufferStatus:
1.211 +
1.212 + "The values of SAMPLE_BUFFERS and SAMPLES are derived from the
1.213 + attachments of the currently bound framebuffer object. If the
1.214 + current DRAW_FRAMEBUFFER_BINDING_ANGLE is not "framebuffer complete",
1.215 + then both SAMPLE_BUFFERS and SAMPLES are undefined. Otherwise,
1.216 + SAMPLES is equal to the value of RENDERBUFFER_SAMPLES_ANGLE for the
1.217 + attached images (which all must have the same value for
1.218 + RENDERBUFFER_SAMPLES_ANGLE). Further, SAMPLE_BUFFERS is one if
1.219 + SAMPLES is non-zero. Otherwise, SAMPLE_BUFFERS is zero.
1.220 +
1.221 +Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special Functions)
1.222 +
1.223 +
1.224 +Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and State
1.225 +Requests)
1.226 +
1.227 + In section 6.1.3 (Enumeraged Queries), modify the third paragraph
1.228 + of the description of GetRenderbufferParameteriv as follows:
1.229 +
1.230 + "Upon successful return from GetRenderbufferParameteriv, if
1.231 + <pname> is RENDERBUFFER_WIDTH, RENDERBUFFER_HEIGHT,
1.232 + RENDERBUFFER_INTERNAL_FORMAT, or RENDERBUFFER_SAMPLES_ANGLE, then <params>
1.233 + will contain the width in pixels, height in pixels, internal format, or
1.234 + number of samples, respectively, of the image of the renderbuffer
1.235 + currently bound to <target>."
1.236 +
1.237 +
1.238 +Dependencies on ANGLE_framebuffer_blit
1.239 +
1.240 + ANGLE_framebuffer_blit is required. Technically, ANGLE_framebuffer_blit
1.241 + would not be required to support multisampled rendering, except for
1.242 + the fact that it provides the only method of doing a multisample
1.243 + resovle from a multisample renderbuffer.
1.244 +
1.245 +Dependencies on OES_texture_3D
1.246 +
1.247 + On an OpenGL ES implementation, in the absense of OES_texture_3D,
1.248 + omit references to CopyTexSubImage3DOES.
1.249 +
1.250 +Errors
1.251 +
1.252 + The error INVALID_OPERATION is generated if ReadPixels or
1.253 + CopyTex{Sub}Image* is called while READ_FRAMEBUFFER_BINDING_ANGLE
1.254 + is non-zero, the read framebuffer is framebuffer complete, and the
1.255 + value of SAMPLE_BUFFERS for the read framebuffer is greater than
1.256 + zero.
1.257 +
1.258 + If both the draw and read framebuffers are framebuffer complete and
1.259 + the draw framebuffer has a value of SAMPLE_BUFFERS that is greater
1.260 + than zero, then the error INVALID_OPERATION is generated if
1.261 + BlitFramebufferANGLE is called.
1.262 +
1.263 + If both the draw and read framebuffers are framebuffer complete and
1.264 + the read framebuffer has a value of SAMPLE_BUFFERS that is greater
1.265 + than zero, the error INVALID_OPERATION is generated if
1.266 + BlitFramebufferANGLE is called and any of the following conditions
1.267 + are true:
1.268 + - <mask> includes DEPTH_BUFFER_BIT or STENCIL_BUFFER_BIT.
1.269 + - the source or destination rectangles do not specify the entire
1.270 + source or destination buffer.
1.271 +
1.272 + If both the draw and read framebuffers are framebuffer complete and
1.273 + either has a value of SAMPLE_BUFFERS that is greater than zero, then
1.274 + the error INVALID_OPERATION is generated if BlitFramebufferANGLE is
1.275 + called and the formats of the draw and read framebuffers are not
1.276 + identical.
1.277 +
1.278 + If either the draw or read framebuffer is framebuffer complete and
1.279 + has a value of SAMPLE_BUFFERS that is greater than zero, then the
1.280 + error INVALID_OPERATION is generated if BlitFramebufferANGLE is called
1.281 + and the specified source and destination dimensions are not
1.282 + identical.
1.283 +
1.284 + If RenderbufferStorageMultisampleANGLE is called with <target> not
1.285 + equal to RENDERBUFFER, the error INVALID_ENUM is generated.
1.286 +
1.287 + If RenderbufferStorageMultisampleANGLE is called with an
1.288 + <internalformat> that is not listed as one of the color-, depth-
1.289 + or stencil-renderable formats in Table 4.5, then the error
1.290 + INVALID_ENUM is generated.
1.291 +
1.292 + If RenderbufferStorageMultisampleANGLE is called with <width> or
1.293 + <height> greater than MAX_RENDERBUFFER_SIZE, then the error
1.294 + INVALID_VALUE is generated.
1.295 +
1.296 + If RenderbufferStorageMultisampleANGLE is called with a value of
1.297 + <samples> that is greater than MAX_SAMPLES_ANGLE or less than zero,
1.298 + then the error INVALID_VALUE is generated.
1.299 +
1.300 + The error OUT_OF_MEMORY is generated when
1.301 + RenderbufferStorageMultisampleANGLE cannot create storage of the
1.302 + specified size.
1.303 +
1.304 +New State
1.305 +
1.306 + Add to table 6.22 (Renderbuffer State)
1.307 +
1.308 + Get Value Type Get Command Initial Value Description Section
1.309 + ------------------------------- ------ -------------------------- ------------- -------------------- -------
1.310 + RENDERBUFFER_SAMPLES_ANGLE Z+ GetRenderbufferParameteriv 0 number of samples 4.4.3
1.311 +
1.312 +
1.313 + Add to table 6.yy (Framebuffer Dependent Vaues) (added by
1.314 + ANGLE_framebuffer_blit), the following new framebuffer dependent state.
1.315 +
1.316 + Get Value Type Get Command Minimum Value Description Section
1.317 + ----------------- ---- ----------- ------------- ------------------- -------
1.318 + MAX_SAMPLES_ANGLE Z+ GetIntegerv 1 Maximum number of 4.4.3
1.319 + samples supported
1.320 + for multisampling
1.321 +
1.322 +
1.323 +
1.324 +Issues
1.325 +
1.326 + Issues from EXT_framebuffer_multisample have been removed.
1.327 +
1.328 + 1) What should we call this extension?
1.329 +
1.330 + Resolved: ANGLE_framebuffer_blit.
1.331 +
1.332 + This extension is a result of a collaboration between Google and
1.333 + TransGaming for the open-source ANGLE project. Typically one would
1.334 + label a multi-vendor extension as EXT, but EXT_framebuffer_mulitsample
1.335 + is already the name for this on Desktop GL. Additionally this
1.336 + isn't truely a multi-vendor extension because there is only one
1.337 + implementation of this. We'll follow the example of the open-source
1.338 + MESA project which uses the project name for the vendor suffix.
1.339 +
1.340 + 2) How does this extension differ from EXT_framebuffer_multisample?
1.341 +
1.342 + This is designed to be a proper subset of EXT_framebuffer_multisample
1.343 + functionality as applicable to OpenGL ES 2.0.
1.344 +
1.345 + Functionality that is unchanged:
1.346 + - creation of multisample renderbuffers.
1.347 + - whole buffer multi-sample->single-sample resolve.
1.348 + - no format conversions, stretching or flipping supported on multisample blits.
1.349 +
1.350 + Additional restrictions on BlitFramebufferANGLE:
1.351 + - multisample resolve is only supported on color buffers.
1.352 + - no blits to multisample destinations (no single->multi or multi-multi).
1.353 + - only entire buffers can be resolved.
1.354 +
1.355 +Revision History
1.356 +
1.357 + Revision 1, 2010/07/08
1.358 + - copied from revision 7 of EXT_framebuffer_multisample
1.359 + - removed language that was not relevant to ES2
1.360 + - rebase changes against the Open GL ES 2.0 specification
1.361 + - added ANGLE-specific restrictions
1.362 + Revision 2, 2010/07/19
1.363 + - fix missing error code
1.364 + Revision 3, 2010/08/06
1.365 + - add additional contributors, update implementation status
1.366 + - disallow negative samples
