1Name 2 3 EXT_draw_buffers2 4 5Name Strings 6 7 GL_EXT_draw_buffers2 8 9Contact 10 11 Mike Strauss, NVIDIA Corporation (mstrauss 'at' nvidia.com) 12 13Status 14 15 Multi vendor extension 16 17 Shipping for GeForce 8 Series (November 2006) 18 19Version 20 21 Last Modified Date: 10/02/2010 22 NVIDIA Revision: 11 23 24Number 25 26 340 27 28Dependencies 29 30 The extension is written against the OpenGL 2.0 Specification. 31 32 OpenGL 2.0 is required. 33 34Overview 35 36 This extension builds upon the ARB_draw_buffers extension and provides 37 separate blend enables and color write masks for each color output. In 38 ARB_draw_buffers (part of OpenGL 2.0), separate values can be written to 39 each color buffer, but the blend enable and color write mask are global 40 and apply to all color outputs. 41 42 While this extension does provide separate blend enables, it does not 43 provide separate blend functions or blend equations per color output. 44 45 46New Procedures and Functions 47 48 void ColorMaskIndexedEXT(uint buf, boolean r, boolean g, 49 boolean b, boolean a); 50 51 void GetBooleanIndexedvEXT(enum value, uint index, boolean *data); 52 53 void GetIntegerIndexedvEXT(enum value, uint index, int *data); 54 55 void EnableIndexedEXT(enum target, uint index); 56 57 void DisableIndexedEXT(enum target, uint index); 58 59 boolean IsEnabledIndexedEXT(enum target, uint index); 60 61New Tokens 62 63 None. 64 65Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL Operation) 66 67 None. 68 69Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization) 70 71 None. 72 73Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment 74Operations and the Frame Buffer) 75 76 Modify the thrid paragraph of section 4.1.8 (Blending), p206, to 77 read as follows: 78 79 Blending is dependent on the incoming fragment's alpha value and 80 that of the corresponding currently stored pixel. Blending applies 81 only in RGBA mode; in color index mode it is bypassed. Blending 82 is enabled or disabled for an individual draw buffer using 83 84 void EnableIndexedEXT(GLenum target, GLuint index); 85 void DisableIndexedEXT(GLenum target, GLuint index); 86 87 <target> is the symbolic constant BLEND and <index> is an integer 88 i specifying the draw buffer associated with the symbolic constant 89 DRAW_BUFFERi. If the color buffer associated with DRAW_BUFFERi is 90 one of FRONT, BACK, LEFT, RIGHT, or FRONT_AND_BACK (specifying 91 multiple color buffers), then the state enabled or disabled is 92 applicable for all of the buffers. Blending can be enabled or 93 disabled for all draw buffers using Enable or Disable with the 94 symbolic constant BLEND. If blending is disabled for a particular 95 draw buffer, or if logical operation on color values is enabled 96 (section 4.1.10), proceed to the next operation. 97 98 99 Modify the first paragraph of section 4.1.8 (Blending - Blending 100 State), p209, to read as follows: 101 102 The state required for blending is two integers for the RGB and 103 alpha blend equations, four integers indicating the source and 104 destination RGB and alpha blending functions, four floating-point 105 values to store the RGBA constant blend color, and n bits 106 indicating whether blending is enabled or disabled for each of the 107 n draw buffers. The initial blend equations for RGB and alpha are 108 both FUNC_ADD. The initial blending functions are ONE for the 109 source RGB and alpha functions, and ZERO for the destination RGB 110 and alpha functions. The initial constant blend color is 111 (R, G, B, A) = (0, 0, 0, 0). Initially, blending is disabled for 112 all draw buffers. 113 114 115 Modify the first paragraph of section 4.2.2 (Fine Control of Buffer 116 Updates) to read as followS: 117 118 Three commands are used to mask the writing of bits to each of the 119 logical draw buffers after all per-fragment operations have been 120 performed. 121 122 The commands 123 124 void IndexMask(uint mask); 125 void ColorMask(boolean r, boolean g, boolean b, boolean a); 126 void ColorMaskIndexedEXT(uint buf, boolean r, boolean g, 127 boolean b, boolean a); 128 129 control writes to the active draw buffers. 130 131 The least significant n bits of <mask>, where n is the number of 132 bits in a color index buffer, specify a mask. Where a 1 appears in 133 this mask, the corresponding bit in the color index buffer (or 134 buffers) is written; where a 0 appears, the bit is not written. 135 This mask applies only in color index mode. 136 137 In RGBA mode, ColorMask and ColorMaskIndexedEXT are used to mask 138 the writing of R, G, B and A values to the draw buffer or buffers. 139 ColorMaskIndexedEXT sets the mask for a particular draw buffer. 140 The mask for DRAW_BUFFERi is modified by passing i as the parameter 141 <buf>. <r>, <g>, <b>, and <a> indicate whether R, G, B, or A 142 values, respectively, are written or not (a value of TRUE means 143 that the corresponding value is written). The mask specified by 144 <r>, <g>, <b>, and <a> is applied to the color buffer associated 145 with DRAW_BUFFERi. If DRAW_BUFFERi is one of FRONT, BACK, LEFT, 146 RIGHT, or FRONT_AND_BACK (specifying multiple color buffers) then 147 the mask is applied to all of the buffers. ColorMask sets the mask 148 for all draw buffers to the same values as specified by <r>, <g>, 149 <b>, and <a>. 150 151Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions) 152 153 None. 154 155Additions to Chapter 6 of the OpenGL 2.0 Specification (State and 156State Requests) 157 158 Modify the second paragraph of section 6.1.1 (Simple Queries) 159 p244 to read as follows: 160 161 ...<data> is a pointer to a scalar or array of the indicated 162 type in which to place the returned data. 163 164 void GetBooleanIndexedvEXT(enum target, uint index, boolean *data); 165 void GetIntegerIndexedvEXT(enum target, uint index, int *data); 166 167 are used to query indexed state. <target> is the name of 168 the indexed state and <index> is the index of the particular 169 element being queried. <data> is a pointer to a scalar or array 170 of the indicated type in which to place the returned data. In 171 addition 172 173 boolean IsEnabled(enum value); 174 175 can be used to determine if <value> is currently enabled (as with 176 Enable) or disabled. 177 178 boolean IsEnabledIndexedEXT(enum target, uint index); 179 180 can be used to determine if the index state corresponding to 181 <target> and <index> is enabled or disabled. 182 183Additions to Appendix A of the OpenGL 2.0 Specification (Invariance) 184 185 None. 186 187Additions to the AGL/GLX/WGL Specifications 188 189 None. 190 191GLX Protocol 192 193 The following rendering commands are sent to the server as part of 194 a glXRender request: 195 196 ColorMaskIndexedEXT 197 198 2 12 rendering command length 199 2 352 rendering command opcode 200 4 CARD32 buf 201 1 BOOL r 202 1 BOOL g 203 1 BOOL b 204 1 BOOL a 205 206 EnableIndexedEXT 207 208 2 12 rendering length 209 2 353 rendering command opcode 210 4 ENUM target 211 4 CARD32 index 212 213 DisableIndexedEXT 214 215 2 12 rendering length 216 2 354 rendering command opcode 217 4 ENUM target 218 4 CARD32 index 219 220 The following new non-rendering commands are added: 221 222 GetBooleanIndexedvEXT 223 224 1 CARD8 opcode(X assigned) 225 1 210 GLX opcode 226 2 4 request length 227 4 GLX_CONTEXT_TAG context tag 228 4 ENUM value 229 4 CARD32 index 230 => 231 1 reply 232 1 unused 233 2 CARD16 sequence number 234 4 m reply length, m = (n == 1 ? 0 :(n+p)/4) 235 4 unused 236 4 CARD32 n (number of parameter components) 237 238 if (n == 1) this follows: 239 240 1 BOOL data 241 15 unused 242 243 otherwise this follows: 244 245 16 unused 246 n*1 LISTofBOOL data 247 p unused, p = pad(n) 248 249 GetIntegerIndexedvEXT 250 251 1 CARD8 opcode(X assigned) 252 1 211 GLX opcode 253 2 4 request length 254 4 GLX_CONTEXT_TAG context tag 255 4 ENUM value 256 4 CARD32 index 257 => 258 1 reply 259 1 unused 260 2 CARD16 sequence number 261 4 m reply length, m = (n == 1 ? 0 : n) 262 4 unused 263 4 CARD32 n (number of parameter components) 264 265 if (n == 1) this follows: 266 267 4 CARD32 data 268 12 unused 269 270 otherwise this follows: 271 272 16 unused 273 4*n LISTofCARD32 data 274 275 IsEnabledIndexedEXT 276 277 1 CARD8 opcode(X assigned) 278 1 212 GLX opcode 279 2 4 request length 280 4 GLX_CONTEXT_TAG context tag 281 4 ENUM target 282 4 CARD32 index 283 => 284 1 reply 285 1 unused 286 2 CARD16 sequence number 287 4 0 reply length 288 4 BOOL32 return value 289 20 unused 290 291Errors 292 293 The error INVALID_ENUM is generated by EnableIndexedEXT and 294 DisableIndexedEXT if the <target> parameter is not BLEND. 295 296 The error INVALID_OPERATION is generated by EnableIndexedEXT and 297 DisableIndexeEXT if the <target> parameter is BLEND and the <index> 298 parameter is outside the range [0, MAX_DRAW_BUFFERS-1]. 299 300 The error INVALID_ENUM is generated by IsEnabledIndexedEXT if the 301 <target> parameter is not BLEND. 302 303 The error INVALID_OPERATION is generated by IsEnabledIndexedEXT if 304 the <target> parameter is BLEND and the <index> parameter is 305 outside the range [0, MAX_DRAW_BUFFERS-1]. 306 307 The error INVALID_OPERATION is generated by DrawBufferColorMaskEXT 308 if the <buf> parameter is outside the range 309 [0, MAX_DRAW_BUFFERS-1]. 310 311 The error INVALID_ENUM is generated by GetBooleanIndexedvEXT if the 312 <target> parameter is not BLEND. 313 314 The error INVALID_OPERATION is generated by GetBooleanIndexedvEXT 315 if the <target> parameter is BLEND and the <index> parameter is 316 outside the range [0, MAX_DRAW_BUFFERS-1]. 317 318New State 319 320 Modify (table 6.20, p281), modifying the entry for BLEND and adding 321 a new one. 322 323 324 Get Target Type Get Command Value Description Section Attribute 325 ---------- ---- ------------------- ----- ---------------------------------- ------- ------------------- 326 BLEND B IsEnabled False Blending enabled for draw buffer 0 4.1.8 color-buffer/enable 327 BLEND B IsEnabledIndexedEXT False Blending enabled for draw buffer i 4.1.8 color-buffer/enable 328 where i is specified as <index> 329 330 331 Modify (table 6.21, p282), modifying the entry for COLOR_WRITEMASK 332 and adding a new one. 333 334 Get Value Type Get Command Value Description Section Attribute 335 --------------- ---- --------------------- ----- ---------------------------------- ------- ------------ 336 COLOR_WRITEMASK 4xB GetBooleanv True Color write mask for draw buffer 0 4.2.2 color-buffer 337 COLOR_WRITEMASK 4xB GetBooleanIndexedvEXT True Color write mask for draw buffer i 4.2.2 color-buffer 338 where i is specified as <index> 339 340Issues 341 342 1. Should the extension provide support for per draw buffer index 343 masks as well as per draw buffer color masks? 344 345 RESOLVED: No. Color index rendering is not interesting 346 enough to warrant extending the API in this direction. 347 348 2. Should the API for specifying separate color write masks be 349 based on DrawBuffers() (specifying an array of write masks at 350 once)? 351 352 RESOLVED: No. There are two ways to mimic the DrawBuffers() 353 API. A function, ColorMasks(), could take an an element count 354 and an array of four element boolean arrays as parameters. 355 Each four element boolean array contains a set of red, green, 356 blue, and alpha write masks for a specific color buffer. An 357 alternative is a ColorMasks() function that takes an element 358 count and four parallel boolean arrays with one array per color 359 channel. Neither approach is particularly clean. A cleaner 360 approach, taken by ColorMaskIndexedEXT(), is to specify a 361 color mask for a single draw buffer where the draw buffer is 362 specified as a parameter to the function. 363 364 3. How should ColorMask() affect the per color buffer write masks? 365 366 RESOLVED: ColorMask() should set all color buffer write masks 367 to the same values. This is backwards compatible with the way 368 ColorMask() behaves in the absence of this extension. 369 370 4. What should GetBooleanv return when COLOR_WRITEMASK is queried? 371 372 RESOLVED: COLOR_WRITEMASK should return 373 DRAW_BUFFER0_COLOR_WRITEMASK_EXT. This is backwards compatible 374 with the way the query works without this extension. To query 375 the writemask associated with a particular draw buffer, an 376 application can use GetBooleanIndexedvEXT. 377 378 5. How are separate blend enables controlled? Should a new 379 function be introduced, or do Enable() and Disable() provide 380 sufficient functionality? 381 382 RESOLVED: This extension introduces new functions 383 EnableIndexedEXT and DisableIndexedEXT that can be used to 384 enable/disable individual states of a state array. These 385 functions are introduced because there is a trend towards 386 introducing arrays of state. Rather than creating enums for 387 each index in the array, it is better to give applications 388 a mechanism for accessing a particular element of the state 389 array given the name of the state and an index into the array. 390 391 6. What effect does enabling or disabling blending using BLEND 392 have on per draw buffer blend enables? 393 394 RESOLVED: BLEND, used with Enable() and Disable(), should 395 enable or disable all per draw buffer blend enables. This is 396 similar to the way that ColorMask() affects the per draw 397 buffer write masks. 398 399 7. What does DRAW_BUFFERi mean in the context of functions like 400 ColorMaskIndexedEXT? 401 402 PROPOSED: When DrawBuffersARB is called with a list of buffers 403 to be used for MRT rendering, DRAW_BUFFERi implies an index into 404 the list of buffers. That is, DRAW_BUFFER0 refers to the zeroeth 405 buffer in the array passed to DrawBuffersARB (or any of the other 406 ways to specify multiple render targets). MAX_DRAW_BUFFERS is 407 also to be understood in this context to mean the number of currently 408 active draw buffers. 409 410Revision History 411 412 Rev. Date Author Changes 413 ---- -------- -------- ----------------------------------------- 414 11 10/02/10 srahman Added GLX protocol. 415 416 10 07/11/08 joburgess Added a clarification of ColorMaskIndexedEXT / DrawBuffersARB interaction. 417 418 9 02/09/07 pbrown Updated status section (now released). 419 420 8 10/23/06 pbrown Fixed typo in the prototype for 421 GetIntegerIndexedvEXT -- <data> should be an 422 integer pointer. Moved issues to the end. 423 424 7 10/21/06 barthold Added revision history 425 426 1-6 mstrauss Internal spec development. 427 428