| Name | |
| APPLE_framebuffer_multisample | |
| Name Strings | |
| GL_APPLE_framebuffer_multisample | |
| Contributors | |
| Contributors to EXT_framebuffer_multisample and EXT_framebuffer_blit | |
| desktop OpenGL extensions from which this extension borrows heavily. | |
| Contacts | |
| Benj Lipchak, Apple (lipchak 'at' apple.com) | |
| Status | |
| Complete | |
| Version | |
| Last Modified Date: February 24, 2011 | |
| Revision: #4 | |
| Number | |
| OpenGL ES Extension #78 | |
| Dependencies | |
| Requires GL_OES_framebuffer_object or OpenGL ES 2.0. | |
| Written based on the wording of the OpenGL ES 2.0 specification. | |
| OpenGL ES 1.1 affects the definition of this extension. | |
| EXT_discard_framebuffer affects the definition of this extension. | |
| Overview | |
| This extension extends the framebuffer object framework to | |
| enable multisample rendering. | |
| The new operation RenderbufferStorageMultisampleAPPLE() allocates | |
| storage for a renderbuffer object that can be used as a multisample | |
| buffer. A multisample render buffer image differs from a | |
| single-sample render buffer image in that a multisample image has a | |
| number of SAMPLES that is greater than zero. No method is provided | |
| for creating multisample texture images. | |
| All of the framebuffer-attachable images attached to a framebuffer | |
| object must have the same number of SAMPLES or else the framebuffer | |
| object is not "framebuffer complete". If a framebuffer object with | |
| multisample attachments is "framebuffer complete", then the | |
| framebuffer object behaves as if SAMPLE_BUFFERS is one. | |
| The resolve operation is affected by calling | |
| ResolveMultisampleFramebufferAPPLE where the source is a multisample | |
| application-created framebuffer object and the destination is a | |
| single-sample framebuffer object. Separate read and draw framebuffer | |
| object binding points are established to facilitate the resolve. | |
| Scissoring may be used in conjunction with | |
| ResolveMultisampleFramebufferAPPLE to resolve only a portion of the | |
| framebuffer. | |
| IP Status | |
| No known IP claims. | |
| New Procedures and Functions | |
| void RenderbufferStorageMultisampleAPPLE( | |
| enum target, sizei samples, | |
| enum internalformat, | |
| sizei width, sizei height); | |
| void ResolveMultisampleFramebufferAPPLE(void); | |
| New Tokens | |
| Accepted by the <pname> parameter of GetRenderbufferParameteriv: | |
| RENDERBUFFER_SAMPLES_APPLE 0x8CAB | |
| Returned by CheckFramebufferStatus: | |
| FRAMEBUFFER_INCOMPLETE_MULTISAMPLE_APPLE 0x8D56 | |
| Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, and | |
| GetFloatv: | |
| MAX_SAMPLES_APPLE 0x8D57 | |
| Accepted by the <target> parameter of BindFramebuffer, | |
| CheckFramebufferStatus, FramebufferTexture2D, FramebufferRenderbuffer, and | |
| GetFramebufferAttachmentParameteriv: | |
| READ_FRAMEBUFFER_APPLE 0x8CA8 | |
| DRAW_FRAMEBUFFER_APPLE 0x8CA9 | |
| Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, and | |
| GetFloatv: | |
| DRAW_FRAMEBUFFER_BINDING_APPLE 0x8CA6 // FRAMEBUFFER_BINDING | |
| READ_FRAMEBUFFER_BINDING_APPLE 0x8CAA | |
| Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL ES Operation) | |
| None | |
| Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization) | |
| None | |
| Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment | |
| Operations and the Framebuffer) | |
| Change the first word of Chapter 4 from "The" to "A". | |
| Append to the introduction of Chapter 4: | |
| "Conceptually, the GL has two active framebuffers; the draw | |
| framebuffer is the destination for rendering operations, and the | |
| read framebuffer is the source for readback operations. The same | |
| framebuffer may be used for both drawing and reading. Section | |
| 4.4.1 describes the mechanism for controlling framebuffer usage." | |
| Modify the last paragraph of section 4.1.1 as follows: | |
| "While an application-created framebuffer object is bound to | |
| DRAW_FRAMEBUFFER_APPLE, the pixel ownership test always passes." | |
| Add to 4.3.2 (Reading Pixels), right before the subsection titled | |
| "Obtaining Pixels from the Framebuffer": | |
| "ReadPixels generates INVALID_FRAMEBUFFER_OPERATION if the object bound to | |
| READ_FRAMEBUFFER_APPLE is not framebuffer complete (see section 4.4.5). | |
| ReadPixels generates INVALID_OPERATION if the object bound to | |
| READ_FRAMEBUFFER_APPLE is framebuffer complete and the value of | |
| SAMPLE_BUFFERS for the read framebuffer is greater than zero." | |
| Replace the first paragraph of the subsection titled "Obtaining Pixels | |
| from the Framebuffer" with the following: | |
| "The buffer from which values are obtained is the color buffer used for | |
| reading. If READ_FRAMEBUFFER_BINDING_APPLE is non-zero, pixel values are | |
| read from the buffer attached as the COLOR_ATTACHMENT0 attachment to the | |
| currently bound read framebuffer object." | |
| Modify the beginning of section 4.4.1 as follows: | |
| "The operations described in chapter 4 affect the images attached to the | |
| framebuffer objects bound to targets READ_FRAMEBUFFER_APPLE and | |
| DRAW_FRAMEBUFFER_APPLE. By default, the framebuffer bound to these | |
| targets is zero, specifying the default implementation-dependent | |
| framebuffer provided by the windowing system. When the framebuffers bound | |
| to these targets is not zero, but instead names an application-created | |
| framebuffer object, then the operations described in chapter 4 affect the | |
| application-created framebuffer object rather than the default framebuffer. | |
| The namespace for framebuffer objects is the unsigned integers, with zero | |
| reserved by OpenGL ES to refer to the default framebuffer. A framebuffer | |
| object is created by binding an unused name to DRAW_FRAMEBUFFER_APPLE or | |
| READ_FRAMEBUFFER_APPLE. The binding is effected by calling | |
| void BindFramebuffer(enum target, uint framebuffer); | |
| with <target> set to the desired framebuffer target and | |
| <framebuffer> set to the unused name. The resulting framebuffer | |
| object is a new state vector. There is one color attachment points, plus | |
| one each for the depth and stencil attachment points. | |
| BindFramebuffer may also be used to bind an existing framebuffer object to | |
| <target>. If the bind is successful no change is made to the state of the | |
| bound framebuffer object, and any previous binding to <target> is broken. | |
| The current DRAW_FRAMEBUFFER_APPLE and READ_FRAMEBUFFER_APPLE bindings can | |
| be queried using GetIntegerv(DRAW_FRAMEBUFFER_BINDING_APPLE) and | |
| GetIntegerv(READ_FRAMEBUFFER_BINDING_APPLE), respectively. | |
| If a framebuffer object is bound to DRAW_FRAMEBUFFER_APPLE or | |
| READ_FRAMEBUFFER_APPLE, it becomes the destination of fragment operations | |
| or the source of pixel reads, respectively, until it is deleted or another | |
| framebuffer is bound to the corresponding bind point. Calling | |
| BindFramebuffer with <target> set to FRAMEBUFFER binds the | |
| framebuffer to both DRAW_FRAMEBUFFER_APPLE and READ_FRAMEBUFFER_APPLE. | |
| While a framebuffer object is bound, OpenGL ES operations on the target | |
| to which it is bound affect the images attached to the bound | |
| framebuffer object, and queries of the target to which it is bound | |
| return state from the bound object. In particular, queries of the values | |
| specified in table 6.20 (Implementation Dependent Pixel Depths) are | |
| derived from the framebuffer object bound to DRAW_FRAMEBUFFER_APPLE. | |
| In the initial state, the reserved name zero is bound to the targets | |
| DRAW_FRAMEBUFFER_APPLE and READ_FRAMEBUFFER_APPLE. There is no application | |
| created framebuffer object corresponding to the name zero. Instead, the | |
| name zero refers to the window-system-provided framebuffer. All Queries | |
| and operations on the framebuffer while the name zero is bound to target | |
| DRAW_FRAMEBUFFER_APPLE or READ_FRAMEBUFFER_APPLE operate on this default | |
| framebuffer..." | |
| Change the description of DeleteFramebuffers as follows: | |
| "<framebuffers> contains <n> names of framebuffer objects to be | |
| deleted. After a framebuffer object is deleted, it has no | |
| attachments, and its name is again unused. If a framebuffer that | |
| is currently bound to one or more of the targets | |
| DRAW_FRAMEBUFFER_APPLE or READ_FRAMEBUFFER_APPLE is deleted, it is as | |
| though BindFramebuffer had been executed with the corresponding | |
| <target> and <framebuffer> of zero. Unused names in <framebuffers> | |
| are silently ignored, as is the value zero." | |
| Add to section 4.4.3, just above the definition of RenderbufferStorage: | |
| "The command | |
| void RenderbufferStorageMultisampleAPPLE( | |
| enum target, sizei samples, | |
| enum internalformat, | |
| sizei width, sizei height); | |
| establishes the data storage, format, dimensions, and number of | |
| samples of a renderbuffer object's image. <target> must be | |
| RENDERBUFFER. <internalformat> must be one of the color-renderable, | |
| depth-renderable, or stencil-renderable formats described in table 4.5. | |
| <width> and <height> are the dimensions in pixels of the renderbuffer. If | |
| either <width> or <height> is greater than the value of | |
| MAX_RENDERBUFFER_SIZE, or if <samples> is greater than MAX_SAMPLES_APPLE, | |
| then the error INVALID_VALUE is generated. If OpenGL ES is unable to | |
| create a data store of the requested size, the error OUT_OF_MEMORY is | |
| generated. RenderbufferStorageMultisampleAPPLE deletes any existing | |
| data store for the renderbuffer and the contents of the data store after | |
| calling RenderbufferStorageMultisampleAPPLE are undefined. | |
| If <samples> is zero, then RENDERBUFFER_SAMPLES_APPLE is set to zero. | |
| Otherwise <samples> represents a request for a desired minimum | |
| number of samples. Since different implementations may support | |
| different sample counts for multisampled rendering, the actual | |
| number of samples allocated for the renderbuffer image is | |
| implementation dependent. However, the resulting value for | |
| RENDERBUFFER_SAMPLES_APPLE is guaranteed to be greater than or equal | |
| to <samples> and no more than the next larger sample count supported | |
| by the implementation. | |
| An OpenGL ES implementation may vary its allocation of internal component | |
| resolution based on any RenderbufferStorageMultisampleAPPLE parameter | |
| (except target), but the allocation and chosen internal format must not be | |
| a function of any other state and cannot be changed once they are | |
| established. The actual resolution in bits of each component of the | |
| allocated image can be queried with GetRenderbufferParameteriv." | |
| Modify the definiton of RenderbufferStorage in section 4.4.3 as follows: | |
| "The command | |
| void RenderbufferStorage( | |
| enum target, enum internalformat, | |
| sizei width, sizei height); | |
| is equivalent to calling RenderbufferStorageMultisampleAPPLE with | |
| <samples> equal to zero." | |
| In section 4.4.3, modify the first two sentences of the | |
| description of FramebufferRenderbuffer as follows: | |
| "<target> must be DRAW_FRAMEBUFFER_APPLE, READ_FRAMEBUFFER_APPLE, or | |
| FRAMEBUFFER. If <target> is FRAMEBUFFER, it behaves as | |
| though DRAW_FRAMEBUFFER_APPLE were specified. INVALID_OPERATION is | |
| generated if the current value of the corresponding binding is zero | |
| when FramebufferRenderbuffer is called." | |
| In section 4.4.3, modify the first two sentences of the | |
| description of FramebufferTexture2D as follows: | |
| "The <target> must be DRAW_FRAMEBUFFER_APPLE, READ_FRAMEBUFFER_APPLE, or | |
| FRAMEBUFFER. If <target> is FRAMEBUFFER, it behaves as though | |
| DRAW_FRAMEBUFFER_APPLE were specified. INVALID_OPERATION is generated if | |
| the current value of the corresponding binding is zero when | |
| FramebufferTexture2D is called." | |
| In section 4.4.5, add an entry to the Framebuffer Completeness bullet list: | |
| "* All attached images have the same number of samples. | |
| FRAMEBUFFER_INCOMPLETE_MULTISAMPLE_APPLE" | |
| In section 4.4.5, modify the first sentence of the description | |
| of CheckFramebufferStatus as follows: | |
| "If <target> is not DRAW_FRAMEBUFFER_APPLE, READ_FRAMEBUFFER_APPLE, or | |
| FRAMEBUFFER, INVALID_ENUM is generated. If <target> is FRAMEBUFFER, it | |
| behaves as though DRAW_FRAMEBUFFER_APPLE were specified." | |
| Modify the first sentence of the last paragraph of section 4.4.5 as | |
| follows: | |
| "If the currently bound draw or read framebuffer is not framebuffer | |
| complete, then it is an error to attempt to use the framebuffer for | |
| writing or reading, respectively." | |
| In section 4.4.6, replace references to FRAMEBUFFER_BINDING with | |
| DRAW_FRAMEBUFFER_BINDING_APPLE. | |
| Add new section titled "Multisample Resolves" to section 4.4: | |
| "The command | |
| void ResolveMultisampleFramebufferAPPLE(void); | |
| converts the samples corresponding to each pixel location in the | |
| read framebuffer's color attachment to a single sample before writing | |
| them to the draw framebuffer's color attachment. | |
| The pixel copy bypasses the fragment pipeline. The only fragment | |
| operations which affect the resolve are the pixel ownership test, | |
| the scissor test, and dithering. | |
| INVALID_OPERATION is generated if SAMPLE_BUFFERS for the read framebuffer | |
| is zero, or if SAMPLE_BUFFERS for the draw framebuffer is greater than | |
| zero, or if the read framebuffer or draw framebuffer does not have a color | |
| attachment, or if the dimensions of the read and draw framebuffers | |
| are not identical, or if the components in the format of the draw | |
| framebuffer's color attachment are not present in the format of the read | |
| framebuffer's color attachment. | |
| INVALID_FRAMEBUFFER_OPERATION is generated if the objects bound to | |
| DRAW_FRAMEBUFFER_APPLE and READ_FRAMEBUFFER_APPLE are not framebuffer | |
| complete (see section 4.4.5)." | |
| Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special Functions) | |
| None | |
| Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and State | |
| Requests) | |
| In section 6.1.3, modify the first sentence of the description of | |
| GetFramebufferAttachmentParameteriv as follows: | |
| "<target> must be DRAW_FRAMEBUFFER_APPLE, READ_FRAMEBUFFER_APPLE or | |
| FRAMEBUFFER. If <target> is FRAMEBUFFER, it behaves as though | |
| DRAW_FRAMEBUFFER_APPLE were specified." | |
| In section 6.1.3, modify the third paragraph of the description of | |
| GetRenderbufferParameteriv as follows: | |
| "Upon successful return from GetRenderbufferParameteriv, if | |
| <pname> is RENDERBUFFER_WIDTH, RENDERBUFFER_HEIGHT, | |
| RENDERBUFFER_INTERNAL_FORMAT, or RENDERBUFFER_SAMPLES_APPLE, then <params> | |
| will contain the width in pixels, height in pixels, internal format, or | |
| number of samples, respectively, of the image of the renderbuffer | |
| currently bound to <target>." | |
| Move SAMPLES and SAMPLE_BUFFERS state to table 6.20. | |
| Dependencies on OpenGL ES 1.1 | |
| On an OpenGL ES 1.1 implementation, OES_framebuffer_object is required. | |
| Include GetFixedv where GetBooleanv, GetIntegerv and GetFloatv appear. | |
| Add OES suffixes to entrypoints and tokens introduced by | |
| OES_framebuffer_object. | |
| Dependencies on EXT_discard_framebuffer | |
| In the presence of EXT_discard_framebuffer, DiscardFramebufferEXT is | |
| modified to allow READ_FRAMEBUFFER_APPLE and DRAW_FRAMEBUFFER_APPLE | |
| as acceptable targets. If <target> is FRAMEBUFFER, DiscardFramebufferEXT | |
| behaves as though DRAW_FRAMEBUFFER_APPLE were specified. | |
| Errors | |
| INVALID_FRAMEBUFFER_OPERATION is generated if DrawArrays, DrawElements, or | |
| ResolveMultisampleFramebufferAPPLE is called while the draw framebuffer is | |
| not framebuffer complete. | |
| INVALID_FRAMEBUFFER_OPERATION is generated if ReadPixels, | |
| CopyTex{Sub}Image*, or ResolveMultisampleFramebufferAPPLE is called while | |
| the read framebuffer is not framebuffer complete. | |
| INVALID_OPERATION is generated if ReadPixels, or CopyTex{Sub}Image* is | |
| called while READ_FRAMEBUFFER_BINDING_APPLE is non-zero, the read | |
| framebuffer is framebuffer complete, and the value of SAMPLE_BUFFERS for | |
| the read framebuffer is greater than zero. | |
| INVALID_OPERATION is generated by ResolveMultisampleFramebufferAPPLE if | |
| SAMPLE_BUFFERS for the read framebuffer is zero, or if SAMPLE_BUFFERS for | |
| the draw framebuffer is greater than zero, or if the read framebuffer or | |
| draw framebuffer does not have a color attachment, or if the dimensions of | |
| the read and draw framebuffers are not identical, or if the components in | |
| the format of the draw framebuffer's color attachment are not present in | |
| the format of the read framebuffer's color attachment. | |
| OUT_OF_MEMORY is generated when RenderbufferStorageMultisampleAPPLE cannot | |
| create storage of the specified size. | |
| INVALID_VALUE is generated if RenderbufferStorageMultisampleAPPLE is | |
| called with a value of <samples> that is greater than MAX_SAMPLES_APPLE | |
| or with a value of <width> or <height> that is greater than | |
| MAX_RENDERBUFFER_SIZE. | |
| New State | |
| Add to table 6.19 (Implementation Dependent Values (cont.)): | |
| Get Value Type Get Command Minimum Value Description Section | |
| --------- ---- ----------- ------------- ------------------- ------- | |
| MAX_SAMPLES_APPLE Z+ GetIntegerv 1 Maximum number of 4.4.3 | |
| samples supported | |
| for multisampling | |
| Add to table 6.22 (Renderbuffer State): | |
| Get Value Type Get Command Initial Value Description Section | |
| -------------------------- ---- -------------------------- ------------- -------------------- ------- | |
| RENDERBUFFER_SAMPLES_APPLE Z+ GetRenderbufferParameteriv 0 Renderbuffer samples 4.4.3 | |
| Remove reference to FRAMEBUFFER_BINDING from Table 6.23 (Framebuffer State) | |
| and replace with the following: | |
| Get Value Type Get Command Initial Value Description Section | |
| ------------------------------ ---- ----------- ------------- ------------------------- ------- | |
| DRAW_FRAMEBUFFER_BINDING_APPLE Z+ GetIntegerv 0 Framebuffer object bound 4.4.1 | |
| to DRAW_FRAMEBUFFER_APPLE | |
| READ_FRAMEBUFFER_BINDING_APPLE Z+ GetIntegerv 0 Framebuffer object 4.4.1 | |
| to READ_FRAMEBUFFER_APPLE | |
| Revision History | |
| #4, February 24, 2011: Benj Lipchak | |
| - assign extension number | |
| - clarify that dithering is still performed during resolve | |
| - clarify that only format conversions that drop components are allowed | |
| during resolve | |
| #3, January 5, 2010: Benj Lipchak | |
| - remove the error when read and draw color formats are not identical | |
| - add an error when missing a color attachment to the read or draw FBO | |
| #2, October 29, 2009: Benj Lipchak | |
| - add interaction with EXT_discard_framebuffer | |
| - mention that scissoring can be used for partial resolves | |
| #1, October 28, 2009: Benj Lipchak | |
| - first revision |