The Tor Browser: comparison gfx/angle/extensions/EXT_draw

--1:000000000000
+:6d089c727695
+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:
+3.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.
+1) 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.
+2) 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.
+3) 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).
+4) 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.
+5) 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.
+6) 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
+01/30/2013  dgkoch  add issue 6 and clear interactions
+renamed to EXT_draw_buffers based on feedback
+changed resolution of issue 3.
+01/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.
+11/13/2012  dgkoch  add revision history
+add text from updated ES 3.0 spec
+add issues for discussion
+10/16/2012  kbr     update name string
+10/16/2012  kbr     remove restrition requiring draw buffer 0 to be non-NULL
+10/12/2012  kbr     remove references to GetDoublev and ReadBuffer
+10/11/2012  kbr     initial draft extension

The Tor Browser / file comparison

comparison: gfx/angle/extensions/EXT_draw_buffers.txt

gfx/angle/extensions/EXT_draw_buffers.txt