XXX - Not complete yet!!!
Name
SGIX_async
Name Strings
GL_SGIX_async
Version
$Date: 1998/06/04 20:57:36 $ $Revision: 1.8 $
Number
132
Dependencies
None.
Overview
This extension provides a framework for asynchronous OpenGL
commands. It also provides commands allowing a program to wait
for the completion of asynchronous commands.
Asynchronous commands have two properties:
1) Asynchronous commands are non-blocking. For example, an
asynchronous ReadPixels command returns control to the program
immediately rather than blocking until the command completes.
This property allows the program to issue other OpenGL commands in
parallel with the execution of commands that normally block.
2) Asynchronous commands may complete out-of-order with respect to
other OpenGL commands. For example, an asynchronous TexImage
command may complete after subsequent OpenGL commands issued by
the program rather than maintaining the normal serial order of the
OpenGL command stream. This property allows the graphics
accelerator to execute asynchronous commands in parallel with the
normal command stream, for instance using a secondary path to
transfer data from or to the host, without doing any dependency
checking.
Programs that issue asynchronous commands must also be able to
determine when the commands have completed. The completion status
may be needed so that results can be retrieved (e.g. the image
data from a ReadPixels command) or so that dependent commands can
be issued (e.g. drawing commands that use texture data downloaded
by an earlier asynchronous command). This extension provides
fine-grain control over asynchronous commands by introducing a
mechanism for determining the status of individual commands.
Each invocation of an asynchronous command is associated with an
integer called a "marker." A program specifies a marker before it
issues an asynchronous command. The program may later issue a
command to query if any asynchronous commands have completed. The
query commands return a marker to identify the command that
completed. This extension provides both blocking and non-blocking
query commands.
This extension does not define any asynchronous commands.
See SGIX_async_pixel for the asynchronous pixel commands.
Issues
* Should all asynchronous operations share the same marker name space?
Ans: Yes. The argument for separate name spaces is that it
makes modularizing an application easier. The proposal was to
use a separate name space for each category of commands,
e.g. readpixels, teximage, drawpixels, and histogram. That works
if each name space is used by only one part of the application
(e.g. one part of the application issues asynchronous readpixels
and some other part issues asynchronous teximage), but it
doesn't work if there are multiple uses of one name space
(e.g. two libraries that both use asynchronous readpixels). It
doesn't seem worth complicating the API to provide such a
limited benefit. The better solution is for a higher-level API
to provide a mechanism for registering an interest in particular
markers, similar to the X Windows mechanism for distributing
window events.
* Should the order of asynchronous operations be preserved, even
if they are executed out-of-order with respect to normal commands?
Ans: No, let the extensions that define the async operations choose
whether or not to preserve order.
* Should the extension also define a WaitAsyncSGIX command that
guarantees completion of a specified asynchronous command before
subsequent commands are executed? This command wouldn't require
the marker to make a round trip back to the host like
FinishAsyncSGIX does, so it could be implemented more efficiently.
Ans: No for now (no compelling application).
* When are errors associated with an asynchronous command
reported?
Ans: A call to GetError after an asynchronous command always
reports any errors associated with the command. The behavior
is as if errors are detected at the time a command is issued rather
than when it is executed. In this respect asynchronous commands
are no different from synchronous commands.
* Should a call to MakeCurrent implicitly force all pending
asynchronous commands to complete?
Ans: This is an implementation issue. It does not affect the
semantics of this extension.
* Should there be an implementation-dependent limit on the
number of outstanding asynchronous commands before the
application calls FinishAsync?
Ans: This extension does not impose such a limit, but the
extensions that introduce asynchronous commands must address the
issue. An asynchronous command that uses an application-allocated
buffer for return results (e.g. instruments) lets the application
determine the limit by sizing the buffer appropriately.
* Should this extension modify the instruments extension to use
the new PollAsyncSGIX command instead of PollInstrumentsSGIX?
Ans: No for now.
* Should there be a generic command to set the current marker
instead of a different mechanism for each asynchronous command?
Ans: Yes, this has been added (AsyncMarkerSGIX).
* Should there be a command to reserve a set of markers, like
GenLists?
Ans: Yes, this has been added (GenAsyncMarkers and
DeleteAsyncMarkers).
* Should name spaces be specified using enums instead of bitmasks?
Ans: Yes, but name spaces have now been removed (see above).
* Would it be better to define an extension that provides non-blocking
commands rather than asynchronous commands?
Ans: No. Non-blocking commands would require the GL to preserve
the order of commands, but that limits the potential for
optimization. The GL would have to check for dependencies
between a non-blocking command and all subsequent commands
(which is hard to do efficiently), or stall all subsequent
commands until the non-blocking command completes, or maintain
multiple sets of state. By defining an asynchronous style of
execution we place the burden of detecting dependencies on the
application. There is a large class of applications which can
easily guarantee that there are no dependencies.
New Procedures and Functions
void AsyncMarkerSGIX(uint marker)
int FinishAsyncSGIX(uint *markerp)
int PollAsyncSGIX(uint *markerp)
uint GenAsyncMarkersSGIX(sizei range)
void DeleteAsyncMarkersSGIX(uint marker, sizei range)
boolean IsAsyncMarkerSGIX(uint marker)
New Tokens
Accepted by the <pname> parameters of GetBooleanv, GetIntegerv,
GetFloatv, and GetDoublev:
ASYNC_MARKER_SGIX 0x8329
Additions to Chapter 2 of the 1.1 Specification (OpenGL Operation)
None
Additions to Chapter 3 of the 1.1 Specification (Rasterization)
None
Additions to Chapter 4 of the 1.1 Specification (Fragments and the
Frame Buffer)
None
Additions to Chapter 5 of the 1.1 Specification (Special Functions)
Add to section 5.4 (Display Lists):
The following commands are not included in display lists:
FinishAsyncSGIX
PollAsyncSGIX
GenAsyncMarkersSGIX
DeleteAsyncMarkersSGIX
IsAsyncMarkerSGIX
Add a section 5.X prior to the Instruments section entitled
"Asynchronous Commands":
Asynchronous commands are commands that may complete out-of-order
with respect to other OpenGL commands. An asynchronous command
samples the OpenGL state vector when it is issued. The sampled
state includes the results from the complete execution of all
synchronous (normal) commands issued prior to the asynchronous
command. However, the results of an asynchronous command (state
changes or framebuffer updates) are not necessarily committed in
order. An asynchronous command may commit its results any time
after the completion of all synchronous commands issued prior to
the asynchronous command. An implementation may choose to execute
asynchronous commands in parallel with subsequent commands or at
some convenient time in the future.
Implementations of asynchronous commands may also be non-blocking.
For example, a non-blocking query command returns control to the
program immediately rather than stalling the program until the
results of the query are available.
When an asynchronous command is issued the current value of
ASYNC_MARKER_SGIX is associated with the particular invocation of
the command. This value is an integer called a "marker" which can
be used by the application to identify a particular command when
it completes as described later in this section. The value of
ASYNC_MARKER_SGIX is specified by calling AsyncMarkerSGIX with the
<marker> parameter set to the marker value. It is not an error to
invoke multiple asynchronous commands without changing
ASYNC_MARKER_SGIX, although such a situation may make it
impossible for the application to distinguish the completion
status of the commands.
OpenGL provides two commands for determining that
previously-issued asynchronous commands have completed:
FinishAsyncSGIX, which blocks until an asynchronous command
completes, and PollAsyncSGIX, which is non-blocking. Both
commands write the marker associated with the completed
asynchronous command into the integer referred to by the <markerp>
parameter.
FinishAsyncSGIX returns 1 when an asynchronous command has
completed. If there are pending asynchronous commands but none
have completed then FinishAsyncSGIX blocks until at least one
command completes. If there are no pending asynchronous commands
then FinishAsyncSGIX immediately returns 0 and does not modify the
integer referred to by <markerp>.
PollAsyncSGIX is identical to FinishAsyncSGIX except that if there
are no asynchronous commands that have completed then
PollAsyncSGIX immediately returns 0 rather than blocking.
Calls to FinishAsyncSGIX and PollAsyncSGIX may be freely
intermixed. Once OpenGL has reported the completion of an
asynchronous command via either FinishAsyncSGIX or PollAsyncSGIX
the completion status of the command will not be reported again.
If several commands have the same marker associated with them, the
completion status of each command will be reported separately,
although these reports will be indistinguishable. The order in
which asynchronous commands are reported is undefined by this
extension, although the extensions that define asynchronous
commands may guarantee a particular order.
A program may guarantee that all outstanding asynchronous commands
have completed by calling Finish. A call to Finish does not cause
the completion status of outstanding commands to be reported, so
subsequent calls to FinishAsyncSGIX or PollAsyncSGIX will report
the status of such commands.
Three commands are provided to manage asynchronous command
markers. A marker is "in use" if it is the current value of
ASYNC_MARKER_SGIX or if it is associated with any asynchronous
command that has been issued but has not been queried using
FinishAsyncSGIX or PollAsyncSGIX. A marker may also be "reserved"
by calling GenAsyncMarkersSGIX. GenAsyncMarkersSGIX returns an
integer n such that the markers n, n+1, n+2, ..., n+s-1 are not
previously reserved or in use, where s is the value of the <range>
parameter, or it returns 0 if no contiguous range of the specified
length could be reserved. The command also records that each of
the markers in the returned range is reserved.
DeleteAsyncMarkersSGIX records that each of the markers in the
range n, n+1, n+2, ..., n+s-1 is no longer reserved, where n is
the value of the <marker> parameter and s is the value of the
<range> parameter. It is not an error if some of the markers in
the range are not reserved or are currently in use, but a marker
that is in use will remain so even if DeleteAsyncMarkersSGIX is
called. IsAsyncMarkerSGIX returns 1 if the parameter <marker>
identifies a marker that is currently in use or reserved, and the
command returns 0 otherwise.
Note that the marker name space is never shared across contexts,
as the name spaces for texture objects and display lists may be.
Additions to Chapter 6 of the 1.1 Specification (State and State Requests)
None
Additions to the GLX Specification
Add to the end of Section 4.4 (Sequentiality):
Asynchronous OpenGL commands do not obey the normal sequentiality
guarantees for OpenGL commands. Any command issued asynchronously
may be inserted into the GLX protocol stream at any command
boundary following the command that was issued before it.
GLX Protocol
XXX Not complete. Asynchronous commands should generate events
when they complete. The current GLX spec says that no new events
are defined, so this will have to be changed.
Errors
INVALID_OPERATION is generated if AsyncMarkerSGIX,
FinishAsyncSGIX, PollAsyncSGIX, GenAsyncMarkersSGIX,
DeleteAsyncMarkersSGIX or IsAsyncMarkerSGIX is called between
execution of Begin and the corresponding execution of End.
New State
Get Value Get Command Type Value Attrib
--------- ----------- ---- ------- ------
ASYNC_MARKER_SGIX GetIntegerv Z+ 0 -
New Implementation Dependent State
None