WebGL WEBGL_draw_buffers Khronos Ratified Extension Specification

Name

WEBGL_draw_buffers

Contact

WebGL working group (public_webgl 'at' khronos.org)

Contributors

Members of the WebGL working group

Version

Last modified date: July 23, 2016
Revision: 11

Number

WebGL extension #18

Dependencies

Written against the WebGL API 1.0 specification.

Promoted to core and no longer available as an extension in WebGL API 2.0 specification. Requires GLSL #version 300 es.

Overview

This extension exposes the EXT_draw_buffers functionality to WebGL.

The following WebGL-specific behavioral changes apply:

• The implementation must support a minimum of 4 color attachments.
• The value of the MAX_COLOR_ATTACHMENTS_WEBGL parameter must be greater than or equal to that of the MAX_DRAW_BUFFERS_WEBGL parameter.
• If:
  • A framebuffer's color attachments are all textures allocated with format RGBA and type UNSIGNED_BYTE, and
  • The framebuffer has either:
    • No depth or stencil attachment
    • A valid DEPTH or DEPTH_STENCIL attachment
  Then a call to checkFramebufferStatus against this framebuffer must not return FRAMEBUFFER_UNSUPPORTED. (In other words, the implementation must support the use of RGBA/UNSIGNED_BYTE textures as color attachments, plus either a DEPTH or DEPTH_STENCIL attachment.)
• Attaching n consecutive color attachments starting at COLOR_ATTACHMENT0_WEBGL, where n is between 1 and MAX_DRAW_BUFFERS_WEBGL, must not return FRAMEBUFFER_UNSUPPORTED from a call to checkFramebufferStatus. In other words, if MAX_DRAW_BUFFERS_WEBGL is 4, then the implementation is required to support the following combinations of color attachments:
  • COLOR_ATTACHMENT0_WEBGL = RGBA/UNSIGNED_BYTE
  • COLOR_ATTACHMENT0_WEBGL = RGBA/UNSIGNED_BYTE
COLOR_ATTACHMENT1_WEBGL = RGBA/UNSIGNED_BYTE
    
  • COLOR_ATTACHMENT0_WEBGL = RGBA/UNSIGNED_BYTE
COLOR_ATTACHMENT1_WEBGL = RGBA/UNSIGNED_BYTE
COLOR_ATTACHMENT2_WEBGL = RGBA/UNSIGNED_BYTE
    
  • COLOR_ATTACHMENT0_WEBGL = RGBA/UNSIGNED_BYTE
COLOR_ATTACHMENT1_WEBGL = RGBA/UNSIGNED_BYTE
COLOR_ATTACHMENT2_WEBGL = RGBA/UNSIGNED_BYTE
COLOR_ATTACHMENT3_WEBGL = RGBA/UNSIGNED_BYTE
    
• Although the extension name is prefixed with WEBGL the extension must be enabled with the #extension GL_EXT_draw_buffers directive, as shown in the sample code, to use the extension in a shader. Likewise the shading language preprocessor #define GL_EXT_draw_buffers, will be defined to 1 if the extension is supported.
• The value of gl_MaxDrawBuffers must match MAX_DRAW_BUFFERS_WEBGL from the API if the extension is enabled in a WebGL context; otherwise, the value must be 1. Whether or not the extension is enabled with the #extension GL_EXT_draw_buffers directive in a shader does not affect the value of gl_MaxDrawBuffers. The value of gl_MaxDrawBuffers is a constant in the shader, and is guaranteed to be frozen at program link time. It is implementation-dependent whether it is frozen at shader compile time. (A consequence is that if a program is linked, and later the WEBGL_draw_buffers extension is enabled, the value of gl_MaxDrawBuffers seen by that program will still be 1.)
• If the WEBGL_draw_buffers extension is enabled, but the fragment shader does not contain the #extension GL_EXT_draw_buffers directive to enable it, then writes to gl_FragColor are only written to COLOR_ATTACHMENT0_WEBGL, and not broadcast to all color attachments. In this scenario, if there are draw buffers other than COLOR_ATTACHMENT0, because there is only a fragment shader output for DRAW_BUFFER0, draw commands generate INVALID_OPERATION, unless all 4 channels of colorMask are set to false.
• If a fragment shader writes to neither gl_FragColor nor gl_FragData, the values of the fragment colors following shader execution are untouched. If a fragment shader contains the #extension GL_EXT_draw_buffers directive, all gl_FragData variables (from gl_FragData[0] to gl_FragData[MAX_DRAW_BUFFERS_WEBGL - 1]) default to zero if no values are written to them during a shader execution.
• If an image is attached to more than one color attachment point in a framebuffer, checkFramebufferStatus returns FRAMEBUFFER_UNSUPPORTED. An image can be an individual mip level, or a face of cube map.

Consult the above extension for documentation, issues and new functions and enumerants.

When this extension is enabled:

• Adds support for multiple color buffers and color outputs from fragment shaders.

