1Name 2 3 ATI_draw_buffers 4 5Name Strings 6 7 GL_ATI_draw_buffers 8 9Contributors 10 11 Benj Lipchak 12 13Contact 14 15 Rob Mace, ATI Research (rob.mace 'at' amd.com) 16 17Status 18 19 Complete. 20 21Version 22 23 Last Modified Date: November 4, 2006 24 Revision: 9 25 26Number 27 28 277 29 30Dependencies 31 32 The extension is written against the OpenGL 1.3 Specification. 33 34 OpenGL 1.3 is required. 35 36 ARB_fragment_program affects the definition of this extension. 37 38 39Overview 40 41 This extension extends ARB_fragment_program to allow multiple output 42 colors, and provides a mechanism for directing those outputs to 43 multiple color buffers. 44 45 46Issues 47 48 (1) How many GL_DRAW_BUFFER#_ATI enums should be reserved? 49 50 RESOLVED: We only need 4 currently, but for future expandability 51 it would be nice to keep the enums in sequence. We'll specify 52 16 for now, which will be more than enough for a long time. 53 54 55New Procedures and Functions 56 57 void DrawBuffersATI(sizei n, const enum *bufs); 58 59 60New Tokens 61 62 Accepted by the <pname> parameters of GetIntegerv, GetFloatv, 63 and GetDoublev: 64 65 MAX_DRAW_BUFFERS_ATI 0x8824 66 DRAW_BUFFER0_ATI 0x8825 67 DRAW_BUFFER1_ATI 0x8826 68 DRAW_BUFFER2_ATI 0x8827 69 DRAW_BUFFER3_ATI 0x8828 70 DRAW_BUFFER4_ATI 0x8829 71 DRAW_BUFFER5_ATI 0x882A 72 DRAW_BUFFER6_ATI 0x882B 73 DRAW_BUFFER7_ATI 0x882C 74 DRAW_BUFFER8_ATI 0x882D 75 DRAW_BUFFER9_ATI 0x882E 76 DRAW_BUFFER10_ATI 0x882F 77 DRAW_BUFFER11_ATI 0x8830 78 DRAW_BUFFER12_ATI 0x8831 79 DRAW_BUFFER13_ATI 0x8832 80 DRAW_BUFFER14_ATI 0x8833 81 DRAW_BUFFER15_ATI 0x8834 82 83 84Additions to Chapter 2 of the OpenGL 1.3 Specification (OpenGL 85Operation) 86 87 None 88 89 90Additions to Chapter 3 of the OpenGL 1.3 Specification (Rasterization) 91 92 Modify Section 3.11.2, Fragment Program Grammar and Semantic 93 Restrictions 94 95 (replace <resultBinding> grammar rule with these rules) 96 97 <resultBinding> ::= "result" "." "color" <optOutputColorNum> 98 | "result" "." "depth" 99 100 <optOutputColorNum> ::= "" 101 | "[" <outputColorNum> "]" 102 103 <outputColorNum> ::= <integer> from 0 to MAX_DRAW_BUFFERS_ATI-1 104 105 106 Modify Section 3.11.3.4, Fragment Program Results 107 108 (modify Table X.3) 109 110 Binding Components Description 111 ----------------------------- ---------- ---------------------------- 112 result.color[n] (r,g,b,a) color n 113 result.depth (*,*,*,d) depth coordinate 114 115 Table X.3: Fragment Result Variable Bindings. Components labeled 116 "*" are unused. "[n]" is optional -- color <n> is used if 117 specified; color 0 is used otherwise. 118 119 (modify third paragraph) If a result variable binding matches 120 "result.color[n]", updates to the "x", "y", "z", and "w" components 121 of the result variable modify the "r", "g", "b", and "a" components, 122 respectively, of the fragment's corresponding output color. If 123 "result.color[n]" is not both bound by the fragment program and 124 written by some instruction of the program, the output color <n> of 125 the fragment program is undefined. 126 127 128 Add a new Section 3.11.4.5.3 129 130 3.11.4.5.3 Draw Buffers Program Option 131 132 If a fragment program specifies the "ATI_draw_buffers" option, 133 it will generate multiple output colors, and the result binding 134 "result.color[n]" is allowed, as described in section 3.11.3.4, 135 and with modified grammar rules as set forth in section 3.11.2. 136 If this option is not specified, a fragment program that attempts 137 to bind "result.color[n]" will fail to load, and only "result.color" 138 will be allowed. 139 140 141Additions to Chapter 4 of the OpenGL 1.3 Specification (Per-Fragment 142Operations and the Frame Buffer) 143 144 Modify Section 4.2.1, Selecting a Buffer for Writing (p. 168) 145 146 (modify the title and first paragraph, p. 168) 147 148 4.2.1 Selecting Color Buffers for Writing 149 150 The first such operation is controlling the color buffers into 151 which each of the output colors are written. This is accomplished 152 with either DrawBuffer or DrawBuffersATI. DrawBuffer defines the 153 set of color buffers to which output color 0 is written. 154 155 (insert paragraph between first and second paragraph, p. 168) 156 157 DrawBuffer will set the draw buffer for output colors other than 0 158 to NONE. DrawBuffersATI defines the draw buffers to which all 159 output colors are written. 160 161 void DrawBuffersATI(sizei n, const enum *bufs); 162 163 <n> specifies the number of buffers in <bufs>. <bufs> is a pointer 164 to an array of symbolic constants specifying the buffer to which 165 each output color is written. The constants may be NONE, 166 FRONT_LEFT, FRONT_RIGHT, BACK_LEFT, BACK_RIGHT, and AUX0 through 167 AUXn, where n + 1 is the number of available auxiliary buffers. The 168 draw buffers being defined correspond in order to the respective 169 output colors. The draw buffer for output colors beyond <n> is set 170 to NONE. 171 172 If the "ATI_draw_buffers" fragment program option, is not being used 173 then DrawBuffersATI specifies a set of draw buffers into which output 174 color 0 is written. 175 176 The maximum number of draw buffers is implementation dependent and 177 must be at least 1. The number of draw buffers supported can 178 be queried with the state MAX_DRAW_BUFFERS_ATI. 179 180 The constants FRONT, BACK, LEFT, RIGHT, and FRONT_AND_BACK that 181 refer to multiple buffers are not valid for use in DrawBuffersATI 182 and will result in the error INVALID_OPERATION. 183 184 If DrawBuffersATI is supplied with a constant (other than NONE) 185 that does not indicate any of the color buffers allocated to 186 the GL context, the error INVALID_OPERATION will be generated. If 187 <n> is greater than MAX_DRAW_BUFFERS_ATI, the error 188 INVALID_OPERATION will be generated. 189 190 (replace last paragraph, p. 169) 191 192 The state required to handle color 193 buffer selection is an integer for each supported output color. In 194 the initial state, draw buffer for output color 0 is FRONT if there 195 are no back buffers; otherwise it is BACK. The initial state of 196 draw buffers for output colors other then 0 is NONE. 197 198 199Additions to Chapter 5 of the OpenGL 1.3 Specification (Special 200Functions) 201 202 None 203 204 205Additions to Chapter 6 of the OpenGL 1.3 Specification (State and 206State Requests) 207 208 None 209 210 211Dependencies on ARB_fragment_program 212 213 If ARB_fragment_program is not supported then all changes to 214 section 3.11 are removed. 215 216 217Interactions with possible future extensions 218 219 If there is some other future extension that defines multiple 220 color outputs then this extension and glDrawBuffersATI could be 221 used to define the destinations for those outputs. This extension 222 need not be used only with ARB_fragment_program. 223 224 225Errors 226 227 The error INVALID_OPERATION is generated by DrawBuffersATI if a 228 color buffer not currently allocated to the GL context is specified. 229 230 The error INVALID_OPERATION is generated by DrawBuffersATI if <n> 231 is greater than the state MAX_DRAW_BUFFERS_ATI. 232 233 The error INVALID_OPERATION is generated by DrawBuffersATI if value in 234 <bufs> does not correspond to one of the allowed buffers. 235 236 237New State 238 239 (table 6.19, p227) add the following entry: 240 241 Get Value Type Get Command Initial Value Description Section Attribute 242 ------------------------------- ------ ------------- ------------- -------------------- ------------ ------------ 243 DRAW_BUFFERi_ATI Z10* GetIntegerv see 4.2.1 Draw buffer selected 4.2.1 color-buffer 244 for output color i 245 246 247New Implementation Dependent State 248 249 Get Value Type Get Command Minimum Value Description Sec. Attribute 250 --------- ---- ----------- ------------- ------------------- ----- --------- 251 MAX_DRAW_BUFFERS_ATI Z+ GetIntegerv 1 Maximum number of 4.2.1 - 252 active draw buffers 253 254 255Revision History 256 257 Date: 11/4/2006 258 Revision: 9 259 - Updated contact info after ATI/AMD merger. 260 261 Date: 12/30/2002 262 Revision: 8 263 - Clarified that DrawBuffersATI will set the set of draw buffers to 264 write color output 0 to when the "ATI_draw_buffer" fragments 265 program option is not in use. 266 267 Date: 9/27/2002 268 Revision: 7 269 - Fixed confusion between meaning of color buffer and draw buffer 270 in last revision. 271 - Fixed mistake in when an error is generated based on the <n> 272 argument of DrawBuffersATI. 273 274 Date: 9/26/2002 275 Revision: 6 276 - Cleaned up and put in sync with latest ARB_fragment_program 277 revision (#22). Some meaningless changes made just in the name 278 of consistency. 279 280 Date: 9/11/2002 281 Revision: 5 282 - Added section 3.11.4.5.3. 283 - Added enum numbers to New Tokens. 284 285 Date: 9/9/2002 286 Revision: 4 287 - Changed error from MAX_OUTPUT_COLORS to MAX_DRAW_BUFFERS_ATI. 288 - Changed 3.10 section numbers to 3.11 to match change to 289 ARB_fragment_program spec. 290 - Changed ARB_fragment_program from required to affects, and 291 added section on interactions with it and future extensions 292 that define multiple color outputs. 293 294 Date: 9/6/2002 295 Revision: 3 296 - Changed error to INVALID OPERATION. 297 - Cleaned up typos. 298 299 Date: 8/19/2002 300 Revision: 2 301 - Added a paragraph that specifically points out that the 302 constants that refer to multiple buffers are not allowed with 303 DrawBuffersATI. 304 - Changed bufs to <bufs> in a couple of places. 305 306 Date: 8/16/2002 307 Revision: 1 308 - First draft for circulation. 309