blob: 404bc875c20ea35f3a065b000fede3bba8f35209 [file] [log] [blame]
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.