1Name 2 3 ARB_blend_func_extended 4 5Name Strings 6 7 GL_ARB_blend_func_extended 8 9Contributors 10 11 Graham Sellers, AMD 12 Mark Young, AMD 13 Nick Haemel, AMD 14 Pierre Boudier, AMD 15 Mais Alnasser, AMD 16 Jeff Bolz, NVIDIA 17 Pat Brown, NVIDIA 18 Ian Stewart, NVIDIA 19 Mark Kilgard, NVIDIA 20 21Contact 22 23 Graham Sellers, AMD (graham.sellers 'at' amd.com) 24 25Notice 26 27 Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at 28 http://www.khronos.org/registry/speccopyright.html 29 30Specification Update Policy 31 32 Khronos-approved extension specifications are updated in response to 33 issues and bugs prioritized by the Khronos OpenGL Working Group. For 34 extensions which have been promoted to a core Specification, fixes will 35 first appear in the latest version of that core Specification, and will 36 eventually be backported to the extension document. This policy is 37 described in more detail at 38 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 39 40Status 41 42 Complete. Approved by the ARB at the 2010/01/22 F2F meeting. 43 Approved by the Khronos Board of Promoters on March 10, 2010. 44 45Version 46 47 Last Modified Date: 05/22/2015 48 Author Revision: 13 49 50Number 51 52 ARB Extension #78 53 54Dependencies 55 56 OpenGL 1.0 is required. 57 58 The ARB_fragment_shader extension is required. 59 60 The EXT_gpu_shader4 extension is required. 61 62 The EXT_blend_func_separate extension interacts with this extension. 63 64 The ARB_draw_buffers extension trivially affects the definition of this 65 extension. 66 67 The ARB_draw_buffers_blend extension affects the definition of this 68 extension. 69 70 This extension is written against the OpenGL 3.2 Specification (Compatibility Profile) 71 72Overview 73 74 Traditional OpenGL includes fixed-function blending that combines source 75 colors with the existing content of a render buffer in a variety of ways. 76 A number of extensions have enhanced this functionality by adding further 77 sources of blending weights and methods to combine them. However, the inputs 78 to the fixed-function blending units are constrained to a source color (as 79 output from fragment shading), destination color (as the current content 80 of the frame buffer) or constants that may be used in their place. 81 82 This extension adds new blending functions whereby a fragment shader may 83 output two colors, one of which is treated as the source color, and the 84 other used as a blending factor for either source or destination colors. 85 Furthermore, this extension increases orthogonality by allowing the 86 SRC_ALPHA_SATURATE function to be used as the destination weight. 87 88IP Status 89 90 No known IP claims. 91 92New Procedures and Functions 93 94 void BindFragDataLocationIndexed(uint program, uint colorNumber, 95 uint index, const char * name); 96 97 int GetFragDataIndex(uint program, const char * name); 98 99New Tokens 100 101 Accepted by the <src> and <dst> parameters of BlendFunc and 102 BlendFunci, and by the <srcRGB>, <dstRGB>, <srcAlpha> and <dstAlpha> 103 parameters of BlendFuncSeparate and BlendFuncSeparatei: 104 105 SRC1_COLOR 0x88F9 106 SRC1_ALPHA 107 ONE_MINUS_SRC1_COLOR 0x88FA 108 ONE_MINUS_SRC1_ALPHA 0x88FB 109 110 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv 111 and GetDoublev: 112 113 MAX_DUAL_SOURCE_DRAW_BUFFERS 0x88FC 114 115Additions to Chapter 2 of the OpenGL 3.2 Specification (Compatibility Profile) (OpenGL Operation) 116 117 None. 118 119Additions to Chapter 3 of the OpenGL 3.2 Specification (Compatibility Profile) (Rasterization) 120 121 Modify the "Shader Outputs" subsection of Section 3.12.2, Shader Execution 122 123 Modify the text on p.297 beginning "The binding of a user-defined varying 124 out variable to a fragment..." 125 126 The binding of a user-defined varying out variable to a fragment color number 127 can be specified explicitly. The command 128 129 void BindFragDataLocationIndexed(uint program, uint colorNumber, uint index, const char * name); 130 131 specifies that the varying out variable name in <program> should be bound to 132 fragment color <colorNumber> when the program is next linked. <index> may be 133 zero or one to specify that the color be used as either the first or second 134 color input to the blend equation, respectively, as described in Section 4.1.8. 135 136 If <name> was bound previously, its assigned binding is replaced with 137 colorNumber. <name> must be a null-terminated string. The error INVALID_VALUE 138 is generated if <colorNumber> is equal or greater than MAX_DRAW_BUFFERS and 139 <index> is zero, or if <colorNumber> is equal or greater than 140 MAX_DUAL_SOURCE_DRAW_BUFFERS and <index> is greater than or equal to one. 141 The command 142 143 void BindFragDataLocation(uint program, uint colorNumber, const char * name) 144 145 is equivalent to calling BindFragDataLocationIndexed with the same values 146 for <program>, <colorNumber> and <name>, and with <index> set to zero. 147 148 When a program is linked, any varying out variables without a binding 149 specified through BindFragDataLocationIndexed or BindFragDataLocation will 150 automatically be bound to fragment colors and indices by the GL. All such 151 assignments will use color indices of zero. Such bindings can be queried 152 using the commands GetFragDataLocation and GetFragDataIndex. Output 153 binding assignments will cause LinkProgram to fail: 154 155 * if the number of active outputs is greater than the value of 156 MAX_DRAW_BUFFERS; 157 158 * if the program has an active output assigned to a location greater 159 than or equal to the value of MAX_DUAL_SOURCE_DRAW_BUFFERS and has an 160 active output assigned an index greater than or equal to one; 161 162 * if more than one varying out variable is bound to the same number and 163 index; or 164 165 * if the explicit binding assignments do not leave enough space for the 166 linker to automatically assign a location for a varying out array, 167 which requires multiple contiguous locations. 168 169 BindFragDataLocationIndexed may be issued before any shader objects are 170 attached to a program object. Hence it is allowed to bind any name (except a 171 name starting with gl_) to a color number and index, including a name that 172 is never used as a varying out variable in any fragment shader object. 173 Assigned bindings for variables that do not exist are ignored. 174 175 Add to the last paragraph on p.279 176 177 The command 178 179 int GetFragDataIndex(uint program, const char * name); 180 181 returns the index of the fragment color to which the variable <name> was bound 182 when the program object <program> was last linked. If program has not been 183 successfully linked, the error INVALID_OPERATION is generated. If name is not 184 a varying out variable, or if an error occurs, -1 will be returned. 185 186Additions to Chapter 4 of the OpenGL 3.2 Specification (Compatibility Profile) (Per-Fragment Operations 187and the Framebuffer) 188 189 Modify the first paragraph of the Blending Functions subsection of Section 190 4.1.8 Blending (p. 292) as follows: 191 192 The weighting factors used by the blend equation are determined by the blend 193 functions. There are four possible sources for weighting factors. These are 194 the constant color (Rc, Gc, Bc, Ac) (see BlendColor, p. 211), the first 195 source color (Rs0, Gs0, Bs0, As0), the second source color 196 (Rs1, Gs1, Bs1, As1), and the destination color (the existing content of the 197 draw buffer). Additionally the special constants ZERO and ONE are 198 available as weighting factors. Blend functions are specified ... 199 200 Modify Table 4.2 (p. 213) as follows 201 202 RGB Blend Factors Alpha Blend Factors 203 Value (Sr, Sg, Sb) or (Dr, Dg, Db) Sa or Da 204 ----- ---------------------------- ------------------- 205 ZERO (0, 0, 0) 0 206 ONE (1, 1, 1) 1 207 SRC_COLOR (Rs0, Gs0, Bs0) As0 208 ONE_MINUS_SRC_COLOR (1, 1, 1) - (Rs0, Gs0, Bs0) 1 - As0 209 DST_COLOR (Rd, Gd, Bd) Ad 210 ONE_MINUS_DST_COLOR (1, 1, 1) - (Rd, Gd, Bd) 1 - Ad 211 SRC_ALPHA (As0, As0, As0) As0 212 ONE_MINUS_SRC_ALPHA (1, 1, 1) - (As0, As0, As0) 1 - As0 213 DST_ALPHA (Ad, Ad, Ad) Ad 214 ONE_MINUS_DST_ALPHA (1, 1, 1) - (Ad, Ad, Ad) 1 - Ad 215 CONSTANT_COLOR (Rc, Gc, Bc) Ac 216 ONE_MINUS_CONSTANT_COLOR (1, 1, 1) - (Rc, Gc, Bc) 1 - Ac 217 CONSTANT_ALPHA (Ac, Ac, Ac) Ac 218 ONE_MINUS_CONSTANT_ALPHA (1, 1, 1) - (Ac, Ac, Ac) 1 - Ac 219 SRC_ALPHA_SATURATE (f, f, f) 1 (Now allowed for dst) 220 SRC1_COLOR (Rs1, Gs1, Bs1) As1 New 221 ONE_MINUS_SRC1_COLOR (1, 1, 1) - (Rs1, Gs1, Bs1) 1 - As1 New 222 SRC1_ALPHA (As1, As1, As1) As1 New 223 ONE_MINUS_SRC1_ALPHA (1, 1, 1) - (As1, As1, As1) 1 - As1 New 224 225 Remove Footnote 1 from Table 4.2. 226 227 Add the following subsections to Section 4.1.8 Blending, at the end of the 228 description of Blend Function (p. 294) 229 230 Dual Source Blending and Multiple Draw Buffers 231 232 Blend functions that require the second color input, <Rs1, Gs1, Bs1, As1> 233 (SRC1_COLOR, SRC1_ALPHA, ONE_MINUS_SRC1_COLOR, or 234 ONE_MINUS_SRC1_ALPHA) may consume hardware resources that could 235 otherwise be used for rendering to multiple draw buffers. Therefore, the 236 number of draw buffers that can be attached to a frame buffer may be lower 237 when using dual-source blending. 238 239 The maximum number of draw buffers that may be attached to a single frame 240 buffer when using dual-source blending functions is implementation dependent 241 and can be queried by calling GetIntegerv with the symbolic constant 242 MAX_DUAL_SOURCE_DRAW_BUFFERS. When 243 using dual-source blending, MAX_DUAL_SOURCE_DRAW_BUFFERS should be used 244 in place of MAX_DRAW_BUFFERS to determine the maximum number of draw 245 buffers that may be attached to a single frame buffer. The value of 246 MAX_DUAL_SOURCE_DRAW_BUFFERS must be at least 1. If the value of 247 MAX_DUAL_SOURCE_DRAW_BUFFERS is 1, then dual-source blending and 248 multiple draw buffers cannot be used simultaneously. 249 250 If either blend function is set to one of the second source factors 251 (SRC1_COLOR, SRC1_ALPHA, ONE_MINUS_SRC1_COLOR, or 252 ONE_MINUS_SRC1_ALPHA) for any draw buffer and any draw buffers equal to 253 or greater than the value of MAX_DUAL_SOURCE_DRAW_BUFFERS have values other than NONE, 254 the error INVALID_OPERATION is generated by Begin, or any procedure that 255 implicitly calls Begin. 256 257 Generation of Second Color Source for Blending 258 259 There is no way to generate the second source color using the fixed-function 260 fragment pipeline. Rendering using any of the blend functions that consume 261 the second input color (SRC1_COLOR, ONE_MINUS_SRC1_COLOR, 262 SRC1_ALPHA or ONE_MINUS_SRC1_ALPHA) using fixed function will produce 263 undefined results. To produce input for the second source color, a shader 264 must be used. 265 266 When using a GLSL fragment shader with dual-source blending functions, 267 the color output varyings are bound to the first and second inputs of a 268 draw buffer using BindFragDataLocationIndexed as described in the "Shader 269 Outputs" subsection of Section 3.12.2. Data written to the first of these outputs 270 becomes the first source color input to the blender (corresponding to 271 SRC_COLOR and SRC_ALPHA). Data written to the second of these outputs 272 generates the second source color input to the blender (corresponding to 273 SRC1_COLOR and SRC1_ALPHA). 274 275 If the second color input to the blender is not written in the shader, or if 276 no output is bound to the second input of a blender, the result of the blending 277 operation is not defined. 278 279 Other shading languages may define similar methods for producing the first 280 and second color inputs to blending equations. 281 282Additions to Chapter 5 of the OpenGL 3.2 Specification (Compatibility Profile) (Special 283Functions) 284 285 None. 286 287Additions to Chapter 6 of the OpenGL 3.2 Specification (Compatibility Profile) (State and 288State Requests) 289 290 None. 291 292Dependencies on ARB_fragment_shader 293 294 If ARB_fragment_shader is not supported then references to 295 ARB_fragment_shader in section 4.1.8 and elsewhere in this document should 296 be removed. In this case, there is no way to generate the second color input 297 to the blending equation unless a further extension to another shading 298 language is defined and used. 299 300Dependencies on ARB_draw_buffers 301 302 Using dual-source blending functions may consume additional outputs from 303 hardware shading units and therefore can reduce the number of draw buffers 304 that may be attached to a single frame buffer when dual-source blending 305 functions are enabled. In this case, the value of 306 MAX_DUAL_SOURCE_DRAW_BUFFERS may be less than the value of 307 MAX_DRAW_BUFFERS. If ARB_draw_buffers is not supported then the value of 308 MAX_DUAL_SOURCE_DRAW_BUFFERS will be 1. Furthermore, the discussion 309 in the subsection entitled "Dual Source Blending and Multiple Draw Buffers" 310 may be discarded. 311 312Dependencies on EXT_blend_func_separate 313 314 If EXT_blend_func_separate is not supported, remove references to 315 BlendFuncSeparate. Also, remove any references to BLEND_SRC_ALPHA and 316 BLEND_DST_ALPHA, and replace references to BLEND_SRC_RGB and BLEND_DST_RGB 317 with BLEND_SRC and BLEND_DST, respectively. In this case, the new blend 318 functions may only be enabled via the BlendFunc procedure. 319 320Dependencies on ARB_draw_buffers_blend 321 322 If ARB_draw_buffers_blend is not supported, all references to BlendFunci 323 and BlendFuncSeparatei should be removed. In this case, the blend 324 functions for all attached draw buffers will be the same. 325 326Interactions with NV_gpu_program5 327 328 If NV_gpu_program5 is supported, fragment result bindings 329 "result.color[n].primary" and "result.color[n].secondary" can be used to 330 specify the <n>th color outputs for index 0 and 1, respectively. 331 332Additions to the AGL/GLX/WGL Specifications 333 334 None. 335 336GLX Protocol 337 338 None. 339 340Errors 341 342 The error INVALID_OPERATION is generated by Begin or any procedure that 343 implicitly calls Begin if any draw buffer has a blend function requiring the 344 second color input (SRC1_COLOR, ONE_MINUS_SRC1_COLOR, SRC1_ALPHA or 345 ONE_MINUS_SRC1_ALPHA), and a framebuffer is bound that has more than 346 the value of MAX_DUAL_SOURCE_DRAW_BUFFERS-1 active color attachments. 347 348New State 349 350 Table 6.21 (p. 286) 351 352 Get Value Type Get Command Initial Value Description Sec Attribute 353 ------------------------ ---- ------------ ------------- ------------------- ----- --------- 354 BLEND_SRC_RGB Z19 GetIntegerv ONE Blending source RGB 4.1.8 color-buffer 355 function 356 BLEND_SRC_ALPHA Z19 GetIntegerv ONE Blending source A 4.1.8 color-buffer 357 function 358 BLEND_DST_RGB Z19 GetIntegerv ZERO Blending dest. RGB 4.1.8 color-buffer 359 function 360 BLEND_DST_ALPHA Z19 GetIntegerv ZERO Blending dest. A 4.1.8 color-buffer 361 function 362 363NOTE: The only change is that Z14 and Z15 change to Z19 for the existing blend 364function state. No new state is actually added to the OpenGL Specification. 365 366New Implementation Dependent State 367 368 Get Value Type Get Command Minimum Value Description Sec. Attribute 369 --------- ---- ----------- ------------- ------------------- ----- --------- 370 MAX_DUAL_SOURCE_DRAW_BUFFERS Z+ GetIntegerv 1 Maximum number of 4.1.8 - 371 active draw buffers 372 when using dual-source 373 blending 374 375Example Use Cases 376 377 There are several potential uses for this functionality. A first example 378 is in the implementation of sub-pixel accurate font rendering algorithms. 379 Given a known layout of pixel elements (red, green and blue components), 380 coverage may be calculated independently for each element and passed 381 to the blender in the second source color as a per-channel opacity. To use 382 this mode, use the following blend functions: 383 384 glBlendFunc(GL_SRC1_COLOR, GL_ONE_MINUS_SRC1_COLOR); 385 386 As a second example, consider a partially reflective colored glass window. 387 It will attenuate light passing through it, and reflect some of the light 388 that strikes it. Using an appropriate combination of functions, this effect 389 may be simulated in a single pass using only fixed-function blending 390 hardware. In this case, the following blend functions may be used: 391 392 glBlendFunc(GL_SRC_ALPHA, GL_SRC1_COLOR); 393 394Issues 395 396 1) Should the new tokens be SRC1_COLOR and SRC2_COLOR (1-based), or 397 be SRC0_COLOR and SRC1_COLOR. 398 399 RESOLVED: Indices in OpenGL are generally zero based. These follow 400 suit. 401 402 2) What happens when rendering using a dual-source blend function using 403 fixed-function? 404 405 RESOLVED: There is no reasonable way to generate the second source color 406 for blending using fixed-function fragment processing. However, as it is 407 possible to set the blend function and then enable a shader, there isn't 408 really a clean way to report an error. Therefore, we allow it, but leave 409 the result undefined. 410 411 2a) Can't we use an existing output from fixed function, like back color, 412 to make this work? 413 414 DISCUSSION: We could relabel things. For example, make the front color 415 be the first input to blending and the back color the second input. This 416 kind of thing would come at the cost of lost fixed function capability, 417 possible ambiguity and added complexity in the fixed function 418 specification. The new functionality in this extension is most useful 419 when reading data from multiple textures or other complex sources that 420 would just be too complex to express with fixed function processing. 421 For these reasons, rendering through dual-source blending functions using 422 the fixed function pipeline is not supported and will produce undefined 423 results. 424 425 2b) Then why write this against OpenGL 2.1 which includes fixed-function? 426 Why not write against OpenGL 3.x that only supports shaders anyway? 427 428 DISCUSSION: Because this extension adds functionality to existing 429 extensions and those are written against OpenGL 2.1. Furthermore, the 430 functionality described here does not rely on any core feature provided 431 by OpenGL 3.x and can be easily built upon and used in implementations of 432 OpenGL 2.1 or earlier versions of the OpenGL Specification. 433 434 RESOLVED: Updated to stand against OpenGL 3.2, but kept the fixed function 435 issues in the spec. 436 437 3) Why is this not orthogonal and interoperable with ARB_draw_buffers? 438 439 RESOLVED: This is functionality that has existed in hardware for some 440 time and been made available via other graphics APIs. In some hardware 441 and APIs, the second color input from the shader is actually what would 442 have been written to draw buffer 1. This is the functionality that is 443 guaranteed to be universally supported. This extension does not preclude 444 use with multiple draw buffers except exclusion through implementation 445 defined limits. If future hardware supports multiple color outputs 446 simultaneously to multiple draw buffers, it can simply advertise higher 447 limits. 448 449 4) Can we not add an implementation state query to find out if it's 450 available with multiple draw buffers? 451 452 RESOLVED: Done. Query MAX_DUAL_SOURCE_DRAW_BUFFERS. If this returns 453 the same value as MAX_DRAW_BUFFERS then the functions are orthogonal. 454 If this returns 1, then they cannot be used together. If it returns some 455 value between 1 and MAX_DRAW_BUFFERS, then dual-source blending 456 may consume some additional hardware routing resources, but can be used 457 with multiple draw buffers provided the MAX_DUAL_SOURCE_DRAW_BUFFERS 458 limit is not exceeded. 459 460 5) Should there also be a Link error if the fragment shader uses both an 461 index=1 output below MAX and an index=0 output greater than or equal to 462 MAX? The quoted begin-time error leaves open the possibility of an app 463 doing something like BindFragDataLocationIndexed(colorNumber=0, index=0) 464 + (colorNumber=0, index=1) + (colorNumber=1, index=0), then rendering 465 without using the src1 blend functions. If an implementation aliases 466 index=1 onto other index=0 outputs, then it wouldn't be able to handle 467 that case. 468 469 DISCUSSION: The begin time error language states '... if any draw buffer 470 has a blend function requiring the second color input ...'. This means 471 that the outputs can be bound to non-zero indices, but if the blend 472 function does not consume that output, no error will be generated. In 473 theory, an implementation could ignore output bound to color=0, index=1 474 in this case and operate as if it were not there. However, it makes no 475 sense for the linker to accept such a configuration of outputs because 476 the underlying hardware may not be able to support it. Therefore, we can 477 generate a link time error, thus eliminating this begin-time check and 478 potentially improving run-time performance. 479 480Revision History 481 482 Rev. Date Author Changes 483 ---- -------- -------- ----------------------------------------- 484 13 05/22/2015 mjk Fix misspellings 485 12 02/05/2010 istewart Add interactions with NV_gpu_program5. 486 11 01/26/2010 pbrown Assign enum values. 487 10 01/14/2010 pbrown Add spec language allowing for a link error if 488 explicit output bindings don't leave enough 489 space for array outputs. Clarify that any 490 automatic assignments for fragment outputs 491 will use color index zero. 492 9 12/10/2009 Jon Leech Fix typos in blending equation table, remove 493 ARB suffixes for core 3.3 inclusion, clean 494 up "GL_TOKEN" vs. "the value of GL_TOKEN". 495 8 11/19/2009 gsellers Remove SRC0_COLOR etc. enums, use old ones 496 instead. Use previously defined value for 497 SRC1_ALPHA. Update text to match. 498 7 10/26/2009 gsellers Change BindFragDataLocationIndexedARB to take a 499 numerical index instead of an enum. Clarify 500 behavior in several places. Add issue 5. 501 6 10/20/2009 gsellers Update to diff to OpenGL 3.2 (Compatibility) spec. 502 Add BindFragDataLocationIndexedARB and 503 GetFragDataIndexARB. Remove idea of making shader 504 outputs arrays. Define Begin time error when 505 blend func is SRC1_* for FBO with >= 506 MAX_DUAL_SOURCE_DRAW_BUFFERS draw buffers. 507 5 05/21/2009 gsellers Clarify meaning of MAX_DUAL_SOURCE_BUFFERS_ARB. 508 Clarify the (lack of) interaction with fixed 509 function fragment processing and further 510 justify lack of support (Issues 2a and 2b). 511 Clarify modification to state. 512 4 05/19/2009 gsellers Allow simultaneous use of ARB_draw_buffers with 513 this extension; 514 add MAX_DUAL_SOURCE_DRAW_BUFFERS_ARB. 515 Document interaction with ARB_draw_buffers_blend. 516 3 05/19/2009 gsellers Remove access via gl_FragData, replace with user 517 defined output varyings. 518 2 05/15/2009 gsellers Minor cleanup. Add usage examples. 519 1 05/14/2009 gsellers Initial draft 520