| Name |
| |
| EXT_draw_buffers2 |
| |
| Name Strings |
| |
| GL_EXT_draw_buffers2 |
| |
| Contact |
| |
| Mike Strauss, NVIDIA Corporation (mstrauss 'at' nvidia.com) |
| |
| Status |
| |
| Multi vendor extension |
| |
| Shipping for GeForce 8 Series (November 2006) |
| |
| Version |
| |
| Last Modified Date: 10/02/2010 |
| NVIDIA Revision: 11 |
| |
| Number |
| |
| 340 |
| |
| Dependencies |
| |
| The extension is written against the OpenGL 2.0 Specification. |
| |
| OpenGL 2.0 is required. |
| |
| Overview |
| |
| This extension builds upon the ARB_draw_buffers extension and provides |
| separate blend enables and color write masks for each color output. In |
| ARB_draw_buffers (part of OpenGL 2.0), separate values can be written to |
| each color buffer, but the blend enable and color write mask are global |
| and apply to all color outputs. |
| |
| While this extension does provide separate blend enables, it does not |
| provide separate blend functions or blend equations per color output. |
| |
| |
| New Procedures and Functions |
| |
| void ColorMaskIndexedEXT(uint buf, boolean r, boolean g, |
| boolean b, boolean a); |
| |
| void GetBooleanIndexedvEXT(enum value, uint index, boolean *data); |
| |
| void GetIntegerIndexedvEXT(enum value, uint index, int *data); |
| |
| void EnableIndexedEXT(enum target, uint index); |
| |
| void DisableIndexedEXT(enum target, uint index); |
| |
| boolean IsEnabledIndexedEXT(enum target, uint index); |
| |
| New Tokens |
| |
| None. |
| |
| Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL Operation) |
| |
| None. |
| |
| Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization) |
| |
| None. |
| |
| Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment |
| Operations and the Frame Buffer) |
| |
| Modify the thrid paragraph of section 4.1.8 (Blending), p206, to |
| read as follows: |
| |
| Blending is dependent on the incoming fragment's alpha value and |
| that of the corresponding currently stored pixel. Blending applies |
| only in RGBA mode; in color index mode it is bypassed. Blending |
| is enabled or disabled for an individual draw buffer using |
| |
| void EnableIndexedEXT(GLenum target, GLuint index); |
| void DisableIndexedEXT(GLenum target, GLuint index); |
| |
| <target> is the symbolic constant BLEND and <index> is an integer |
| i specifying the draw buffer associated with the symbolic constant |
| DRAW_BUFFERi. If the color buffer associated with DRAW_BUFFERi is |
| one of FRONT, BACK, LEFT, RIGHT, or FRONT_AND_BACK (specifying |
| multiple color buffers), then the state enabled or disabled is |
| applicable for all of the buffers. 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, or if logical operation on color values is enabled |
| (section 4.1.10), proceed to the next operation. |
| |
| |
| Modify the first paragraph of section 4.1.8 (Blending - Blending |
| State), p209, to read as follows: |
| |
| The state required for blending is two integers for the RGB and |
| alpha blend equations, four integers indicating the source and |
| destination RGB and alpha blending functions, four floating-point |
| values to store the RGBA constant blend color, and n bits |
| indicating whether blending is enabled or disabled for each of the |
| n draw buffers. The initial blend equations for RGB and alpha are |
| both FUNC_ADD. The initial blending functions are ONE for the |
| source RGB and alpha functions, and ZERO for the destination RGB |
| and alpha functions. The initial constant blend color is |
| (R, G, B, A) = (0, 0, 0, 0). Initially, blending is disabled for |
| all draw buffers. |
| |
| |
| Modify the first paragraph of section 4.2.2 (Fine Control of Buffer |
| Updates) to read as followS: |
| |
| Three commands are used to mask the writing of bits to each of the |
| logical draw buffers after all per-fragment operations have been |
| performed. |
| |
| The commands |
| |
| void IndexMask(uint mask); |
| void ColorMask(boolean r, boolean g, boolean b, boolean a); |
| void ColorMaskIndexedEXT(uint buf, boolean r, boolean g, |
| boolean b, boolean a); |
| |
| control writes to the active draw buffers. |
| |
| The least significant n bits of <mask>, where n is the number of |
| bits in a color index buffer, specify a mask. Where a 1 appears in |
| this mask, the corresponding bit in the color index buffer (or |
| buffers) is written; where a 0 appears, the bit is not written. |
| This mask applies only in color index mode. |
| |
| In RGBA mode, ColorMask and ColorMaskIndexedEXT are used to mask |
| the writing of R, G, B and A values to the draw buffer or buffers. |
| ColorMaskIndexedEXT sets the mask for a particular draw buffer. |
| The mask for DRAW_BUFFERi 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_BUFFERi. If DRAW_BUFFERi is one of FRONT, BACK, LEFT, |
| RIGHT, or FRONT_AND_BACK (specifying multiple color buffers) then |
| the mask is applied to all of the buffers. ColorMask sets the mask |
| for all draw buffers to the same values as specified by <r>, <g>, |
| <b>, and <a>. |
| |
| Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions) |
| |
| None. |
| |
| Additions to Chapter 6 of the OpenGL 2.0 Specification (State and |
| State Requests) |
| |
| Modify the second paragraph of section 6.1.1 (Simple Queries) |
| p244 to read as follows: |
| |
| ...<data> is a pointer to a scalar or array of the indicated |
| type in which to place the returned data. |
| |
| void GetBooleanIndexedvEXT(enum target, uint index, boolean *data); |
| void GetIntegerIndexedvEXT(enum target, uint index, int *data); |
| |
| are used to query indexed state. <target> is the name of |
| the indexed state and <index> is the index of the particular |
| element being queried. <data> is a pointer to a scalar or array |
| of the indicated type in which to place the returned data. In |
| addition |
| |
| boolean IsEnabled(enum value); |
| |
| can be used to determine if <value> is currently enabled (as with |
| Enable) or disabled. |
| |
| boolean IsEnabledIndexedEXT(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 2.0 Specification (Invariance) |
| |
| None. |
| |
| Additions to the AGL/GLX/WGL Specifications |
| |
| None. |
| |
| GLX Protocol |
| |
| The following rendering commands are sent to the server as part of |
| a glXRender request: |
| |
| ColorMaskIndexedEXT |
| |
| 2 12 rendering command length |
| 2 352 rendering command opcode |
| 4 CARD32 buf |
| 1 BOOL r |
| 1 BOOL g |
| 1 BOOL b |
| 1 BOOL a |
| |
| EnableIndexedEXT |
| |
| 2 12 rendering length |
| 2 353 rendering command opcode |
| 4 ENUM target |
| 4 CARD32 index |
| |
| DisableIndexedEXT |
| |
| 2 12 rendering length |
| 2 354 rendering command opcode |
| 4 ENUM target |
| 4 CARD32 index |
| |
| The following new non-rendering commands are added: |
| |
| GetBooleanIndexedvEXT |
| |
| 1 CARD8 opcode(X assigned) |
| 1 210 GLX opcode |
| 2 4 request length |
| 4 GLX_CONTEXT_TAG context tag |
| 4 ENUM value |
| 4 CARD32 index |
| => |
| 1 reply |
| 1 unused |
| 2 CARD16 sequence number |
| 4 m reply length, m = (n == 1 ? 0 :(n+p)/4) |
| 4 unused |
| 4 CARD32 n (number of parameter components) |
| |
| if (n == 1) this follows: |
| |
| 1 BOOL data |
| 15 unused |
| |
| otherwise this follows: |
| |
| 16 unused |
| n*1 LISTofBOOL data |
| p unused, p = pad(n) |
| |
| GetIntegerIndexedvEXT |
| |
| 1 CARD8 opcode(X assigned) |
| 1 211 GLX opcode |
| 2 4 request length |
| 4 GLX_CONTEXT_TAG context tag |
| 4 ENUM value |
| 4 CARD32 index |
| => |
| 1 reply |
| 1 unused |
| 2 CARD16 sequence number |
| 4 m reply length, m = (n == 1 ? 0 : n) |
| 4 unused |
| 4 CARD32 n (number of parameter components) |
| |
| if (n == 1) this follows: |
| |
| 4 CARD32 data |
| 12 unused |
| |
| otherwise this follows: |
| |
| 16 unused |
| 4*n LISTofCARD32 data |
| |
| IsEnabledIndexedEXT |
| |
| 1 CARD8 opcode(X assigned) |
| 1 212 GLX opcode |
| 2 4 request length |
| 4 GLX_CONTEXT_TAG context tag |
| 4 ENUM target |
| 4 CARD32 index |
| => |
| 1 reply |
| 1 unused |
| 2 CARD16 sequence number |
| 4 0 reply length |
| 4 BOOL32 return value |
| 20 unused |
| |
| Errors |
| |
| The error INVALID_ENUM is generated by EnableIndexedEXT and |
| DisableIndexedEXT if the <target> parameter is not BLEND. |
| |
| The error INVALID_OPERATION is generated by EnableIndexedEXT and |
| DisableIndexeEXT 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 IsEnabledIndexedEXT if the |
| <target> parameter is not BLEND. |
| |
| The error INVALID_OPERATION is generated by IsEnabledIndexedEXT if |
| the <target> parameter is BLEND and the <index> parameter is |
| outside the range [0, MAX_DRAW_BUFFERS-1]. |
| |
| The error INVALID_OPERATION is generated by DrawBufferColorMaskEXT |
| if the <buf> parameter is outside the range |
| [0, MAX_DRAW_BUFFERS-1]. |
| |
| The error INVALID_ENUM is generated by GetBooleanIndexedvEXT if the |
| <target> parameter is not BLEND. |
| |
| The error INVALID_OPERATION is generated by GetBooleanIndexedvEXT |
| if the <target> parameter is BLEND and the <index> parameter is |
| outside the range [0, MAX_DRAW_BUFFERS-1]. |
| |
| New State |
| |
| Modify (table 6.20, p281), modifying the entry for BLEND and adding |
| a new one. |
| |
| |
| Get Target Type Get Command Value Description Section Attribute |
| ---------- ---- ------------------- ----- ---------------------------------- ------- ------------------- |
| BLEND B IsEnabled False Blending enabled for draw buffer 0 4.1.8 color-buffer/enable |
| BLEND B IsEnabledIndexedEXT False Blending enabled for draw buffer i 4.1.8 color-buffer/enable |
| where i is specified as <index> |
| |
| |
| Modify (table 6.21, p282), modifying the entry for COLOR_WRITEMASK |
| and adding a new one. |
| |
| Get Value Type Get Command Value Description Section Attribute |
| --------------- ---- --------------------- ----- ---------------------------------- ------- ------------ |
| COLOR_WRITEMASK 4xB GetBooleanv True Color write mask for draw buffer 0 4.2.2 color-buffer |
| COLOR_WRITEMASK 4xB GetBooleanIndexedvEXT True Color write mask for draw buffer i 4.2.2 color-buffer |
| where i is specified as <index> |
| |
| Issues |
| |
| 1. Should the extension provide support for per draw buffer index |
| masks as well as per draw buffer color masks? |
| |
| RESOLVED: No. Color index rendering is not interesting |
| enough to warrant extending the API in this direction. |
| |
| 2. Should the API for specifying separate color write masks be |
| based on DrawBuffers() (specifying an array of write masks at |
| once)? |
| |
| RESOLVED: No. There are two ways to mimic the DrawBuffers() |
| API. A function, ColorMasks(), could take an an element count |
| and an array of four element boolean arrays as parameters. |
| Each four element boolean array contains a set of red, green, |
| blue, and alpha write masks for a specific color buffer. An |
| alternative is a ColorMasks() function that takes an element |
| count and four parallel boolean arrays with one array per color |
| channel. Neither approach is particularly clean. A cleaner |
| approach, taken by ColorMaskIndexedEXT(), is to specify a |
| color mask for a single draw buffer where the draw buffer is |
| specified as a parameter to the function. |
| |
| 3. How should ColorMask() affect the per color buffer write masks? |
| |
| RESOLVED: ColorMask() should set all color buffer write masks |
| to the same values. This is backwards compatible with the way |
| ColorMask() behaves in the absence of this extension. |
| |
| 4. What should GetBooleanv return when COLOR_WRITEMASK is queried? |
| |
| RESOLVED: COLOR_WRITEMASK should return |
| DRAW_BUFFER0_COLOR_WRITEMASK_EXT. This is backwards compatible |
| with the way the query works without this extension. To query |
| the writemask associated with a particular draw buffer, an |
| application can use GetBooleanIndexedvEXT. |
| |
| 5. How are separate blend enables controlled? Should a new |
| function be introduced, or do Enable() and Disable() provide |
| sufficient functionality? |
| |
| RESOLVED: This extension introduces new functions |
| EnableIndexedEXT and DisableIndexedEXT that can be used to |
| enable/disable individual states of a state array. These |
| functions are introduced because there is a trend towards |
| introducing arrays of state. Rather than creating enums for |
| each index in the array, it is better to give applications |
| a mechanism for accessing a particular element of the state |
| array given the name of the state and an index into the array. |
| |
| 6. What effect does enabling or disabling blending using BLEND |
| have on per draw buffer blend enables? |
| |
| RESOLVED: BLEND, used with Enable() and Disable(), should |
| enable or disable all per draw buffer blend enables. This is |
| similar to the way that ColorMask() affects the per draw |
| buffer write masks. |
| |
| 7. What does DRAW_BUFFERi mean in the context of functions like |
| ColorMaskIndexedEXT? |
| |
| PROPOSED: When DrawBuffersARB is called with a list of buffers |
| to be used for MRT rendering, DRAW_BUFFERi implies an index into |
| the list of buffers. That is, DRAW_BUFFER0 refers to the zeroeth |
| buffer in the array passed to DrawBuffersARB (or any of the other |
| ways to specify multiple render targets). MAX_DRAW_BUFFERS is |
| also to be understood in this context to mean the number of currently |
| active draw buffers. |
| |
| Revision History |
| |
| Rev. Date Author Changes |
| ---- -------- -------- ----------------------------------------- |
| 11 10/02/10 srahman Added GLX protocol. |
| |
| 10 07/11/08 joburgess Added a clarification of ColorMaskIndexedEXT / DrawBuffersARB interaction. |
| |
| 9 02/09/07 pbrown Updated status section (now released). |
| |
| 8 10/23/06 pbrown Fixed typo in the prototype for |
| GetIntegerIndexedvEXT -- <data> should be an |
| integer pointer. Moved issues to the end. |
| |
| 7 10/21/06 barthold Added revision history |
| |
| 1-6 mstrauss Internal spec development. |
| |