The Tor Browser: gfx/angle/extensions/EXT_draw_buffers.txt@b8a032363ba2 (annotated)

gfx/angle/extensions/EXT_draw_buffers.txt@b8a032363ba2 (annotated)

gfx/angle/extensions/EXT_draw_buffers.txt

Thu, 22 Jan 2015 13:21:57 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Thu, 22 Jan 2015 13:21:57 +0100
branch: TOR_BUG_9701
changeset 15: b8a032363ba2
permissions: -rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

 Name
     EXT_draw_buffers
 Name Strings
     GL_EXT_draw_buffers
 Contributors
     Contributors to GL_NV_draw_buffers
     Contributors to GL_NV_fbo_color_attachments
     Contributors to the OpenGL ES 2.0 specification
     Contributors to the OpenGLSL ES 1.0.17 specification
     Contributors to the OpenGL ES 3.0 specification
     Nicolas Capens, TransGaming Inc.
     Daniel Koch, TransGaming Inc.
     Alastair Patrick, Google Inc.
     Kenneth Russell, Google Inc.
     Greg Roth, NVIDIA Corporation
     Ben Bowman, Imagination Technologies
     Members of the WebGL and OpenGL ES working groups
 Contact
     Daniel Koch (daniel 'at' transgaming.com)
 Status
     Draft Complete
 Version
     Last Modified Date: January 30, 2013
     Revision: #7
 Number
     TBD
 Dependencies
     OpenGL ES 2.0 is required.
     The extension is written against the OpenGL ES 2.0 specification.
     ANGLE_framebuffer_blit affects the definition of this extension.
     APPLE_framebuffer_multisample affects the definitin of this extension.
 Overview
     This extension increases the number of available framebuffer object
     color attachment points, extends OpenGL ES 2.0 to allow multiple output
     colors, and provides a mechanism for directing those outputs to
     multiple color buffers.
     This extension is similar to the combination of the GL_NV_draw_buffers
     and GL_NV_fbo_color_attachments extensions, but imposes certain
     restrictions informed by the OpenGL ES 3.0 API.
 New Procedures and Functions
       void DrawBuffersEXT(sizei n, const enum *bufs);
 New Tokens
     Accepted by the <pname> parameter of GetIntegerv:
         MAX_COLOR_ATTACHMENTS_EXT             0x8CDF
     Accepted by the <pname> parameters of GetIntegerv and GetFloatv:
         MAX_DRAW_BUFFERS_EXT                  0x8824
         DRAW_BUFFER0_EXT                      0x8825
         DRAW_BUFFER1_EXT                      0x8826
         DRAW_BUFFER2_EXT                      0x8827
         DRAW_BUFFER3_EXT                      0x8828
         DRAW_BUFFER4_EXT                      0x8829
         DRAW_BUFFER5_EXT                      0x882A
         DRAW_BUFFER6_EXT                      0x882B
         DRAW_BUFFER7_EXT                      0x882C
         DRAW_BUFFER8_EXT                      0x882D
         DRAW_BUFFER9_EXT                      0x882E
         DRAW_BUFFER10_EXT                     0x882F
         DRAW_BUFFER11_EXT                     0x8830
         DRAW_BUFFER12_EXT                     0x8831
         DRAW_BUFFER13_EXT                     0x8832
         DRAW_BUFFER14_EXT                     0x8833
         DRAW_BUFFER15_EXT                     0x8834
     Accepted by the <attachment> parameter of FramebufferRenderbuffer,
     FramebufferTexture2D and GetFramebufferAttachmentParameteriv, and by
     the <bufs> parameter of DrawBuffersEXT:
         COLOR_ATTACHMENT0_EXT                      0x8CE0
         COLOR_ATTACHMENT1_EXT                      0x8CE1
         COLOR_ATTACHMENT2_EXT                      0x8CE2
         COLOR_ATTACHMENT3_EXT                      0x8CE3
         COLOR_ATTACHMENT4_EXT                      0x8CE4
         COLOR_ATTACHMENT5_EXT                      0x8CE5
         COLOR_ATTACHMENT6_EXT                      0x8CE6
         COLOR_ATTACHMENT7_EXT                      0x8CE7
         COLOR_ATTACHMENT8_EXT                      0x8CE8
         COLOR_ATTACHMENT9_EXT                      0x8CE9
         COLOR_ATTACHMENT10_EXT                     0x8CEA
         COLOR_ATTACHMENT11_EXT                     0x8CEB
         COLOR_ATTACHMENT12_EXT                     0x8CEC
         COLOR_ATTACHMENT13_EXT                     0x8CED
         COLOR_ATTACHMENT14_EXT                     0x8CEE
         COLOR_ATTACHMENT15_EXT                     0x8CEF
     The COLOR_ATTACHMENT0_EXT constant is equal to the
     COLOR_ATTACHMENT0 constant.
     Each COLOR_ATTACHMENT<i>_EXT adheres to COLOR_ATTACHMENT<i>_EXT
     = COLOR_ATTACHMENT0_EXT + <i>.
 Changes to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization)
     Section 3.2, (Multisampling). Replace the second paragraph:
     An additional buffer, called the multisample buffer, is added to the
     window system-provided framebuffer. Pixel sample values, including
     color, depth, and stencil values, are stored in this buffer. Samples
     contain separate color values for each fragment color. When the
     window system-provided framebuffer includes a multisample buffer, it
     does not include depth or stencil buffers, even if the multisample
     buffer does not store depth or stencil values. Color buffers do
     coexist with the multisample buffer, however.
     Section 3.8.2, (Shader Execution) Replace subsection "Shader
     Outputs":
     The OpenGL ES Shading Language specification describes the values
     that may be output by a fragment shader. These are gl_FragColor and
     gl_FragData[n].  The final fragment color values or the final
     fragment data values written by a fragment shader are clamped to the
     range [0, 1] and then converted to fixed-point as described in
     section 2.1.2 for framebuffer color components.
     Writing to gl_FragColor specifies the fragment color (color number
     zero) that will be used by subsequent stages of the pipeline.
     Writing to gl_FragData[n] specifies the value of fragment color
     number n. Any colors, or color components, associated with a
     fragment that are not written by the fragment shader are undefined.
     A fragment shader may not statically assign values to both
     gl_FragColor and gl_FragData. In this case, a compile or link error
     will result. A shader statically assigns a value to a variable if,
     after preprocessing, it contains a statement that would write to the
     variable, whether or not run-time flow of control will cause that
     statement to be executed.
 Changes to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment
 Operations and the Frame Buffer)
     Modify the overview of Chapter 4 and replace the sentences
     of the fifth paragraph which read:
     "The name of the color buffer of an application-created framebuffer
     object is COLOR_ATTACHMENT0. The names of the depth and stencil buffers
     are DEPTH_ATTACHMENT and STENCIL_ATTACHMENT."
     With the following:
     "A framebuffer object has an array of color buffer attachment points,
     numbered zero through <n>, a depth buffer attachment point, and a
     stencil buffer attachment point."
     Insert Table 4.3 to Section 4.2.1 (and renumber subsequent tables):
     Symbolic Constant                       Meaning
     -----------------                       ---------------------
     NONE                                    No buffer
     COLOR_ATTACHMENT<i>_EXT (see caption)   Output fragment color to image
                                             attached at color attachment
                                             point i
     Table 4.3: Arguments to DrawBuffersEXT when the context is bound to a
     framebuffer object, and the buffers they indicate. <i> in
     COLOR_ATTACHMENT<i>_EXT may range from zero to the value of
     MAX_COLOR_ATTACHMENTS_EXT minus one.
     Replace Section 4.2.1, "Selecting a Buffer for Writing" with the following:
     "By default, color values are written into the front buffer for
     single buffered surfaces or into the back buffer for back buffered
     surfaces as determined when making the context current. To control
     the color buffer into which each of the fragment color values is
     written, DrawBuffersEXT is used.
     The command
       void DrawBuffersEXT(sizei n, const enum *bufs);
     defines the draw buffers to which all fragment colors are written.
     <n> specifies the number of buffers in <bufs>. <bufs> is a pointer
     to an array of symbolic constants specifying the buffer to which
     each fragment color is written.
     Each buffer listed in <bufs> must be BACK, NONE, or one of the
     values from table 4.3. Further, acceptable values for the constants
     in <bufs> depend on whether the GL is using the default framebuffer
     (i.e., DRAW_FRAMEBUFFER_BINDING is zero), or a framebuffer object
     (i.e., DRAW_FRAMEBUFFER_BINDING is non-zero). For more information
     about framebuffer objects, see section 4.4.
     If the GL is bound to the default framebuffer, then <n> must be 1
     and the constant must be BACK or NONE. When draw buffer zero is
     BACK, color values are written into the sole buffer for single-
     buffered contexts, or into the back buffer for double-buffered
     contexts. If DrawBuffersEXT is supplied with a constant other than
     BACK and NONE, the error INVALID_OPERATION is generated.
     If the GL is bound to a draw framebuffer object, then each of the
     constants must be one of the values listed in table 4.3.
     In both cases, the draw buffers being defined correspond in order to
     the respective fragment colors. The draw buffer for fragment
     colors beyond <n> is set to NONE.
     The maximum number of draw buffers is implementation-dependent. The
     number of draw buffers supported can be queried by calling
     GetIntegerv with the symbolic constant MAX_DRAW_BUFFERS_EXT. An
     INVALID_VALUE error is generated if <n> is greater than
     MAX_DRAW_BUFFERS_EXT.
     If the GL is bound to a draw framebuffer object, the <i>th buffer listed
     in <bufs> must be COLOR_ATTACHMENT<i>_EXT or NONE. Specifying a
     buffer out of order, BACK, or COLOR_ATTACHMENT<m>_EXT where <m> is
     greater than or equal to the value of MAX_COLOR_ATTACHMENTS_EXT,
     will generate the error INVALID_OPERATION.
     If a fragment shader writes to "gl_FragColor", DrawBuffersEXT
     specifies the set of draw buffers into which the color
     written to "gl_FragColor" is written. If a fragment shader writes to
     "gl_FragData", DrawBuffersEXT specifies a set of draw buffers
     into which each of the multiple output colors defined by these
     variables are separately written. If a fragment shader writes to
     neither "gl_FragColor" nor "gl_FragData" the values of the
     fragment colors following shader execution are undefined, and may
     differ for each fragment color.
     Indicating a buffer or buffers using DrawBuffersEXT causes
     subsequent pixel color value writes to affect the indicated
     buffers. If the GL is bound to a draw framebuffer object and a draw
     buffer selects an attachment that has no image attached, then that
     fragment color is not written.
     Specifying NONE as the draw buffer for a fragment color will inhibit
     that fragment color from being written.
     The state required to handle color buffer selection for each
     framebuffer is an integer for each supported fragment color. For the
     default framebuffer, in the initial state the draw buffer for
     fragment color zero is BACK if there is a default framebuffer
     associated with the context, otherwise NONE. For framebuffer
     objects, in the initial state the draw buffer for fragment color
     zero is COLOR_ATTACHMENT0_EXT.
     For both the default framebuffer and framebuffer objects, the
     initial state of draw buffers for fragment colors other than zero is
     NONE.
     The value of the draw buffer selected for fragment color <i> can be
     queried by calling GetIntegerv with the symbolic constant
     DRAW_BUFFER<i>_EXT."
     Modify Section 4.2.3 (Clearing the Buffers) and replace the first
     two paragraphs with the following:
     "The GL provides a means for setting portions of every pixel in a
     particular buffer to the same value.  The argument to
         void Clear(bitfield buf);
     is the bitwise OR of a number of values indicating which buffers are
     to be cleared. The values are COLOR_BUFFER_BIT, DEPTH_BUFFER_BIT, and
     STENCIL_BUFFER_BIT, indicating the buffers currently enabled for color
     writing, the depth buffer, and the stencil buffer (see below),
     respectively. The value to which each buffer is cleared depends on
     the setting of the clear value for that buffer.  If the mask is not a
     bitwise OR of the specified values, then the error INVALID_VALUE is
     generated.
         void ClearColor(clampf r, clampf, g, clampf b, clampf a);
     sets the clear value for fixed-point color buffers.  Each of the
     specified components is clamped to [0, 1] and converted to fixed-point
     as described in section 2.1.2 for framebuffer color components."
     Replace the second paragraph of Section 4.4.1 (Binding and Managing
     Framebuffer Objects) with the following:
     "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 the
     target FRAMEBUFFER, DRAW_FRAMEBUFFER, or READ_FRAMEBUFFER. The binding
     is effected by calling
         void BindFramebuffer(enum target, uint framebuffer);
     with <target> set the desired framebuffer target and <framebuffer> set
     to the unused name. The resulting framebuffer object is a new state
     vector. There is a number of color attachment points, plus one each
     for the depth and stencil attachment points. The number of color attachment
     points is equal to the value of MAX_COLOR_ATTACHMENTS_EXT."
     Replace the third item in the bulleted list in Section 4.4.1 (Binding
     and Managing Framebuffer Objects) with the following:
     " * The only color buffer bitplanes are the ones defined by the
     framebuffer attachments points named COLOR_ATTACHMENT0_EXT through
     COLOR_ATTACHMENT<n>_EXT."
     Modify Section 4.4.3 (Renderbuffer Objects) in the
     "Attaching Renderbuffer Images to a Framebuffer" subsection as follows:
     Insert the following table:
     Name of attachment
     ---------------------------------------
     COLOR_ATTACHMENT<i>_EXT (see caption)
     DEPTH_ATTACHMENT
     STENCIL_ATTACHMENT
     Table 4.x: Framebuffer attachment points. <i> in COLOR_ATTACHMENT<i>_EXT
     may range from zero to the value of MAX_COLOR_ATTACHMENTS_EXT minus 1.
     Modify the third sentence of the paragraph following the definition of
     FramebufferRenderbuffer to be as follows:
     "<attachment> should be set to one of the attachment points of the
     framebuffer listed in Table 4.x."
     Modify Section 4.4.3 (Renderbuffer Objects) in the "Attaching Texture
     Images to a Framebuffer" subsection as follows:
     Modify the last sentence of the paragraph following the definition of
     FramebufferTexture2D to be as follows:
     "<attachment> must be one of the attachment points of the framebuffer
     listed in Table 4.x."
     Modify Section 4.4.5 (Framebuffer Completeness) and replace the 3rd
     item in the bulleted list in the "Framebuffer Attachment Completeness"
     subsection with the following:
     " * If <attachment> is COLOR_ATTACHMENT<i>_EXT, then <image> must
     have a color-renderable internal format."
 Changes to Chapter 6 of the OpenGL ES 2.0 Specification (State and
 State Requests)
     In section 6.1.3 (Enumerated Queries) modify the third sentence in
     the definition of GetFramebufferAttachmentParameteriv to be as follows:
     "<attachment> must be one of the attachment points of the framebuffer
     listed in Table 4.x."
 Changes to Chapter 3 of the OpenGL ES Shading Language 1.0.17 Specification (Basics)
     Add a new section:
 .4.1 GL_EXT_draw_buffers Extension
     To use the GL_EXT_draw_buffers extension in a shader it
     must be enabled using the #extension directive.
     The shading language preprocessor #define
     GL_EXT_draw_buffers will be defined to 1, if the
     GL_EXT_draw_buffers extension is supported.
 Dependencies on ANGLE_framebuffer_blit and APPLE_framebuffer_multisample:
     If neither ANGLE_framebuffer_blit nor APPLE_framebuffer_multisample are
     supported, then all references to "draw framebuffers" should be replaced
     with references to "framebuffers". References to DRAW_FRAMEBUFFER_BINDING
     should be replaced with references to FRAMEBUFFER_BINDING. References to
     DRAW_FRAMEBUFFER and READ_FRAMEBUFFER should be removed.
     If ANGLE_framebuffer_blit is supported, DRAW_FRAMEBUFFER_BINDING, DRAW_FRAMEBUFFER
     and READ_FRAMEBUFFER all refer to corresponding _ANGLE suffixed names
     (they have the same token values).
     If APPLE_framebuffer_multisample is supported, DRAW_FRAMEBUFFER_BINDING,
     DRAW_FRAMEBUFFER and READ_FRAMEBUFFER all refer to the corresponding _APPLE
     suffixed names (they have the same token values).
 Errors
     The INVALID_OPERATION error is generated if DrawBuffersEXT is called
     when the default framebuffer is bound and any of the following conditions
     hold:
      - <n> is greater than 1 and less than MAX_DRAW_BUFFERS_EXT,
      - <bufs> contains a value other than BACK or NONE.
     The INVALID_OPERATION error is generated if DrawBuffersEXT is called
     when bound to a draw framebuffer object and any of the following
     conditions hold:
      - the <i>th value in <bufs> is not COLOR_ATTACHMENT<i>_EXT or NONE.
     The INVALID_VALUE error is generated if DrawBuffersEXT is called
     with a value of <n> which is greater than MAX_DRAW_BUFFERS_EXT.
     The INVALID_ENUM error is generated by FramebufferRenderbuffer if
     the <attachment> parameter is not one of the values listed in Table 4.x.
     The INVALID_ENUM error is generated by FramebufferTexture2D if
     the <attachment> parameter is not one of the values listed in Table 4.x.
     The INVALID_ENUM error is generated by GetFramebufferAttachmentParameteriv
     if the <attachment> parameter is not one of the values listed in Table 4.x.
 New State
     Add Table 6.X Framebuffer (State per framebuffer object):
     State               Type Get Command  Initial Value Description
     ------------------  ---- ------------ ------------- -----------
     DRAW_BUFFER<i>_EXT  Z10* GetIntegerv  see 4.2.1     Draw buffer selected
 							  for fragment color i
     Add to Table 6.18 (Implementation Dependent Values)
     Get value                 Type Get Cmnd    Minimum Value Description             Sec.
     --------------------      ---- ----------- ------------- -----------             -----
     MAX_DRAW_BUFFERS_EXT      Z+   GetIntegerv 1             Maximum number of       4.2.1
                                                              active draw buffers
     MAX_COLOR_ATTACHMENTS_EXT Z+   GetIntegerv 1             Number of framebuffer   4.4.1
                                                              color attachment points
 Issues
     See ARB_draw_buffers for relevant issues.
 ) What are the differences between this extension and NV_draw_buffers
     + NV_fbo_color_attachments?
     RESOLVED. This extension:
      - adds interactions with blit_framebuffer and the separate
        draw/read binding points
      - The draw buffer and color attachment limits are global instead
        of per-fbo (see Issue 2)
      - can be used to with default framebuffer to set NONE/BACK (see Issue 4)
      - retains the ordering restrictions on color attachments that are
        imposed by ES 3.0.
 ) Should the MAX_DRAW_BUFFERS_EXT and MAX_COLOR_ATTACHMENTS_EXT limits
     be per-framebuffer values or implementation dependent constants?
     DISCUSSION: In ARB_draw_buffers this was per-context (see Issue 2).
     EXT_framebuffer_object (and subsequently ARB_framebuffer_object, and GL 3.0
     through GL 4.2) made these queries framebuffer-dependent.
     However in GL 4.3 and GLES 3.0, these limits were changed from
     framebuffer-dependent state to implementation-dependent state after
     much discussion (Bug 7990).
     NV_draw_buffers has MAX_DRAW_BUFFERS listed as per-framebuffer state,
     but NV_fbo_color_attachments has MAX_COLOR_ATTACHMENTS as an
     implementation-dependent constant.
     This is relevant because some implementations are not able to support
     multisampling in conjuction with multiple color attachments.  If the
     query is per-framebuffer, they can report a maximum of one attachment
     when there are multisampled attachments, but a higher limit when only
     single-sampled attachments are present.
     RESOLVED. Make this global context state as this is most consistent
     with GLES 3.0 and updated GL drivers. In an implementation cannot
     support multisampling in conjunction with multiple color attachments,
     perhaps such an implementation could report FBO incomplete in this
     situation, but this is less than desirable.
 ) Should we support broadcast from gl_FragColor to all gl_FragData[x]
     or should it be synonymous with gl_FragData[0]?
     DISCUSSION: With NV_draw_buffers, writing to gl_FragColor writes to all
     the enabled draw buffers (ie broadcast). In OpenGL ES 3.0 when using
     ESSL 1.0, gl_FragColor is equivalent to writing a single output to
     gl_FragData[0] and multiple outputs are not possible. When using ESSL 3.0,
     only user-defined out variables may be used.
     If broadcast is supported, some implementations may have to replace
     writes to gl_FragColor with replicated writes to all possible gl_FragData
     locations when this extension is enabled.
     RESOLVED: Writes to gl_FragColor are broadcast to all enabled color
     buffers. ES 3.0 using ESSL 1.0 doesn't support broadcast because
     ESSL 1.0 was not extended to have multiple color outputs (but that is
     what this extension adds). ESSL 3.0 doesn't support the broadcast because
     it doesn't have the gl_FragColor variable at all, and only has user-
     defined out variables. This extension extends ESSL 1.0 to have multiple
     color outputs. Broadcasting from gl_FragColor to all enabled color
     buffers is the most consistent with existing draw buffer extensions to
     date (both NV_draw_buffers and desktop GL).
 ) Should we allow DrawBuffersEXT to be called when the default FBO is
     bound?
     DISCUSSION: NV_draw_buffers specifies that DrawBuffersNV errors with
     INVALID_OPERATION when the default FBO is bound. OpenGL ES 3.0 allows
     DrawBuffers to toggle between BACK and NONE on the default FBO.
     An implementation that does not natively support disabling the drawbuffer
     on the default FBO could emulate this by disabling color writes.
     RESOLVED: Allow DrawBuffersEXT to be called for the default FBO. This
     is more forward looking and is compatible with ES 3.0.
 ) What are the requirements on the color attachment sizes and formats?
     RESOLVED: ES 2.0 requires that all color buffers attached to application-
     created framebuffer objects must have the same number of bitplanes
     (Chapter 4 overview p91). ES 2.0 also requires that all attached images
     have the same width and height (Section 4.4.5 Framebuffer Completeness).
     This extension does not lift those requirements, and failing to meet
     them will result in an incomplete FBO.
 ) Does this have any interactions with glClear?
     RESOLVED: Yes. When multiple color buffers are enabled for writing,
     glClear clears all of the color buffers.  Added language clarifying
     that glClear and glClearColor may affect multiple color buffers.
 Revision History
 /30/2013  dgkoch  add issue 6 and clear interactions
                         renamed to EXT_draw_buffers based on feedback
                         changed resolution of issue 3.
 /23/2013  dgkoch  add resolutions to issues 2-4.
                         add issue 5.
                         Add Table 4.x and update various explicit
                         references to COLOR_ATTACHMENT0.
                         Add errors.
 /13/2012  dgkoch  add revision history
                         add text from updated ES 3.0 spec
                         add issues for discussion
 /16/2012  kbr     update name string
 /16/2012  kbr     remove restrition requiring draw buffer 0 to be non-NULL
 /12/2012  kbr     remove references to GetDoublev and ReadBuffer
 /11/2012  kbr     initial draft extension

The Tor Browser / annotate

gfx/angle/extensions/EXT_draw_buffers.txt@b8a032363ba2 (annotated)

gfx/angle/extensions/EXT_draw_buffers.txt