• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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