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