1Name 2 3 EXT_multiview_draw_buffers 4 5Name Strings 6 7 GL_EXT_multiview_draw_buffers 8 9Contributors 10 11 Acorn Pooley, NVIDIA 12 Greg Roth, NVIDIA 13 Maurice Ribble, Qualcomm 14 15Contact 16 17 Greg Roth (groth 'at' nvidia.com) 18 19Version 20 21 Version 3, Sept 03, 2011 22 23Number 24 25 OpenGL ES Extension #125 26 27Status 28 29 Complete 30 31Dependencies 32 33 Written against the OpenGL ES 2.0 Specification 34 35 NV_draw_buffers affects the definition of this extension. 36 37 OpenGL ES 3.0 affects the definition of this extension. 38 39Overview 40 41 This extension allows selecting among draw buffers as the 42 rendering target. This may be among multiple primary buffers 43 pertaining to platform-specific stereoscopic or multiview displays 44 or among offscreen framebuffer object color attachments. 45 46 To remove any artificial limitations imposed on the number of 47 possible buffers, draw buffers are identified not as individual 48 enums, but as pairs of values consisting of an enum representing 49 buffer locations such as COLOR_ATTACHMENT_EXT or MULTIVIEW_EXT, 50 and an integer representing an identifying index of buffers of this 51 location. These (location, index) pairs are used to specify draw 52 buffer targets using a new DrawBuffersIndexedEXT call. 53 54 Rendering to buffers of location MULTIVIEW_EXT associated with the 55 context allows rendering to multiview buffers created by EGL using 56 EGL_EXT_multiview_window for stereoscopic displays. 57 58 Rendering to COLOR_ATTACHMENT_EXT buffers allows implementations to 59 increase the number of potential color attachments indefinitely to 60 renderbuffers and textures. 61 62 This extension allows the traditional quad buffer stereoscopic 63 rendering method that has proven effective by indicating a left or 64 right draw buffer and rendering to each accordingly, but is also 65 dynamic enough to handle an arbitrary number of color buffer targets 66 all using the same shader. This grants the user maximum flexibility 67 as well as a familiar interface. 68 69New Procedures and Functions 70 71 void ReadBufferIndexedEXT(enum src, int index); 72 void DrawBuffersIndexedEXT(int n, const enum *location, 73 const int *indices); 74 void GetIntegeri_vEXT(enum target, uint index, int *data); 75 76New Tokens 77 78 Accepted by the <location> parameter of DrawBuffersIndexedEXT: 79 80 COLOR_ATTACHMENT_EXT 0x90F0 81 MULTIVIEW_EXT 0x90F1 82 83 Accepted by the <target> parameter of GetIntegeri_EXT: 84 85 DRAW_BUFFER_EXT 0x0C01 86 READ_BUFFER_EXT 0x0C02 87 88 Accepted by the <target> parameter of GetInteger: 89 90 MAX_MULTIVIEW_BUFFERS_EXT 0x90F2 91 92 93Changes to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment 94Operations and the Frame Buffer) 95 96 Modify section 4.2.1, "Selecting a Buffer for Writing" 97 98 Change first paragraph to: 99 100 By default, color values are written into the front buffer for 101 single buffered contexts or into the back buffer for back buffered 102 contexts as determined when creating the GL context. To control 103 the color buffer into which each of the fragment color values is 104 written, DrawBuffersNV or DrawBuffersIndexedEXT is used. 105 106 Add to the end of 4.2.1: 107 108 The command 109 110 void DrawBuffersIndexedEXT(sizei n, const enum *locations, 111 const int *indices); 112 113 defines the draw buffers to which all fragment colors are written. 114 <n> specifies the number of values in <locations> and <indices>. 115 <locations> is a pointer to an array of symbolic constants 116 specifying the location of the draw buffer. <indices> is a pointer 117 to an array of integer values specifying the index of the draw 118 buffer. Together <locations> and <indices> specify the draw buffer 119 to which each fragment color is written. 120 121 Each constant in <locations> must be MULTIVIEW_EXT, COLOR_- 122 ATTACHMENT_EXT, or NONE. Otherwise, an INVALID_ENUM error is 123 generated. Further, acceptable values for the constants in 124 <locations> depend on whether the GL is using the default 125 framebuffer (i.e. DRAW_FRAMEBUFFER_BINDING is non-zero). For more 126 information about framebuffer objects, see section 4.4. 127 128 If the GL is bound to the default framebuffer, then each of the 129 location constants must be MULTIVIEW_EXT or NONE. 130 131 If the GL is bound to a framebuffer object, then each of the 132 location constants must be COLOR_ATTACHMENT_EXT or NONE. 133 134 Where the constant in <locations> is MULTIVIEW_EXT, the 135 corresponding value in <indices> must be a value from 0 through 136 MAX_MULTIVIEW_BUFFERS_EXT. Where the constant in <locations> is 137 COLOR_ATTACHMENT_EXT, the value in <indices> must be a value from 0 138 through MAX_COLOR_ATTACHMENTS_NV. Otherwise, an INVALID_OPERATION 139 error is generated. Where the constant in <locations> is NONE, the 140 value in <indices> is ignored. 141 142 For monoscopic rendering, the only available view is index 0. For 143 stereoscopic rendering, view index 0 corresponds to the left buffer 144 and view index 1 corresponds to the right buffer. 145 146 The draw buffers being defined correspond, in order, to the 147 respective fragment colors. The draw buffer for fragment colors 148 beyond <n> is set to NONE. 149 150 Except for where the constant in <locations> is NONE, a buffer may 151 not be specified more than once by the arrays pointed to by 152 <locations> and <indices>. Specifying a buffer more than once will 153 result in the error INVALID_OPERATION. 154 155 If a fragment shader writes to "gl_FragColor", DrawBuffersIndexedEXT 156 specifies a set of draw buffers into which the color written to 157 "gl_FragColor" is written. If a fragment shader writes to 158 gl_FragData, DrawBuffersIndexedEXT specifies a set of draw buffers 159 into which each of the multiple output colors defined by these 160 variables are separately written. If a fragment shader writes to 161 neither gl_FragColor nor gl_FragData, the values of the fragment 162 colors following shader execution are undefined, and may differ 163 for each fragment color. 164 165 Indicating a buffer or buffers using DrawBuffersIndexedEXT causes 166 subsequent pixel color value writes to affect the indicated 167 buffers. If more than one color buffer is selected for drawing, 168 blending is computed and applied independently for each buffer. 169 170 Specifying NONE in the <locations> array for a fragment color will 171 inhibit that fragment color from being written to any buffer. 172 173 Monoscopic surfaces include only left buffers, while stereoscopic 174 surfaces include a left and a right buffer, and multiview surfaces 175 include more than 1 buffer (a stereoscopic surface is a multiview 176 surface with 2 buffers). The type of surface is selected at EGL 177 surface initialization. 178 179 The state required to handle color buffer selection is two integers 180 for each supported fragment color for each framebuffer or 181 framebuffer object. For the default framebuffer, the initial state 182 of the draw buffer location for fragment color zero is MULTIVIEW_EXT 183 and the index is 0. For framebuffer objects, the initial state of 184 the draw buffer location for fragment color zero is COLOR_- 185 ATTACHMENT_EXT and the index is 0. The initial state of draw buffers 186 for fragment colors other than zero is NONE. 187 188 The color buffer location and index to which fragment colors are 189 written for an output color index <i> can be queried by calling 190 GetIntegeri_vEXT with <target> DRAW_BUFFER_EXT and index 191 <i>. This returns a pair of values representing the draw buffer 192 location and index. The number of multiview buffers available to a 193 GL context can be queried by calling GetIntegerv with <target> 194 MAX_MULTIVIEW_BUFFERS_EXT. 195 196 Section 4.3.1 (Reading Pixels), subsection "Obtaining Pixels from 197 the Framebuffer" add: 198 199 For color formats, the read buffer from which values are obtained is 200 one of the color buffers; the selection of color buffer is 201 controlled with ReadBufferIndexedEXT. 202 203 The command 204 205 void ReadBufferIndexedEXT(enum location, int index); 206 207 takes a symbolic constant and integer pair to select the color 208 buffer from which color values are obtained. <location> must be one 209 of MULTIVIEW_EXT, COLOR_ATTACHMENT_EXT, or NONE. Otherwise, an 210 INVALID_ENUM error is generated. If <location> is MULTIVIEW_EXT, 211 <index> must be a value from 0 through MAX_MULTIVIEW_BUFFERS_EXT. 212 If <location> is COLOR_ATTACHMENT_EXT, <index> must be a value from 213 0 through MAX_COLOR_ATTACHMENTS_NV. Otherwise, an INVALID_OPERATION 214 error is generated. If <location> is NONE, <index> is ignored. 215 216 The acceptable values for <location> depend on whether the GL is 217 using the default framebuffer (i.e. FRAMEBUFFER_BINDING is zero), or 218 a framebuffer object (i.e. FRAMEBUFFER_BINDING is non-zero). For 219 more information about framebuffer objects, see section 4.4. 220 221 If the object bound to FRAMEBUFFER_BINDING is not framebuffer 222 complete (as defined in section 4.4.5), then ReadPixels generates 223 the error INVALID_FRAMEBUFFER_OPERATION. If <location> is a constant 224 that is neither legal for the default framebuffer, nor legal for a 225 framebuffer object, then the error INVALID_ENUM results. 226 227 When FRAMEBUFFER_BINDING is zero, i.e. the default framebuffer, 228 <location> must be MULTIVIEW_EXT or NONE. If the buffer indicated by 229 <index> is missing, the error INVALID_OPERATION is generated. For 230 the default framebuffer, the initial setting for READ_BUFFER_EXT is 231 <location> of MULTIVIEW_EXT and <index> of zero. 232 233 When the GL is using a framebuffer object, <location> must be NONE 234 or COLOR_ATTACHMENT_EXT. Specifying COLOR_ATTACHMENT_EXT enables 235 reading from the image attached to the framebuffer at COLOR_- 236 ATTACHMENT<index>_NV. For framebuffer objects, the initial setting 237 for READ_BUFFER_EXT is <location> of COLOR_ATTACHMENT_EXT and 238 <index> of zero. 239 240 ReadPixels generates an INVALID_OPERATION error if it attempts to 241 select a color buffer while READ_BUFFER_EXT is none. 242 243Changes to chapter 6 244 245 Add to section 6.1.1, "Simple Queries" before description of 246 IsEnabled: 247 248 Indexed simple state variables are queried with the command 249 250 void GetIntegeri_vEXT(enum target, uint index, int* data); 251 252 <target> is the name of the indexed state and <index> is the 253 index of the particular element being queried. <data> is a 254 pointer to a scalar or array of the indicated type in which 255 to place the returned data. An INVALID_VALUE error is generated 256 if <index> is outside the valid range for the indexed state 257 <target>. 258 259Changes to Chapter 3 of the OpenGL Shading Language 1.0 Specification 260(Basics) 261 262 Add a new section: 263 264 3.4.1 GL_EXT_multiview_draw_buffers Extension 265 266 To use the GL_EXT_multiview_draw_buffers extension in a shader it 267 must be enabled using the #extension directive. 268 269 The shading language preprocessor #define GL_EXT_multiview_draw_- 270 buffers will be defined to 1, if the GL_EXT_multiview_draw_buffers 271 extension is supported. 272 273Dependencies on NV_draw_buffers: 274 275 If NV_draw_buffers is not supported and OpenGL ES 3 is, add to the 276 description of DrawBuffersIndexedEXT: 277 278 The <i>th index listed in <indices> must be <i> or NONE. 279 Specifying a buffer out of order will generate the error 280 INVALID_OPERATION. 281 282 If neither NV_draw_buffers nor OpenGL ES 3 is supported, all 283 references to DrawBuffersNV and color attachments are removed. The 284 following is substituted for the above changes to Chapter 4 (Per- 285 Fragment Operations and the Frame Buffer): 286 287 Change section 4.2.1, "Selecting a Buffer for Writing" 288 289 Change first paragraph to: 290 291 By default, color values are written into the front buffer for 292 single buffered contexts or into the back buffer for back buffered 293 contexts as determined when creating the GL context. To control 294 the color buffer into which each of the fragment color values is 295 written, DrawBuffersIndexedEXT is used. 296 297 Add to the end of 4.2.1: 298 299 The command 300 301 void DrawBuffersIndexedEXT(sizei n, const enum *locations, 302 const int *indices); 303 304 defines the draw buffers to which all fragment colors are written. 305 <n> specifies the number of values in <locations> and <indices>. 306 <locations> is a pointer to an array of symbolic constants 307 specifying the location of the draw buffer. <indices> is a pointer 308 to an array of integer values specifying the index of the draw 309 buffer. Together <locations> and <indices> specify the draw buffer 310 to which each fragment color is written. 311 312 Each constant in <locations> must be MULTIVIEW_EXT or NONE. 313 Otherwise, an INVALID_ENUM error is generated. 314 315 DrawBuffersIndexedEXT generates an INVALID_OPERATION error if the GL 316 is bound to a framebuffer object. 317 318 Where the constant in <locations> is MULTIVIEW_EXT, the 319 corresponding value in <indices> must be a value from 0 through 320 MAX_MULTIVIEW_BUFFERS_EXT. Otherwise, an INVALID_OPERATION error is 321 generated. Where the constant in <locations> is NONE, the value 322 in <indices> is ignored. 323 324 An INVALID_VALUE error is generated if <n> is not 1. 325 326 For monoscopic rendering, the only available view is index 0. For 327 stereoscopic rendering, view index 0 is left and view index 1 is 328 right. 329 330 If a fragment shader writes to "gl_FragColor" or "gl_FragData[0]", 331 DrawBuffersIndexedEXT specifies a set of draw buffers into which the 332 output color is written. If a fragment shader writes to neither 333 gl_FragColor nor gl_FragData[0], the values of the fragment colors 334 following shader execution are undefined, and may differ for each 335 fragment color. 336 337 Indicating a buffer using DrawBuffersIndexedEXT causes subsequent 338 pixel color value writes to affect the indicated buffer. 339 340 Specifying NONE in the <locations> array for a fragment color will 341 inhibit that fragment color from being written to any buffer. 342 343 Monoscopic surfaces include only left buffers, while stereoscopic 344 surfaces include a left and a right buffer, and multiview surfaces 345 include more than 1 buffer (a stereoscopic surface is a multiview 346 surface with 2 buffers). The type of surface is selected at EGL 347 surface initialization. 348 349 The state required to handle color buffer selection is two integers 350 for the fragment color output for each framebuffer or framebuffer 351 object. For the default framebuffer, the initial state of the draw 352 buffer location for fragment color zero is MULTIVIEW_EXT and the 353 index is 0. For framebuffer objects, the initial state of the draw 354 buffer location for fragment color zero is COLOR_ATTACHMENT_EXT and 355 the index is 0. 356 357 The color buffer location and index to which fragment colors are 358 written can be queried by calling GetIntegeri_vEXT with <target> 359 DRAW_BUFFER_EXT and index 0. This returns a pair of values 360 representing the draw buffer location and index. The number of 361 multiview buffers available to a GL context can be queried by 362 calling GetIntegerv with <target> MAX_MULTIVIEW_BUFFERS_EXT. 363 364 The command 365 366 void ReadBufferIndexedEXT(enum location, int index); 367 368 takes a symbolic constant and integer pair to select the color 369 buffer from which color values are obtained. <location> must be 370 MULTIVIEW_EXT or NONE. Otherwise, an INVALID_ENUM error is 371 generated. If <location> is MULTIVIEW_EXT, <index> must be a value 372 from 0 through MAX_MULTIVIEW_BUFFERS_EXT. Otherwise, an 373 INVALID_OPERATION error is generated. If <location> is NONE, the 374 <index> is ignored. 375 376 When FRAMEBUFFER_BINDING is zero, i.e. the default framebuffer, 377 <location> must be MULTIVIEW_EXT or NONE. If the buffer indicated by 378 <index> is missing, the error INVALID_OPERATION is generated. For 379 the default framebuffer, the initial setting for READ_BUFFER_EXT is 380 <location> of MULTIVIEW_EXT and <index> of zero. 381 382 ReadBufferIndexedEXT generates an INVALID_OPERATION error if the GL 383 is bound to a framebuffer object. 384 385 ReadPixels generates an INVALID_OPERATION error if it attempts to 386 select a color buffer while READ_BUFFER_EXT is none. 387 388New State 389 390 Add the new Table 6.X "Framebuffer (State per framebuffer object)" : 391 392 State Type Get Command Initial Description 393 --------------- ----- --------------- ------- ----------- 394 DRAW_BUFFER_EXT nxZ+ GetIntegeri_vEXT See 4.2.1 Multiview draw buffer 395 location and index 396 selected for the 397 specified color output 398 READ_BUFFER_EXT nxZ+ GetInteger See 4.3.1 Read source buffer 399 location and index 400 401 Add the new Table 6.X "Framebuffer Dependent Values" : 402 403 State Type Get Command Min Value Description 404 --------------- ----- --------------- --------- ----------- 405 MAX_MULTIVIEW_BUFFERS_EXT Z+ GetIntegerv 1 Number of multiview 406 draw buffers 407 408Issues 409 410 1. What should this extension be called? 411 412 RESOLVED: multiview_draw_buffers. Multiview has come to be the 413 standard term to refer to stereoscopic and beyond buffer rendering 414 and this approach centers around the traditional usage of 415 a drawbuffers call to specify the buffer(s) to render to. 416 417 2. How should draw buffer bindings be queried? 418 419 RESOLVED: A new indexed integer query function called 420 glGetIntegeri_vEXT. This extension adds an indexed binding for draw 421 buffers so it follows that an indexed query should be used to 422 retrieve the state that it sets. The name glGetIntegeri_vEXT is 423 chosen as it was in desktop GL to clarify the 'i' suffix 424 indicating an indexed call as opposed to 'i' indicating an integer 425 variant of a call accepting parameters of various types. 426 427 3. Should the <location> parameter of DrawBuffersIndexedEXT be removed? 428 429 RESOLVED: No. It is useful when draw_buffers is supported. 430 431Revision History 432 Version 4, 25 Sept 2012 Clean up overview. Fix a few typographical 433 errors. 434 Version 3, 03 Sept 2011 EXTify. Remove ALL broadcast. 435 Add interactions for ES3 and non- 436 draw_buffers cases 437 Version 2, 02 Aug 2011 Responses to feedback. 438 Version 1, 14 April 2011 First draft. 439 440