IDL

[Exposed=(Window,Worker), LegacyNoInterfaceObject]
interface WEBGL_draw_buffers {
    const GLenum COLOR_ATTACHMENT0_WEBGL     = 0x8CE0;
    const GLenum COLOR_ATTACHMENT1_WEBGL     = 0x8CE1;
    const GLenum COLOR_ATTACHMENT2_WEBGL     = 0x8CE2;
    const GLenum COLOR_ATTACHMENT3_WEBGL     = 0x8CE3;
    const GLenum COLOR_ATTACHMENT4_WEBGL     = 0x8CE4;
    const GLenum COLOR_ATTACHMENT5_WEBGL     = 0x8CE5;
    const GLenum COLOR_ATTACHMENT6_WEBGL     = 0x8CE6;
    const GLenum COLOR_ATTACHMENT7_WEBGL     = 0x8CE7;
    const GLenum COLOR_ATTACHMENT8_WEBGL     = 0x8CE8;
    const GLenum COLOR_ATTACHMENT9_WEBGL     = 0x8CE9;
    const GLenum COLOR_ATTACHMENT10_WEBGL    = 0x8CEA;
    const GLenum COLOR_ATTACHMENT11_WEBGL    = 0x8CEB;
    const GLenum COLOR_ATTACHMENT12_WEBGL    = 0x8CEC;
    const GLenum COLOR_ATTACHMENT13_WEBGL    = 0x8CED;
    const GLenum COLOR_ATTACHMENT14_WEBGL    = 0x8CEE;
    const GLenum COLOR_ATTACHMENT15_WEBGL    = 0x8CEF;

    const GLenum DRAW_BUFFER0_WEBGL          = 0x8825;
    const GLenum DRAW_BUFFER1_WEBGL          = 0x8826;
    const GLenum DRAW_BUFFER2_WEBGL          = 0x8827;
    const GLenum DRAW_BUFFER3_WEBGL          = 0x8828;
    const GLenum DRAW_BUFFER4_WEBGL          = 0x8829;
    const GLenum DRAW_BUFFER5_WEBGL          = 0x882A;
    const GLenum DRAW_BUFFER6_WEBGL          = 0x882B;
    const GLenum DRAW_BUFFER7_WEBGL          = 0x882C;
    const GLenum DRAW_BUFFER8_WEBGL          = 0x882D;
    const GLenum DRAW_BUFFER9_WEBGL          = 0x882E;
    const GLenum DRAW_BUFFER10_WEBGL         = 0x882F;
    const GLenum DRAW_BUFFER11_WEBGL         = 0x8830;
    const GLenum DRAW_BUFFER12_WEBGL         = 0x8831;
    const GLenum DRAW_BUFFER13_WEBGL         = 0x8832;
    const GLenum DRAW_BUFFER14_WEBGL         = 0x8833;
    const GLenum DRAW_BUFFER15_WEBGL         = 0x8834;

    const GLenum MAX_COLOR_ATTACHMENTS_WEBGL = 0x8CDF;
    const GLenum MAX_DRAW_BUFFERS_WEBGL      = 0x8824;

    undefined drawBuffersWEBGL(sequence<GLenum> buffers);
};
  

Sample Code

    #extension GL_EXT_draw_buffers : require
    precision mediump float;
    void main() {
        gl_FragData[0] = vec4(1.0, 0.0, 0.0, 1.0);
        gl_FragData[1] = vec4(0.0, 1.0, 0.0, 1.0);
        gl_FragData[2] = vec4(0.0, 0.0, 1.0, 1.0);
        gl_FragData[3] = vec4(1.0, 1.0, 1.0, 1.0);
    }
    

Revision History

Revision 1, 2012/10/16

• Initial revision.

Revision 2, 2012/11/05

• Corrected typo in drawBuffersWEBGL. Changed referenced spec version to 1.0 to fix broken link.

Revision 3, 2013/02/02

• Renamed to EXT_draw_buffers per plan of OpenGL ES working group. Moved to draft status. Assigned number.

Revision 4, 2013/03/05

• Renamed to WEBGL_draw_buffers per discussion on public_webgl list. Added guarantees to make it easier for developers to use the extension.

Revision 5, 2013/06/07

• Clarified naming of shader directives.

Revision 6, 2014/07/15

• Added NoInterfaceObject extended attribute.

Revision 7, 2014/08/08

• Ratified by Khronos Board of Promoters.

Revision 8, 2016/06/28

• Revised behavior of gl_MaxDrawBuffers and gl_FragColor broadcasting, to avoid significant performance impact for WebGL 1.0 implementations running on top of the desktop OpenGL API.

Revision 9, 2016/07/08

• Removed undefined behaviors.

Revision 10, 2016/07/11

• Revised user-defined variable behavior to default to zero.

Revision 11, 2016/07/23

• Revised behavior of the same image is attached to more than one color attachment point.