1Name 2 3 NV_draw_buffers 4 5Name Strings 6 7 GL_NV_draw_buffers 8 9Contact 10 11 Greg Roth, NVIDIA Corporation (groth 'at' nvidia.com) 12 13Contributors 14 15 Benj Lipchak, AMD 16 Bill Licea-Kane, AMD 17 Rob Mace, NVIDIA Corporation 18 James Helferty, NVIDIA Corporation 19 20Status 21 22 Complete. 23 24Version 25 26 Last Modified Date: July 11, 2013 27 NVIDIA Revision: 4.0 28 29Number 30 31 OpenGL ES Extension #91 32 33Dependencies 34 35 Written against the OpenGL ES 2.0 Specification and the OpenGL ES 36 Shader Language 1.0.14 Specification. 37 38 This extension interacts with the OpenGL ES 3.0 Specification 39 40Overview 41 42 This extension extends OpenGL ES 2.0 to allow multiple output 43 colors, and provides a mechanism for directing those outputs to 44 multiple color buffers. 45 46 This extension serves a similar purpose to ARB_draw_buffers except 47 that this is for OpenGL ES 2.0. 48 49 When OpenGL ES 3.0 is present, this extension relaxes the order 50 restriction on color attachments to draw framebuffer objects. 51 52IP Status 53 54 NVIDIA Proprietary 55 56New Procedures and Functions 57 58 void DrawBuffersNV(sizei n, const enum *bufs); 59 60New Tokens 61 62 Accepted by the <pname> parameters of GetIntegerv, GetFloatv, 63 and GetDoublev: 64 65 MAX_DRAW_BUFFERS_NV 0x8824 66 DRAW_BUFFER0_NV 0x8825 67 DRAW_BUFFER1_NV 0x8826 68 DRAW_BUFFER2_NV 0x8827 69 DRAW_BUFFER3_NV 0x8828 70 DRAW_BUFFER4_NV 0x8829 71 DRAW_BUFFER5_NV 0x882A 72 DRAW_BUFFER6_NV 0x882B 73 DRAW_BUFFER7_NV 0x882C 74 DRAW_BUFFER8_NV 0x882D 75 DRAW_BUFFER9_NV 0x882E 76 DRAW_BUFFER10_NV 0x882F 77 DRAW_BUFFER11_NV 0x8830 78 DRAW_BUFFER12_NV 0x8831 79 DRAW_BUFFER13_NV 0x8832 80 DRAW_BUFFER14_NV 0x8833 81 DRAW_BUFFER15_NV 0x8834 82 83 84 Accepted by the <bufs> parameter of DrawBuffersNV: 85 86 COLOR_ATTACHMENT0_NV 0x8CE0 87 COLOR_ATTACHMENT1_NV 0x8CE1 88 COLOR_ATTACHMENT2_NV 0x8CE2 89 COLOR_ATTACHMENT3_NV 0x8CE3 90 COLOR_ATTACHMENT4_NV 0x8CE4 91 COLOR_ATTACHMENT5_NV 0x8CE5 92 COLOR_ATTACHMENT6_NV 0x8CE6 93 COLOR_ATTACHMENT7_NV 0x8CE7 94 COLOR_ATTACHMENT8_NV 0x8CE8 95 COLOR_ATTACHMENT9_NV 0x8CE9 96 COLOR_ATTACHMENT10_NV 0x8CEA 97 COLOR_ATTACHMENT11_NV 0x8CEB 98 COLOR_ATTACHMENT12_NV 0x8CEC 99 COLOR_ATTACHMENT13_NV 0x8CED 100 COLOR_ATTACHMENT14_NV 0x8CEE 101 COLOR_ATTACHMENT15_NV 0x8CEF 102 103 104Changes to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization) 105 106 Section 3.2, (Multisampling). Replace the second paragraph: 107 108 An additional buffer, called the multisample buffer, is added to the 109 framebuffer. Pixel sample values, including color, depth, and 110 stencil values, are stored in this buffer. Samples contain separate 111 color values for each fragment color. When the framebuffer includes 112 a multisample buffer, it does not include depth or stencil buffers, 113 even if the multisample buffer does not store depth or stencil 114 values. The color buffer does coexist with the multisample buffer, 115 however. 116 117 Section 3.8.2, (Shader Execution) Replace subsection "Shader 118 Outputs": 119 120 The OpenGL ES Shading Language specification describes the values 121 that may be output by a fragment shader. These are gl_FragColor and 122 gl_FragData[n]. The final fragment color values or the final 123 fragment data values written by a fragment shader are clamped to the 124 range [0, 1] and then converted to fixed-point as described in 125 section 2.1.2 for framebuffer color components. 126 127 Writing to gl_FragColor specifies the fragment color (color number 128 zero) that will be used by subsequent stages of the pipeline. 129 Writing to gl_FragData[n] specifies the value of fragment color 130 number n. Any colors, or color components, associated with a 131 fragment that are not written by the fragment shader are undefined. 132 A fragment shader may not statically assign values to both 133 gl_FragColor and gl_FragData. In this case, a compile or link error 134 will result. A shader statically assigns a value to a variable if, 135 after preprocessing, it contains a statement that would write to the 136 variable, whether or not run-time flow of control will cause that 137 statement to be executed. 138 139Changes to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment 140Operations and the Frame Buffer) 141 142 Replace Section 4.2.1, "Selecting a Buffer for Writing" 143 144 By default, color values are written into the front buffer for 145 single buffered surfaces or into the back buffer for back buffered 146 surfaces as determined when making the context current. To control 147 the color buffer into which each of the fragment color values is 148 written, DrawBuffersNV is used. 149 150 The command 151 152 void DrawBuffersNV(sizei n, const enum *bufs); 153 154 defines the draw buffers to which all fragment colors are written. 155 <n> specifies the number of buffers in <bufs>. <bufs> is a pointer 156 to an array of symbolic constants specifying the buffer to which 157 each fragment color is written. 158 159 Each buffer listed in <bufs> must be NONE, COLOR_ATTACHMENT0, or 160 COLOR_ATTACHMENTi_NV, where <i> is the index of the color attachment 161 point. Otherwise, an INVALID_ENUM error is generated. DrawBuffersNV 162 may only be called when the GL is bound to a framebuffer object. If 163 called when the GL is bound to the default framebuffer, an INVALID_- 164 OPERATION error is generated. 165 166 The draw buffers being defined correspond in order to the respective 167 fragment colors. The draw buffer for fragment colors beyond <n> is 168 set to NONE. 169 170 The maximum number of draw buffers is implementation dependent and 171 must be at least 1. The number of draw buffers supported can be 172 queried by calling GetIntegerv with the symbolic constant 173 MAX_DRAW_BUFFERS_NV. An INVALID_VALUE error is generated if <n> is 174 less than one or greater than MAX_DRAW_BUFFERS_NV. 175 176 Except for NONE, a buffer may not appear more then once in the array 177 pointed to by <bufs>. Specifying a buffer more then once will result 178 in the error INVALID_OPERATION. 179 180 If a fragment shader writes to "gl_FragColor", DrawBuffersNV 181 specifies a set of draw buffers into which the color written to 182 "gl_FragColor" is written. If a fragment shader writes to 183 gl_FragData, DrawBuffers specifies a set of draw buffers into which 184 each of the multiple output colors defined by these variables are 185 separately written. If a fragment shader writes to neither 186 gl_FragColor nor gl_FragData the values of the fragment colors 187 following shader execution are undefined, and may differ for each 188 fragment color. 189 190 If DrawBuffersNV is supplied with a constant COLOR_ATTACHMENT<m> 191 where <m> is greater than or equal to the value of 192 MAX_COLOR_ATTACHMENTS_NV, then the error INVALID_OPERATION results. 193 194 Indicating a buffer or buffers using DrawBuffersNV causes subsequent 195 pixel color value writes to affect the indicated buffers. If the GL is 196 bound to a draw framebuffer object and a draw buffer selects an attachment 197 that has no image attached, then that fragment color is not written. 198 199 Specifying NONE as the draw buffer for a fragment color will inhibit 200 that fragment color from being written to any buffer. 201 202 The state required to handle color buffer selection is an integer 203 for each supported fragment color. For each framebuffer object, the 204 initial state of the draw buffer for fragment color zero is COLOR_- 205 ATTACHMENT0 and the initial state of draw buffers for fragment 206 colors other than zero is NONE. 207 208 The value of the draw buffer selected for fragment color <i> can be 209 queried by calling GetIntegerv with the symbolic constant 210 DRAW_BUFFER<i>_NV. 211 212Changes to Chapter 3 of the OpenGL Shading Language 1.0 Specification (Basics) 213 214 Add a new section: 215 216 3.3.1 GL_NV_draw_buffers Extension 217 218 To use the GL_NV_draw_buffers extension in a shader it must be 219 enabled using the #extension directive. 220 221 The shading language preprocessor #define GL_NV_draw_buffers will be 222 defined to 1, if the GL_NV_draw_buffers extension is supported. 223 224Interactions with OpenGL ES 3.0 225 226 Section 4.2.1 of OpenGL ES 3.0, (Selecting a Buffer for Writing). Replace 227 the eighth and ninth paragraph: 228 229 If the GL is bound to a draw framebuffer object, the ith buffer listed in 230 bufs must be COLOR_ATTACHMENTm or NONE, where m is less than the value of 231 MAX_COLOR_ATTACHMENTS. Specifying BACK or COLOR_ATTACHMENTm where m is 232 greater than or equal to MAX_COLOR_ATTACHMENTS will generate the error 233 INVALID_OPERATION. 234 235 If an OpenGL ES Shading Language 1.00 or 3.00 fragment shader writes a 236 user-defined varying out variable, DrawBuffers specifies a set of draw 237 buffers into which each of the multiple output colors defined by these 238 variables are separately written. If a fragment shader writes to none of 239 gl_FragColor, gl_FragData, nor any user-defined output variables, the 240 values of the fragment colors following shader execution are undefined, and 241 may differ for each fragment color. If some, but not all user-defined 242 output variables are written, the values of fragment colors corresponding 243 to unwritten variables are similarly undefined. 244 245New State 246 247 Add Table 6.X Framebuffer (State per framebuffer object): 248 249 State Type Get Command Initial Value Description 250 --------------- ---- ------------ ------------- ----------- 251 DRAW_BUFFERi_NV Z10* GetIntegerv see 4.2.1 Draw buffer selected 252 for fragment color i 253 254 Add the new Table 6.X "Framebuffer Dependent Values" : 255 256 State Type Get Command Min Value Description 257 ------------------- ---- ----------- --------- ----------- 258 MAX_DRAW_BUFFERS_NV Z+ GetIntegerv 1 Maximum number of 259 active draw buffers 260 261Issues 262 263 1. What behavior should be expected if a draw buffer selects an attachment 264 for a draw framebuffer that has no image attached? 265 266 Early drivers considered this an INVALID_OPERATION and the DrawBuffersNV 267 operation did not succeed. (Following precedent set in Issue 55 of 268 EXT_framebuffer_object) 269 270 OpenGL ES 3.0 and Desktop GL 4.3 consider this legal, and the DrawBuffers 271 call succeeds. Missing attachments are simply not written to. 272 273 RESOLVED: Behavior should match OpenGL ES 3.0. Application developers are 274 cautioned that early Tegra drivers may exhibit the previous behavior. 275 276 See ARB_draw_buffers for additional relevant issues. 277 278Revision History 279 280 Rev. Date Author Changes 281 ---- -------- --------- ------------------------------------ 282 4 07/11/13 jhelferty Updated error behavior for missing 283 attachments to match ES 3.0. 284 Clarified ES 3.0 interactions. 285 3 06/07/11 groth Clarified default behavior, state tables. 286 2 04/26/11 groth Filled in many missing elements. 287 1 03/03/08 kashida First revision based on 288 ARB_draw_buffers. 289