1Name 2 3 EXT_draw_buffers_indexed 4 5Name Strings 6 7 GL_EXT_draw_buffers_indexed 8 9Contact 10 11 Daniel Koch, NVIDIA Corporation (dkoch 'at' nvidia.com) 12 13Contributors 14 15 Graham Connor, Imagination 16 Ben Bowman, Imagination 17 Jonathan Putsman, Imagination 18 Contributors to EXT_draw_buffers2 19 Contributors to ARB_draw_buffers_blend 20 21Status 22 23 Complete. 24 25Version 26 27 Last Modified Date: July 14, 2014 28 Revision: 5 29 30Number 31 32 OpenGL ES Extension #176 33 34Dependencies 35 36 OpenGL ES 3.0 or EXT_draw_buffers is required. 37 38 This extension is written against the OpenGL ES 3.0 specification. 39 40Overview 41 42 This extension builds upon the EXT_draw_buffers extension. 43 In EXT_draw_buffers (part of OpenGL ES 3.0), separate values could 44 be written to each color buffer, but the blend enable, blend functions, 45 blend equations and color write masks are global and apply to all color 46 outputs. 47 48 This extension provides the ability to independently 49 * enable or disable blending, 50 * set the blend equations, 51 * set the blend functions, and 52 * set the color write masks 53 per color output. 54 55 This extension introduces indexed versions of the enable, 56 blend equation, blend function, and color mask commands, as 57 well as associated indexed queries in order to control and 58 query these states independently on a per-color output basis. 59 60New Procedures and Functions 61 62 void EnableiEXT(enum target, uint index); 63 64 void DisableiEXT(enum target, uint index); 65 66 void BlendEquationiEXT(uint buf, enum mode); 67 68 void BlendEquationSeparateiEXT(uint buf, enum modeRGB, 69 enum modeAlpha); 70 71 void BlendFunciEXT(uint buf, enum src, enum dst); 72 73 void BlendFuncSeparateiEXT(uint buf, enum srcRGB, enum dstRGB, 74 enum srcAlpha, enum dstAlpha); 75 76 void ColorMaskiEXT(uint buf, boolean r, boolean g, 77 boolean b, boolean a); 78 79 boolean IsEnablediEXT(enum target, uint index); 80 81New Tokens 82 83 Accepted by the <target> parameter of GetBooleani_v, GetIntegeri_v, and 84 GetInteger64i_v: 85 86 BLEND_EQUATION_RGB 87 BLEND_EQUATION_ALPHA 88 BLEND_SRC_RGB 89 BLEND_SRC_ALPHA 90 BLEND_DST_RGB 91 BLEND_DST_ALPHA 92 COLOR_WRITEMASK 93 94 Accepted by the <target> parameter of EnableiEXT, DisableiEXT, and 95 IsEnablediEXT: 96 97 BLEND 98 99 Accepted by the <mode> parameter of BlendEquationiEXT and by the 100 <modeRGB> and <modeAlpha> parameters of BlendEquationSeparateiEXT: 101 102 FUNC_ADD 103 FUNC_SUBTRACT 104 FUNC_REVERSE_SUBTRACT 105 MIN 106 MAX 107 108 Accepted by the <src> and <dst> parameters of BlendFunciEXT and 109 by the <srcRGB>, <dstRGB>, <srcAlpha>, and <dstAlpha> parameters 110 of BlendFuncSeparateiEXT: 111 112 ZERO 113 ONE 114 SRC_COLOR 115 ONE_MINUS_SRC_COLOR 116 DST_COLOR 117 ONE_MINUS_DST_COLOR 118 SRC_ALPHA 119 ONE_MINUS_SRC_ALPHA 120 DST_ALPHA 121 ONE_MINUS_DST_ALPHA 122 CONSTANT_COLOR 123 ONE_MINUS_CONSTANT_COLOR 124 CONSTANT_ALPHA 125 ONE_MINUS_CONSTANT_ALPHA 126 SRC_ALPHA_SATURATE 127 128 (Note all of the above tokens are already defined in OpenGL ES 3.0.) 129 130Additions to Chapter 2 of the OpenGL ES 3.0 Specification (OpenGL ES Operation) 131 132 None. 133 134Additions to Chapter 3 of the OpenGL ES 3.0 Specification (Rasterization) 135 136 None. 137 138Additions to Chapter 4 of the OpenGL ES 3.0 Specification (Per-Fragment 139Operations and the Framebuffer) 140 141 Modify the fifth paragraph of section 4.1.7 (Blending), p. 179, to 142 read as follows: 143 144 "Blending is enabled or disabled for an individual draw buffer with 145 the commands: 146 147 void EnableiEXT(enum target, uint index); 148 void DisableiEXT(enum target, uint index); 149 150 <target> is the symbolic constant BLEND and <index> is an integer 151 <i> specifying the draw buffer associated with the symbolic constant 152 DRAW_BUFFER<i>. Blending can be enabled or 153 disabled for all draw buffers using Enable or Disable with the 154 symbolic constant BLEND. If blending is disabled for a particular 155 draw buffer, proceed to the next operation." 156 157 Modify section "Blend Equation" replacing the first paragraph beginning 158 on p. 179, with the following: 159 160 "Blending is controlled by the blend equation. This equation can be 161 simultaneously set to the same value for all draw buffers using the 162 commands: 163 164 void BlendEquation(enum mode); 165 void BlendEquationSeparate(enum modeRGB, enum modeAlpha); 166 167 or for an individual draw buffer using the indexed commands: 168 169 void BlendEquationiEXT(uint buf, enum mode); 170 void BlendEquationSeparateiEXT(uint buf 171 enum modeRGB, 172 enum modeAlpha); 173 174 BlendEquationSeparate and BlendEquationSeparateiEXT argument 175 <modeRGB> determines the RGB blend equation while <modeAlpha> 176 determines the alpha blend equation. BlendEquation and 177 BlendEquationiEXT argument <mode> determines both the RGB and alpha 178 blend equations. <mode>, <modeRGB>, and <modeAlpha> must be one of 179 FUNC_ADD, FUNC_SUBTRACT, FUNC_REVERSE_SUBTRACT, MIN, MAX. 180 BlendEquation and BlendEquationSeparate modify the blend equations 181 for all draw buffers. BlendEquationiEXT and 182 BlendEquationSeparateiEXT modify the blend equations associated with 183 an individual draw buffer. The <buf> argument is an integer <i> that 184 indicates that the blend equations should be modified for 185 DRAW_BUFFER<i>." 186 187 Modify section "Blend Functions" on p. 181, replacing the last sentence 188 of the first paragraph and the second paragraph with the following: 189 190 "Blend functions are simultaneously specified 191 for all draw buffers using the commands: 192 193 void BlendFunc(enum src, enum dst); 194 void BlendFuncSeparate(enum srcRGB, enum dstRGB, 195 enum srcAlpha, enum dstAlpha); 196 197 or for an individual draw buffer using the indexed commands: 198 199 void BlendFunciEXT(uint buf, enum src, enum dst); 200 void BlendFuncSeparateiEXT(uint buf, enum srcRGB, 201 enum dstRGB, enum srcAlpha, 202 enum dstAlpha); 203 204 BlendFuncSeparate and BlendFuncSeparateiEXT arguments <srcRGB> and 205 <dstRGB> determine the source and destination RGB blend functions, 206 respectively, while <srcAlpha> and <dstAlpha> determine the source 207 and destination alpha blend functions. BlendFunc and BlendFunciEXT 208 argument <src> determines both RGB and alpha source functions, while 209 <dst> determines both RGB and alpha destination functions. 210 BlendFuncSeparate and BlendFunc modify the blend functions for all 211 draw buffers. BlendFuncSeparateiEXT and BlendFunciEXT modify the 212 blend functions associated with an individual draw buffer. The <buf> 213 argument is an integer <i> that indicates that the blend equations 214 should be modified for DRAW_BUFFER<i>." 215 216 Modify section "Blending State" on p. 183, replacing the first two 217 paragraphs with the following: 218 219 "The state required for blending, for each draw buffer, is two 220 integers for the RGB and alpha blend equations, four integers 221 indicating the source and destination RGB and alpha blending 222 functions, and a bit indicating whether blending is enabled or 223 disabled. Additionally, four floating-point values to store the RGBA 224 constant blend color are required. 225 226 For all draw buffers, the initial blend equations for RGB and alpha 227 are both FUNC_ADD, and the initial blending functions are ONE for 228 the source RGB and alpha functions, and ZERO for the destination RGB 229 and alpha functions. Initially, blending is disabled for all draw 230 buffers. The initial constant blend color is (R,G,B,A) = (0,0,0,0). 231 232 The value of the blend enable for draw buffer <i> can be queried by 233 calling IsEnablediEXT with <target> BLEND and <index> <i>, and the 234 values of the blend equations and functions can be queried by calling 235 GetIntegeri_v with the corresponding <target> as shown in 236 table 6.11 and <index> <i>. 237 238 The value of the blend enable, or the blend equations and functions 239 for draw buffer zero may also be queried by calling IsEnabled, or 240 GetInteger, respectively, with the same symbolic constants but no 241 <index> parameter." 242 243 Modify section 4.2.2 (Fine Control of Buffer Updates) replacing the 244 first two paragraphs as follows: 245 246 "Writing to bits of each of the logical framebuffers after all 247 per-fragment operations have been performed may be "masked". The 248 commands: 249 250 void ColorMask(boolean r, boolean g, boolean b, boolean a); 251 void ColorMaskiEXT(uint buf, boolean r, boolean g, 252 boolean b, boolean a); 253 254 control writes to the active draw buffers. 255 256 ColorMask and ColorMaskiEXT are used to mask 257 the writing of R, G, B and A values to the draw buffer or buffers. 258 ColorMaskiEXT sets the mask for a particular draw buffer. 259 The mask for DRAW_BUFFER<i> is modified by passing <i> as the parameter 260 <buf>. <r>, <g>, <b>, and <a> indicate whether R, G, B, or A 261 values, respectively, are written or not (a value of TRUE means 262 that the corresponding value is written). The mask specified by 263 <r>, <g>, <b>, and <a> is applied to the color buffer associated 264 with DRAW_BUFFER<i>. 265 266 ColorMask sets the mask for all draw buffers to the same values as 267 specified by <r>, <g>, <b>, and <a>. 268 269 In the initial state, all color values are enabled for writing for all 270 draw buffers. 271 272 The value of the color writemask for draw buffer <i> can be queried 273 by calling GetBooleani_v with <target> COLOR_WRITEMASK and <index> 274 <i>. The value of the color writemask for draw buffer zero may also be 275 queried by calling GetBooleanv with the symbolic constant COLOR_WRITEMASK." 276 277Additions to Chapter 5 of the OpenGL ES 3.0 Specification (Special Functions) 278 279 None. 280 281Additions to Chapter 6 of the OpenGL ES 3.0 Specification (State and 282State Requests) 283 284 Modify section 6.1.1 (Simple Queries) p. 226. 285 286 Replace the 3rd paragraph with the following: 287 288 "Finally, 289 290 boolean IsEnabled(enum cap); 291 292 can be used to determine if <cap> is currently enabled (as with 293 Enable) or disabled, and 294 295 boolean IsEnablediEXT(enum target, uint index); 296 297 can be used to determine if the index state corresponding to 298 <target> and <index> is enabled or disabled. 299 300Additions to Appendix A of the OpenGL ES 3.0 Specification (Invariance) 301 302 None. 303 304Additions to the EGL/AGL/GLX/WGL Specifications 305 306 None. 307 308Errors 309 310 The error INVALID_VALUE is generated by BlendEquationiEXT, 311 BlendEquationSeparateiEXT, BlendFuncSeparateiEXT, and 312 BlendFunciEXT if the <buf> parameter is outside the range 313 [0, MAX_DRAW_BUFFERS-1]. 314 315 The error INVALID_VALUE is generated by GetIntegeri_v 316 if <target> is BLEND_EQUATION_RGB, BLEND_EQUATION_ALPHA, BLEND_SRC_RGB, 317 BLEND_SRC_ALPHA, BLEND_DST_RGB, BLEND_DST_ALPHA, and <index> is outside 318 the range [0, MAX_DRAW_BUFFERS-1]. 319 320 The error INVALID_ENUM is generated by BlendFunciEXT 321 if either <src>, or <dst> is not an accepted value. 322 323 The error INVALID_ENUM is generated by BlendFuncSeparateiEXT 324 if either <srcRGB>, <dstRGB>, <srcAlpha>, or <dstAlpha> is not 325 an accepted value. 326 327 The error INVALID_ENUM is generated if the <mode> parameter of 328 BlendEquationiEXT is not one of FUNC_ADD, FUNC_SUBTRACT, 329 FUNC_REVERSE_SUBTRACT, MAX, or MIN. 330 331 The error INVALID_ENUM is generated if either the <modeRGB> or 332 <modeAlpha> parameter of BlendEquationSeparateiEXT is not one of 333 FUNC_ADD, FUNC_SUBTRACT, FUNC_REVERSE_SUBTRACT, MAX, or MIN. 334 335 The error INVALID_ENUM is generated by EnableiEXT and 336 DisableiEXT if the <target> parameter is not BLEND. 337 338 The error INVALID_VALUE is generated by EnableiEXT and 339 DisableiEXT if the <target> parameter is BLEND and the <index> 340 parameter is outside the range [0, MAX_DRAW_BUFFERS-1]. 341 342 The error INVALID_ENUM is generated by IsEnablediEXT if the 343 <target> parameter is not BLEND. 344 345 The error INVALID_VALUE is generated by IsEnablediEXT if 346 the <target> parameter is BLEND and the <index> parameter is 347 outside the range [0, MAX_DRAW_BUFFERS-1]. 348 349 The error INVALID_VALUE is generated by ColorMaskiEXT 350 if the <buf> parameter is outside the range[0, MAX_DRAW_BUFFERS-1]. 351 352 The error INVALID_VALUE is generated by GetBooleani_v if the <target> 353 parameter is COLOR_WRITEMASK and the <index> parameter is outside the 354 range [0, MAX_DRAW_BUFFERS-1]. 355 356New State 357 358 Modify Table 6.11 (Pixel Operations) p. 254, modifying the entries for 359 BLEND enable, the blend functions and blend equations, adding indexed 360 versions: 361 362 Initial 363 Get Value Type Get Command Value Description Section 364 -------------------- --------- ------------- -------- ------------------------------------ ------- 365 BLEND B IsEnablediEXT False Blending enabled for draw buffer <i> 4.1.7 366 where <i> is specified as <index> 367 BLEND_SRC_RGB 4* x Z_19 GetIntegeri_v ONE Blending source RGB 4.1.7 368 function for draw buffer <i> 369 where <i> is specified as <index> 370 BLEND_SRC_ALPHA 4* x Z_19 GetIntegeri_v ONE Blending source A 4.1.7 371 function for draw buffer <i> 372 where <i> is specified as <index> 373 BLEND_DST_RGB 4* x Z_19 GetIntegeri_v ZERO Blending destination RGB 4.1.7 374 function for draw buffer <i> 375 where <i> is specified as <index> 376 BLEND_DST_ALPHA 4* x Z_19 GetIntegeri_v ZERO Blending destination A 4.1.7 377 function for draw buffer <i> 378 where <i> is specified as <index> 379 BLEND_EQUATION_RGB 4* x Z_5 GetIntegeri_v FUNC_ADD RGB blending equation 4.1.7 380 for draw buffer <i> 381 where <i> is specified as <index> 382 BLEND_EQUATION_ALPHA 4* x Z_5 GetIntegeri_v FUNC_ADD Alpha blending equation 4.1.7 383 for draw buffer <i> 384 where <i> is specified as <index> 385 386 Modify Table 6.12 (Framebuffer Control) p. 255, modifying the entry for 387 COLOR_WRITEMASK: 388 389 Get Value Type Get Command Value Description Section 390 --------------- -------- ------------- ------ ---------------------------------- ------- 391 COLOR_WRITEMASK 4* x 4xB GetBooleani_v 4xTrue Color write enables (R, G, B, A) 4.2.2 392 for draw buffer <i> 393 where <i> is specified as <index> 394 395Issues 396 397 Note: these issues apply specifically to the definition of 398 EXT_draw_buffers_indexed, which is based on the OpenGL EXT_draw_buffers2 399 and ARB_draw_buffers_blend extensions as updated in OpenGL 4.x. 400 Resolved issues from EXT_draw_buffers2 and ARB_draw_buffers_blend have 401 been removed but remain largely applicable to this extension. These 402 extensions can be found in the OpenGL Registry. 403 404 (1) What functionality was removed from EXT_draw_buffers2 and 405 ARB_draw_buffers_blend? 406 407 - removed mention of multiple buffers being associated with DRAW_BUFFER<i> 408 - removed mention of logical operation on color values 409 - removed mention of the IndexMask command 410 - removed errors related to glBegin/End 411 412 (2) What functionality was changed or added relative to EXT_draw_buffers2 413 and ARB_draw_buffers_blend? 414 415 - use EnableiEXT/DisableiEXT instead of Enable/DisableIndexedEXT 416 - use ColorMaskiEXT instead of ColorMaskIndexedEXT 417 - use IsEnablediEXT instead of IsEnabledIndexedEXT 418 - GetIntegeri_v is already in ES 3.0 and is re-used instead of adding 419 GetIntegerIndexedvEXT. 420 - GetBooleani_v is already in ES 3.1 and is re-used instead of adding 421 GetBooleanIndexedvEXT 422 - change the errors to be consistent and match GL 4.4. 423 424 (3) What should we call this extension? 425 426 RESOLVED: EXT_draw_buffers_indexed, because it adds the indexed "i" 427 variants of all the draw buffer related state setting commands. 428 Other options considered include: 429 * EXT_draw_buffers2, EXT_draw_buffers_blend: both potentially confusing due 430 to similarly named GL extensions, while this incorporates the functionality 431 of both. Furthermore, this will likely be an EXT extension and there already 432 is an EXT_draw_buffers2 in the GL registry. Using the same name and having 433 different functionality is strongly discouraged. 434 * EXT_draw_buffers_separate: because it allows separate control of the drawing 435 buffers. Potentially could be confused with the "blend_func_separate" and 436 "blend_equation_separate" extensions, which allow separately controlling a 437 of the RGB and A equations and functions. 438 * EXT_draw_buffers_independent: because it allows the functionality of the 439 separate drawing buffers to be independently controlled. 440 441 (4) Why doesn't this extension include GetBooleani_vEXT? 442 443 RESOLVED: GetBooleani_v was added in OpenGL ES 3.1 per Bug 11326 and thus 444 no longer needs to be added by this extension. This extension does 445 however extend the commands accepted by this core function. 446 447 (5) What is the correct error for all the commands which take a <buf> 448 or <index> parameter which should be in the range [0, MAX_DRAW_BUFFERS-1]? 449 450 RESOLVED: INVALID_VALUE is the correct error. 451 EXT_draw_buffers2 specified INVALID_OPERATION for the EnableIndexedEXT, 452 DisableIndexedEXT, IsEnabledIndexedEXT, and GetBooleanIndexedvEXT commands. 453 ARB_draw_buffers_blend specified INVALID_ENUM for the 454 Blend{Equation Func}[Separate]iARB commands. 455 OpenGL 4.4 specifies INVALID_VALUE for the core versions of all these 456 commands. This was clarified by Bug 7705, but never propagated back to 457 the ARB_draw_buffers_blend extension. Since we are basing the 458 functionality on the core versions of these commands we will use the 459 GL 4.x error values. 460 461 (6) What is the correct error for the Blend{Equation Func}[Separate]iEXT 462 commands if mode/modeRGB/modeAlpha/srcRGB/srcAlpha/dstRGB/dstAlpha is 463 not a legal value? 464 465 RESOLVED. INVALID_ENUM. Some versions of the GL 4.4 spec said it should be 466 INVALID_VALUE, but it seems that the more correct error value should 467 INVALID_ENUM since all of these values are specified as 'enum' in the 468 function signatures. This was clarified in Bug 11354. 469 470 471Revision History 472 473 Rev. Date Author Changes 474 ---- -------- -------- ----------------------------------------- 475 5 07/14/14 dkoch Remove stray tokens from error (bug 12358) 476 4 03/26/14 dkoch Update contributors. 477 3 03/10/14 Jon Leech Change NNN suffix to EXT. 478 2 12/16/13 dkoch Removed GetBooleani_vEXT. 479 Resolved Issues 4 and 6. 480 Expanded out New Tokens section to clarify the 481 tokens accepted by the new functions. 482 1 12/02/13 dkoch Initial revision based on EXT_draw_buffers2 v10 483 and ARB_draw_buffers_blend v4 and updated with 484 GL 4.4 commands and language. 485