1XXX - Not complete yet!!! 2 3Name 4 5 SGIX_async 6 7Name Strings 8 9 GL_SGIX_async 10 11Version 12 13 $Date: 1998/06/04 20:57:36 $ $Revision: 1.8 $ 14 15Number 16 17 132 18 19Dependencies 20 21 None. 22 23Overview 24 25 This extension provides a framework for asynchronous OpenGL 26 commands. It also provides commands allowing a program to wait 27 for the completion of asynchronous commands. 28 29 Asynchronous commands have two properties: 30 31 1) Asynchronous commands are non-blocking. For example, an 32 asynchronous ReadPixels command returns control to the program 33 immediately rather than blocking until the command completes. 34 This property allows the program to issue other OpenGL commands in 35 parallel with the execution of commands that normally block. 36 37 2) Asynchronous commands may complete out-of-order with respect to 38 other OpenGL commands. For example, an asynchronous TexImage 39 command may complete after subsequent OpenGL commands issued by 40 the program rather than maintaining the normal serial order of the 41 OpenGL command stream. This property allows the graphics 42 accelerator to execute asynchronous commands in parallel with the 43 normal command stream, for instance using a secondary path to 44 transfer data from or to the host, without doing any dependency 45 checking. 46 47 Programs that issue asynchronous commands must also be able to 48 determine when the commands have completed. The completion status 49 may be needed so that results can be retrieved (e.g. the image 50 data from a ReadPixels command) or so that dependent commands can 51 be issued (e.g. drawing commands that use texture data downloaded 52 by an earlier asynchronous command). This extension provides 53 fine-grain control over asynchronous commands by introducing a 54 mechanism for determining the status of individual commands. 55 56 Each invocation of an asynchronous command is associated with an 57 integer called a "marker." A program specifies a marker before it 58 issues an asynchronous command. The program may later issue a 59 command to query if any asynchronous commands have completed. The 60 query commands return a marker to identify the command that 61 completed. This extension provides both blocking and non-blocking 62 query commands. 63 64 This extension does not define any asynchronous commands. 65 See SGIX_async_pixel for the asynchronous pixel commands. 66 67Issues 68 69 * Should all asynchronous operations share the same marker name space? 70 71 Ans: Yes. The argument for separate name spaces is that it 72 makes modularizing an application easier. The proposal was to 73 use a separate name space for each category of commands, 74 e.g. readpixels, teximage, drawpixels, and histogram. That works 75 if each name space is used by only one part of the application 76 (e.g. one part of the application issues asynchronous readpixels 77 and some other part issues asynchronous teximage), but it 78 doesn't work if there are multiple uses of one name space 79 (e.g. two libraries that both use asynchronous readpixels). It 80 doesn't seem worth complicating the API to provide such a 81 limited benefit. The better solution is for a higher-level API 82 to provide a mechanism for registering an interest in particular 83 markers, similar to the X Windows mechanism for distributing 84 window events. 85 86 * Should the order of asynchronous operations be preserved, even 87 if they are executed out-of-order with respect to normal commands? 88 89 Ans: No, let the extensions that define the async operations choose 90 whether or not to preserve order. 91 92 * Should the extension also define a WaitAsyncSGIX command that 93 guarantees completion of a specified asynchronous command before 94 subsequent commands are executed? This command wouldn't require 95 the marker to make a round trip back to the host like 96 FinishAsyncSGIX does, so it could be implemented more efficiently. 97 98 Ans: No for now (no compelling application). 99 100 * When are errors associated with an asynchronous command 101 reported? 102 103 Ans: A call to GetError after an asynchronous command always 104 reports any errors associated with the command. The behavior 105 is as if errors are detected at the time a command is issued rather 106 than when it is executed. In this respect asynchronous commands 107 are no different from synchronous commands. 108 109 * Should a call to MakeCurrent implicitly force all pending 110 asynchronous commands to complete? 111 112 Ans: This is an implementation issue. It does not affect the 113 semantics of this extension. 114 115 * Should there be an implementation-dependent limit on the 116 number of outstanding asynchronous commands before the 117 application calls FinishAsync? 118 119 Ans: This extension does not impose such a limit, but the 120 extensions that introduce asynchronous commands must address the 121 issue. An asynchronous command that uses an application-allocated 122 buffer for return results (e.g. instruments) lets the application 123 determine the limit by sizing the buffer appropriately. 124 125 * Should this extension modify the instruments extension to use 126 the new PollAsyncSGIX command instead of PollInstrumentsSGIX? 127 128 Ans: No for now. 129 130 * Should there be a generic command to set the current marker 131 instead of a different mechanism for each asynchronous command? 132 133 Ans: Yes, this has been added (AsyncMarkerSGIX). 134 135 * Should there be a command to reserve a set of markers, like 136 GenLists? 137 138 Ans: Yes, this has been added (GenAsyncMarkers and 139 DeleteAsyncMarkers). 140 141 * Should name spaces be specified using enums instead of bitmasks? 142 143 Ans: Yes, but name spaces have now been removed (see above). 144 145 * Would it be better to define an extension that provides non-blocking 146 commands rather than asynchronous commands? 147 148 Ans: No. Non-blocking commands would require the GL to preserve 149 the order of commands, but that limits the potential for 150 optimization. The GL would have to check for dependencies 151 between a non-blocking command and all subsequent commands 152 (which is hard to do efficiently), or stall all subsequent 153 commands until the non-blocking command completes, or maintain 154 multiple sets of state. By defining an asynchronous style of 155 execution we place the burden of detecting dependencies on the 156 application. There is a large class of applications which can 157 easily guarantee that there are no dependencies. 158 159New Procedures and Functions 160 161 void AsyncMarkerSGIX(uint marker) 162 163 int FinishAsyncSGIX(uint *markerp) 164 165 int PollAsyncSGIX(uint *markerp) 166 167 uint GenAsyncMarkersSGIX(sizei range) 168 169 void DeleteAsyncMarkersSGIX(uint marker, sizei range) 170 171 boolean IsAsyncMarkerSGIX(uint marker) 172 173New Tokens 174 175 Accepted by the <pname> parameters of GetBooleanv, GetIntegerv, 176 GetFloatv, and GetDoublev: 177 178 ASYNC_MARKER_SGIX 0x8329 179 180Additions to Chapter 2 of the 1.1 Specification (OpenGL Operation) 181 182 None 183 184Additions to Chapter 3 of the 1.1 Specification (Rasterization) 185 186 None 187 188Additions to Chapter 4 of the 1.1 Specification (Fragments and the 189Frame Buffer) 190 191 None 192 193Additions to Chapter 5 of the 1.1 Specification (Special Functions) 194 195 Add to section 5.4 (Display Lists): 196 197 The following commands are not included in display lists: 198 199 FinishAsyncSGIX 200 PollAsyncSGIX 201 GenAsyncMarkersSGIX 202 DeleteAsyncMarkersSGIX 203 IsAsyncMarkerSGIX 204 205 Add a section 5.X prior to the Instruments section entitled 206 "Asynchronous Commands": 207 208 Asynchronous commands are commands that may complete out-of-order 209 with respect to other OpenGL commands. An asynchronous command 210 samples the OpenGL state vector when it is issued. The sampled 211 state includes the results from the complete execution of all 212 synchronous (normal) commands issued prior to the asynchronous 213 command. However, the results of an asynchronous command (state 214 changes or framebuffer updates) are not necessarily committed in 215 order. An asynchronous command may commit its results any time 216 after the completion of all synchronous commands issued prior to 217 the asynchronous command. An implementation may choose to execute 218 asynchronous commands in parallel with subsequent commands or at 219 some convenient time in the future. 220 221 Implementations of asynchronous commands may also be non-blocking. 222 For example, a non-blocking query command returns control to the 223 program immediately rather than stalling the program until the 224 results of the query are available. 225 226 When an asynchronous command is issued the current value of 227 ASYNC_MARKER_SGIX is associated with the particular invocation of 228 the command. This value is an integer called a "marker" which can 229 be used by the application to identify a particular command when 230 it completes as described later in this section. The value of 231 ASYNC_MARKER_SGIX is specified by calling AsyncMarkerSGIX with the 232 <marker> parameter set to the marker value. It is not an error to 233 invoke multiple asynchronous commands without changing 234 ASYNC_MARKER_SGIX, although such a situation may make it 235 impossible for the application to distinguish the completion 236 status of the commands. 237 238 OpenGL provides two commands for determining that 239 previously-issued asynchronous commands have completed: 240 FinishAsyncSGIX, which blocks until an asynchronous command 241 completes, and PollAsyncSGIX, which is non-blocking. Both 242 commands write the marker associated with the completed 243 asynchronous command into the integer referred to by the <markerp> 244 parameter. 245 246 FinishAsyncSGIX returns 1 when an asynchronous command has 247 completed. If there are pending asynchronous commands but none 248 have completed then FinishAsyncSGIX blocks until at least one 249 command completes. If there are no pending asynchronous commands 250 then FinishAsyncSGIX immediately returns 0 and does not modify the 251 integer referred to by <markerp>. 252 253 PollAsyncSGIX is identical to FinishAsyncSGIX except that if there 254 are no asynchronous commands that have completed then 255 PollAsyncSGIX immediately returns 0 rather than blocking. 256 257 Calls to FinishAsyncSGIX and PollAsyncSGIX may be freely 258 intermixed. Once OpenGL has reported the completion of an 259 asynchronous command via either FinishAsyncSGIX or PollAsyncSGIX 260 the completion status of the command will not be reported again. 261 If several commands have the same marker associated with them, the 262 completion status of each command will be reported separately, 263 although these reports will be indistinguishable. The order in 264 which asynchronous commands are reported is undefined by this 265 extension, although the extensions that define asynchronous 266 commands may guarantee a particular order. 267 268 A program may guarantee that all outstanding asynchronous commands 269 have completed by calling Finish. A call to Finish does not cause 270 the completion status of outstanding commands to be reported, so 271 subsequent calls to FinishAsyncSGIX or PollAsyncSGIX will report 272 the status of such commands. 273 274 Three commands are provided to manage asynchronous command 275 markers. A marker is "in use" if it is the current value of 276 ASYNC_MARKER_SGIX or if it is associated with any asynchronous 277 command that has been issued but has not been queried using 278 FinishAsyncSGIX or PollAsyncSGIX. A marker may also be "reserved" 279 by calling GenAsyncMarkersSGIX. GenAsyncMarkersSGIX returns an 280 integer n such that the markers n, n+1, n+2, ..., n+s-1 are not 281 previously reserved or in use, where s is the value of the <range> 282 parameter, or it returns 0 if no contiguous range of the specified 283 length could be reserved. The command also records that each of 284 the markers in the returned range is reserved. 285 286 DeleteAsyncMarkersSGIX records that each of the markers in the 287 range n, n+1, n+2, ..., n+s-1 is no longer reserved, where n is 288 the value of the <marker> parameter and s is the value of the 289 <range> parameter. It is not an error if some of the markers in 290 the range are not reserved or are currently in use, but a marker 291 that is in use will remain so even if DeleteAsyncMarkersSGIX is 292 called. IsAsyncMarkerSGIX returns 1 if the parameter <marker> 293 identifies a marker that is currently in use or reserved, and the 294 command returns 0 otherwise. 295 296 Note that the marker name space is never shared across contexts, 297 as the name spaces for texture objects and display lists may be. 298 299Additions to Chapter 6 of the 1.1 Specification (State and State Requests) 300 301 None 302 303Additions to the GLX Specification 304 305 Add to the end of Section 4.4 (Sequentiality): 306 307 Asynchronous OpenGL commands do not obey the normal sequentiality 308 guarantees for OpenGL commands. Any command issued asynchronously 309 may be inserted into the GLX protocol stream at any command 310 boundary following the command that was issued before it. 311 312GLX Protocol 313 314 XXX Not complete. Asynchronous commands should generate events 315 when they complete. The current GLX spec says that no new events 316 are defined, so this will have to be changed. 317 318Errors 319 320 INVALID_OPERATION is generated if AsyncMarkerSGIX, 321 FinishAsyncSGIX, PollAsyncSGIX, GenAsyncMarkersSGIX, 322 DeleteAsyncMarkersSGIX or IsAsyncMarkerSGIX is called between 323 execution of Begin and the corresponding execution of End. 324 325New State 326 327 Get Value Get Command Type Value Attrib 328 --------- ----------- ---- ------- ------ 329 ASYNC_MARKER_SGIX GetIntegerv Z+ 0 - 330 331New Implementation Dependent State 332 333 None 334