| Name |
| |
| OES_draw_buffers_indexed |
| |
| Name Strings |
| |
| GL_OES_draw_buffers_indexed |
| |
| Contact |
| |
| Daniel Koch, NVIDIA Corporation (dkoch 'at' nvidia.com) |
| |
| Contributors |
| |
| Graham Connor, Imagination |
| Ben Bowman, Imagination |
| Jonathan Putsman, Imagination |
| Contributors to EXT_draw_buffers2 |
| Contributors to ARB_draw_buffers_blend |
| |
| Notice |
| |
| Copyright (c) 2014 The Khronos Group Inc. Copyright terms at |
| http://www.khronos.org/registry/speccopyright.html |
| |
| Specification Update Policy |
| |
| Khronos-approved extension specifications are updated in response to |
| issues and bugs prioritized by the Khronos OpenGL ES Working Group. For |
| extensions which have been promoted to a core Specification, fixes will |
| first appear in the latest version of that core Specification, and will |
| eventually be backported to the extension document. This policy is |
| described in more detail at |
| https://www.khronos.org/registry/OpenGL/docs/update_policy.php |
| |
| Status |
| |
| Approved by the OpenGL ES Working Group |
| Ratified by the Khronos Board of Promoters on November 7, 2014 |
| |
| Version |
| |
| Last Modified Date: July 14, 2014 |
| Revision: 2 |
| |
| Number |
| |
| OpenGL ES Extension #209 |
| |
| Dependencies |
| |
| OpenGL ES 3.0 or EXT_draw_buffers is required. |
| |
| This extension is written against the OpenGL ES 3.0 specification. |
| |
| Overview |
| |
| This extension builds upon the EXT_draw_buffers extension. |
| In EXT_draw_buffers (part of OpenGL ES 3.0), separate values could |
| be written to each color buffer, but the blend enable, blend functions, |
| blend equations and color write masks are global and apply to all color |
| outputs. |
| |
| This extension provides the ability to independently |
| * enable or disable blending, |
| * set the blend equations, |
| * set the blend functions, and |
| * set the color write masks |
| per color output. |
| |
| This extension introduces indexed versions of the enable, |
| blend equation, blend function, and color mask commands, as |
| well as associated indexed queries in order to control and |
| query these states independently on a per-color output basis. |
| |
| New Procedures and Functions |
| |
| void EnableiOES(enum target, uint index); |
| |
| void DisableiOES(enum target, uint index); |
| |
| void BlendEquationiOES(uint buf, enum mode); |
| |
| void BlendEquationSeparateiOES(uint buf, enum modeRGB, |
| enum modeAlpha); |
| |
| void BlendFunciOES(uint buf, enum src, enum dst); |
| |
| void BlendFuncSeparateiOES(uint buf, enum srcRGB, enum dstRGB, |
| enum srcAlpha, enum dstAlpha); |
| |
| void ColorMaskiOES(uint buf, boolean r, boolean g, |
| boolean b, boolean a); |
| |
| boolean IsEnablediOES(enum target, uint index); |
| |
| New Tokens |
| |
| Accepted by the <target> parameter of GetBooleani_v, GetIntegeri_v, and |
| GetInteger64i_v: |
| |
| BLEND_EQUATION_RGB |
| BLEND_EQUATION_ALPHA |
| BLEND_SRC_RGB |
| BLEND_SRC_ALPHA |
| BLEND_DST_RGB |
| BLEND_DST_ALPHA |
| COLOR_WRITEMASK |
| |
| Accepted by the <target> parameter of EnableiOES, DisableiOES, and |
| IsEnablediOES: |
| |
| BLEND |
| |
| Accepted by the <mode> parameter of BlendEquationiOES and by the |
| <modeRGB> and <modeAlpha> parameters of BlendEquationSeparateiOES: |
| |
| FUNC_ADD |
| FUNC_SUBTRACT |
| FUNC_REVERSE_SUBTRACT |
| MIN |
| MAX |
| |
| Accepted by the <src> and <dst> parameters of BlendFunciOES and |
| by the <srcRGB>, <dstRGB>, <srcAlpha>, and <dstAlpha> parameters |
| of BlendFuncSeparateiOES: |
| |
| ZERO |
| ONE |
| SRC_COLOR |
| ONE_MINUS_SRC_COLOR |
| DST_COLOR |
| ONE_MINUS_DST_COLOR |
| SRC_ALPHA |
| ONE_MINUS_SRC_ALPHA |
| DST_ALPHA |
| ONE_MINUS_DST_ALPHA |
| CONSTANT_COLOR |
| ONE_MINUS_CONSTANT_COLOR |
| CONSTANT_ALPHA |
| ONE_MINUS_CONSTANT_ALPHA |
| SRC_ALPHA_SATURATE |
| |
| (Note all of the above tokens are already defined in OpenGL ES 3.0.) |
| |
| Additions to Chapter 2 of the OpenGL ES 3.0 Specification (OpenGL ES Operation) |
| |
| None. |
| |
| Additions to Chapter 3 of the OpenGL ES 3.0 Specification (Rasterization) |
| |
| None. |
| |
| Additions to Chapter 4 of the OpenGL ES 3.0 Specification (Per-Fragment |
| Operations and the Framebuffer) |
| |
| Modify the fifth paragraph of section 4.1.7 (Blending), p. 179, to |
| read as follows: |
| |
| "Blending is enabled or disabled for an individual draw buffer with |
| the commands: |
| |
| void EnableiOES(enum target, uint index); |
| void DisableiOES(enum target, uint index); |
| |
| <target> is the symbolic constant BLEND and <index> is an integer |
| <i> specifying the draw buffer associated with the symbolic constant |
| DRAW_BUFFER<i>. Blending can be enabled or |
| disabled for all draw buffers using Enable or Disable with the |
| symbolic constant BLEND. If blending is disabled for a particular |
| draw buffer, proceed to the next operation." |
| |
| Modify section "Blend Equation" replacing the first paragraph beginning |
| on p. 179, with the following: |
| |
| "Blending is controlled by the blend equation. This equation can be |
| simultaneously set to the same value for all draw buffers using the |
| commands: |
| |
| void BlendEquation(enum mode); |
| void BlendEquationSeparate(enum modeRGB, enum modeAlpha); |
| |
| or for an individual draw buffer using the indexed commands: |
| |
| void BlendEquationiOES(uint buf, enum mode); |
| void BlendEquationSeparateiOES(uint buf |
| enum modeRGB, |
| enum modeAlpha); |
| |
| BlendEquationSeparate and BlendEquationSeparateiOES argument |
| <modeRGB> determines the RGB blend equation while <modeAlpha> |
| determines the alpha blend equation. BlendEquation and |
| BlendEquationiOES argument <mode> determines both the RGB and alpha |
| blend equations. <mode>, <modeRGB>, and <modeAlpha> must be one of |
| FUNC_ADD, FUNC_SUBTRACT, FUNC_REVERSE_SUBTRACT, MIN, MAX. |
| BlendEquation and BlendEquationSeparate modify the blend equations |
| for all draw buffers. BlendEquationiOES and |
| BlendEquationSeparateiOES modify the blend equations associated with |
| an individual draw buffer. The <buf> argument is an integer <i> that |
| indicates that the blend equations should be modified for |
| DRAW_BUFFER<i>." |
| |
| Modify section "Blend Functions" on p. 181, replacing the last sentence |
| of the first paragraph and the second paragraph with the following: |
| |
| "Blend functions are simultaneously specified |
| for all draw buffers using the commands: |
| |
| void BlendFunc(enum src, enum dst); |
| void BlendFuncSeparate(enum srcRGB, enum dstRGB, |
| enum srcAlpha, enum dstAlpha); |
| |
| or for an individual draw buffer using the indexed commands: |
| |
| void BlendFunciOES(uint buf, enum src, enum dst); |
| void BlendFuncSeparateiOES(uint buf, enum srcRGB, |
| enum dstRGB, enum srcAlpha, |
| enum dstAlpha); |
| |
| BlendFuncSeparate and BlendFuncSeparateiOES arguments <srcRGB> and |
| <dstRGB> determine the source and destination RGB blend functions, |
| respectively, while <srcAlpha> and <dstAlpha> determine the source |
| and destination alpha blend functions. BlendFunc and BlendFunciOES |
| argument <src> determines both RGB and alpha source functions, while |
| <dst> determines both RGB and alpha destination functions. |
| BlendFuncSeparate and BlendFunc modify the blend functions for all |
| draw buffers. BlendFuncSeparateiOES and BlendFunciOES modify the |
| blend functions associated with an individual draw buffer. The <buf> |
| argument is an integer <i> that indicates that the blend equations |
| should be modified for DRAW_BUFFER<i>." |
| |
| Modify section "Blending State" on p. 183, replacing the first two |
| paragraphs with the following: |
| |
| "The state required for blending, for each draw buffer, is two |
| integers for the RGB and alpha blend equations, four integers |
| indicating the source and destination RGB and alpha blending |
| functions, and a bit indicating whether blending is enabled or |
| disabled. Additionally, four floating-point values to store the RGBA |
| constant blend color are required. |
| |
| For all draw buffers, the initial blend equations for RGB and alpha |
| are both FUNC_ADD, and the initial blending functions are ONE for |
| the source RGB and alpha functions, and ZERO for the destination RGB |
| and alpha functions. Initially, blending is disabled for all draw |
| buffers. The initial constant blend color is (R,G,B,A) = (0,0,0,0). |
| |
| The value of the blend enable for draw buffer <i> can be queried by |
| calling IsEnablediOES with <target> BLEND and <index> <i>, and the |
| values of the blend equations and functions can be queried by calling |
| GetIntegeri_v with the corresponding <target> as shown in |
| table 6.11 and <index> <i>. |
| |
| The value of the blend enable, or the blend equations and functions |
| for draw buffer zero may also be queried by calling IsEnabled, or |
| GetInteger, respectively, with the same symbolic constants but no |
| <index> parameter." |
| |
| Modify section 4.2.2 (Fine Control of Buffer Updates) replacing the |
| first two paragraphs as follows: |
| |
| "Writing to bits of each of the logical framebuffers after all |
| per-fragment operations have been performed may be "masked". The |
| commands: |
| |
| void ColorMask(boolean r, boolean g, boolean b, boolean a); |
| void ColorMaskiOES(uint buf, boolean r, boolean g, |
| boolean b, boolean a); |
| |
| control writes to the active draw buffers. |
| |
| ColorMask and ColorMaskiOES are used to mask |
| the writing of R, G, B and A values to the draw buffer or buffers. |
| ColorMaskiOES sets the mask for a particular draw buffer. |
| The mask for DRAW_BUFFER<i> is modified by passing <i> as the parameter |
| <buf>. <r>, <g>, <b>, and <a> indicate whether R, G, B, or A |
| values, respectively, are written or not (a value of TRUE means |
| that the corresponding value is written). The mask specified by |
| <r>, <g>, <b>, and <a> is applied to the color buffer associated |
| with DRAW_BUFFER<i>. |
| |
| ColorMask sets the mask for all draw buffers to the same values as |
| specified by <r>, <g>, <b>, and <a>. |
| |
| In the initial state, all color values are enabled for writing for all |
| draw buffers. |
| |
| The value of the color writemask for draw buffer <i> can be queried |
| by calling GetBooleani_v with <target> COLOR_WRITEMASK and <index> |
| <i>. The value of the color writemask for draw buffer zero may also be |
| queried by calling GetBooleanv with the symbolic constant COLOR_WRITEMASK." |
| |
| Additions to Chapter 5 of the OpenGL ES 3.0 Specification (Special Functions) |
| |
| None. |
| |
| Additions to Chapter 6 of the OpenGL ES 3.0 Specification (State and |
| State Requests) |
| |
| Modify section 6.1.1 (Simple Queries) p. 226. |
| |
| Replace the 3rd paragraph with the following: |
| |
| "Finally, |
| |
| boolean IsEnabled(enum cap); |
| |
| can be used to determine if <cap> is currently enabled (as with |
| Enable) or disabled, and |
| |
| boolean IsEnablediOES(enum target, uint index); |
| |
| can be used to determine if the index state corresponding to |
| <target> and <index> is enabled or disabled. |
| |
| Additions to Appendix A of the OpenGL ES 3.0 Specification (Invariance) |
| |
| None. |
| |
| Additions to the EGL/AGL/GLX/WGL Specifications |
| |
| None. |
| |
| Errors |
| |
| The error INVALID_VALUE is generated by BlendEquationiOES, |
| BlendEquationSeparateiOES, BlendFuncSeparateiOES, and |
| BlendFunciOES if the <buf> parameter is outside the range |
| [0, MAX_DRAW_BUFFERS-1]. |
| |
| The error INVALID_VALUE is generated by GetIntegeri_v |
| if <target> is BLEND_EQUATION_RGB, BLEND_EQUATION_ALPHA, BLEND_SRC_RGB, |
| BLEND_SRC_ALPHA, BLEND_DST_RGB, BLEND_DST_ALPHA, and <index> is outside |
| the range [0, MAX_DRAW_BUFFERS-1]. |
| |
| The error INVALID_ENUM is generated by BlendFunciOES |
| if either <src>, or <dst> is not an accepted value. |
| |
| The error INVALID_ENUM is generated by BlendFuncSeparateiOES |
| if either <srcRGB>, <dstRGB>, <srcAlpha>, or <dstAlpha> is not |
| an accepted value. |
| |
| The error INVALID_ENUM is generated if the <mode> parameter of |
| BlendEquationiOES is not one of FUNC_ADD, FUNC_SUBTRACT, |
| FUNC_REVERSE_SUBTRACT, MAX, or MIN. |
| |
| The error INVALID_ENUM is generated if either the <modeRGB> or |
| <modeAlpha> parameter of BlendEquationSeparateiOES is not one of |
| FUNC_ADD, FUNC_SUBTRACT, FUNC_REVERSE_SUBTRACT, MAX, or MIN. |
| |
| The error INVALID_ENUM is generated by EnableiOES and |
| DisableiOES if the <target> parameter is not BLEND. |
| |
| The error INVALID_VALUE is generated by EnableiOES and |
| DisableiOES if the <target> parameter is BLEND and the <index> |
| parameter is outside the range [0, MAX_DRAW_BUFFERS-1]. |
| |
| The error INVALID_ENUM is generated by IsEnablediOES if the |
| <target> parameter is not BLEND. |
| |
| The error INVALID_VALUE is generated by IsEnablediOES if |
| the <target> parameter is BLEND and the <index> parameter is |
| outside the range [0, MAX_DRAW_BUFFERS-1]. |
| |
| The error INVALID_VALUE is generated by ColorMaskiOES |
| if the <buf> parameter is outside the range[0, MAX_DRAW_BUFFERS-1]. |
| |
| The error INVALID_VALUE is generated by GetBooleani_v if the <target> |
| parameter is COLOR_WRITEMASK and the <index> parameter is outside the |
| range [0, MAX_DRAW_BUFFERS-1]. |
| |
| New State |
| |
| Modify Table 6.11 (Pixel Operations) p. 254, modifying the entries for |
| BLEND enable, the blend functions and blend equations, adding indexed |
| versions: |
| |
| Initial |
| Get Value Type Get Command Value Description Section |
| -------------------- --------- ------------- -------- ------------------------------------ ------- |
| BLEND B IsEnablediOES False Blending enabled for draw buffer <i> 4.1.7 |
| where <i> is specified as <index> |
| BLEND_SRC_RGB 4* x Z_19 GetIntegeri_v ONE Blending source RGB 4.1.7 |
| function for draw buffer <i> |
| where <i> is specified as <index> |
| BLEND_SRC_ALPHA 4* x Z_19 GetIntegeri_v ONE Blending source A 4.1.7 |
| function for draw buffer <i> |
| where <i> is specified as <index> |
| BLEND_DST_RGB 4* x Z_19 GetIntegeri_v ZERO Blending destination RGB 4.1.7 |
| function for draw buffer <i> |
| where <i> is specified as <index> |
| BLEND_DST_ALPHA 4* x Z_19 GetIntegeri_v ZERO Blending destination A 4.1.7 |
| function for draw buffer <i> |
| where <i> is specified as <index> |
| BLEND_EQUATION_RGB 4* x Z_5 GetIntegeri_v FUNC_ADD RGB blending equation 4.1.7 |
| for draw buffer <i> |
| where <i> is specified as <index> |
| BLEND_EQUATION_ALPHA 4* x Z_5 GetIntegeri_v FUNC_ADD Alpha blending equation 4.1.7 |
| for draw buffer <i> |
| where <i> is specified as <index> |
| |
| Modify Table 6.12 (Framebuffer Control) p. 255, modifying the entry for |
| COLOR_WRITEMASK: |
| |
| Get Value Type Get Command Value Description Section |
| --------------- -------- ------------- ------ ---------------------------------- ------- |
| COLOR_WRITEMASK 4* x 4xB GetBooleani_v 4xTrue Color write enables (R, G, B, A) 4.2.2 |
| for draw buffer <i> |
| where <i> is specified as <index> |
| |
| Issues |
| |
| Note: these issues apply specifically to the definition of |
| OES_draw_buffers_indexed, which is based on the OpenGL EXT_draw_buffers2 |
| and ARB_draw_buffers_blend extensions as updated in OpenGL 4.x. |
| Resolved issues from EXT_draw_buffers2 and ARB_draw_buffers_blend have |
| been removed but remain largely applicable to this extension. These |
| extensions can be found in the OpenGL Registry. |
| |
| (1) What functionality was removed from EXT_draw_buffers2 and |
| ARB_draw_buffers_blend? |
| |
| - removed mention of multiple buffers being associated with DRAW_BUFFER<i> |
| - removed mention of logical operation on color values |
| - removed mention of the IndexMask command |
| - removed errors related to glBegin/End |
| |
| (2) What functionality was changed or added relative to EXT_draw_buffers2 |
| and ARB_draw_buffers_blend? |
| |
| - use EnableiOES/DisableiOES instead of Enable/DisableIndexedEXT |
| - use ColorMaskiOES instead of ColorMaskIndexedEXT |
| - use IsEnablediOES instead of IsEnabledIndexedEXT |
| - GetIntegeri_v is already in ES 3.0 and is re-used instead of adding |
| GetIntegerIndexedvEXT. |
| - GetBooleani_v is already in ES 3.1 and is re-used instead of adding |
| GetBooleanIndexedvEXT |
| - change the errors to be consistent and match GL 4.4. |
| |
| (3) Issue removed. Not applicable to this extension. |
| |
| (4) Why doesn't this extension include GetBooleani_vOES? |
| |
| RESOLVED: GetBooleani_v was added in OpenGL ES 3.1 per Bug 11326 and thus |
| no longer needs to be added by this extension. This extension does |
| however extend the commands accepted by this core function. |
| |
| (5) What is the correct error for all the commands which take a <buf> |
| or <index> parameter which should be in the range [0, MAX_DRAW_BUFFERS-1]? |
| |
| RESOLVED: INVALID_VALUE is the correct error. |
| EXT_draw_buffers2 specified INVALID_OPERATION for the EnableIndexedEXT, |
| DisableIndexedEXT, IsEnabledIndexedEXT, and GetBooleanIndexedvEXT commands. |
| ARB_draw_buffers_blend specified INVALID_ENUM for the |
| Blend{Equation Func}[Separate]iARB commands. |
| OpenGL 4.4 specifies INVALID_VALUE for the core versions of all these |
| commands. This was clarified by Bug 7705, but never propagated back to |
| the ARB_draw_buffers_blend extension. Since we are basing the |
| functionality on the core versions of these commands we will use the |
| GL 4.x error values. |
| |
| (6) What is the correct error for the Blend{Equation Func}[Separate]iOES |
| commands if mode/modeRGB/modeAlpha/srcRGB/srcAlpha/dstRGB/dstAlpha is |
| not a legal value? |
| |
| RESOLVED. INVALID_ENUM. Some versions of the GL 4.4 spec said it should be |
| INVALID_VALUE, but it seems that the more correct error value should |
| INVALID_ENUM since all of these values are specified as 'enum' in the |
| function signatures. This was clarified in Bug 11354. |
| |
| |
| Revision History |
| |
| Rev. Date Author Changes |
| ---- ---------- -------- ----------------------------------------- |
| 2 07/14/2014 dkoch Remove stray tokens from error (bug 12358) |
| 1 06/18/2014 dkoch Initial OES version based on EXT. |
| No functional changes. |
