Back to the OpenGL extension cross reference

WGL_OML_sync_control


Name


    OML_sync_control

Name Strings


    WGL_OML_sync_control

Contact


    Randi Rost, 3Dlabs (rost 'at' 3dlabs.com)

Status


    Complete. Approved by the Khronos SIG on July 19, 2001.

Version


    Last Modified Date: 07/23/2001   Revision: 17.0

Number


    242

Dependencies


    The extension is written against the OpenGL 1.2.1 Specification
although it should work on any previous OpenGL specification.

WGL_ARB_extensions_string is required.

Overview


    This extension provides the control necessary to ensure
synchronization between events on the graphics card (such as
vertical retrace) and other parts of the system. It provides support
for applications with real-time rendering requirements by providing
precise synchronization between graphics and streaming video or
audio.

This extension incorporates the use of three counters that provide
the necessary synchronization. The Unadjusted System Time (or UST)
is a 64-bit monotonically increasing counter that is available
throughout the system. UST is not a resource that is controlled
by OpenGL, so it is not defined further as part of this extension.
The graphics Media Stream Counter (or graphics MSC) is a counter
that is unique to the graphics subsystem and increments for each
vertical retrace that occurs. The Swap Buffer Counter (SBC) is a
per-window value that is incremented each time a swap buffer
action is performed on the window.

The use of these three counters allows the application to
synchronize graphics rendering to vertical retraces and/or swap
buffer actions, and to synchronize other activities in the system
(such as streaming video or audio) to vertical retraces and/or
swap buffer actions.

Functions are provided to allow an application to detect when an
MSC or SBC has reached a certain value. This function will block
until the specified value has been reached. Applications that want
to continue other processing while waiting are expected to call
these blocking functions from a thread that is separate from the
main processing thread(s) of the application.

This extension carefully defines the observable order in which
things occur in order to allow implementations to perform
optimizations and avoid artifacts such as tearing, while at the
same time providing a framework for consistent behavior from the
point of view of an application.

Issues


    None.

IP Status


    No known issues.

New Procedures and Functions


    BOOL wglGetSyncValuesOML(HDC hdc, INT64 *ust, INT64 *msc, INT64 *sbc)

BOOL wglGetMscRateOML(HDC hdc, INT32 *numerator, INT32 *denominator)

INT64 wglSwapBuffersMscOML(HDC hdc, INT64 target_msc, INT64 divisor,
INT64 remainder)

INT64 wglSwapLayerBuffersMscOML(HDC hdc, INT fuPlanes, INT64 target_msc,
INT64 divisor, INT64 remainder)

BOOL wglWaitForMscOML(HDC hdc, INT64 target_msc, INT64 divisor,
INT64 remainder, INT64 *ust, INT64 *msc,
INT64 *sbc)

BOOL wglWaitForSbcOML(HDC hdc, INT64 target_sbc, INT64 *ust, INT64 *msc,
INT64 *sbc)

New Tokens


    None

Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation)


    None

Additions to Chapter 3 of the OpenGL 1.2.1 Specification (Rasterization)


    None

Additions to Chapter 4 of the OpenGL 1.2.1 Specification (Per-Fragment Operations and the Framebuffer)


    None

Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions)


    None

Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and State Requests)


    None

Additions to the WGL Specification


    wglGetSyncValuesOML returns the current UST/MSC/SBC triple. A UST
timestamp is obtained each time the graphics MSC is incremented.
If this value does not reflect the value of the UST at the time the
first scan line of the display begins passing through the video
output port, it will be adjusted by the graphics driver to do so
prior to being returned by any of the functions defined by this
extension.

This UST timestamp, together with the current graphics MSC and the
current SBC, comprise the current UST/MSC/SBC triple. The UST,
graphics MSC, and SBC values are not part of the render context
state. These values cannot be pushed or popped. The graphics MSC
value is initialized to 0 when the graphics device is initialized.
The SBC is per-window state and is initialized to 0 when the window
is initialized.

The SBC value is incremented by the graphics driver at the completion
of each buffer swap (e.g., the pixel copy has been completed or the
hardware register that swaps memory banks has been written). For pixel
formats that do not contain a back buffer, the SBC will always be
returned as 0.

The graphics MSC value is incremented once for each screen refresh.
For a non-interlaced display, this means that the graphics MSC value
is incremented for each frame. For an interlaced display, it means
that it will be incremented for each field. For a multi-monitor
system, the monitor used to determine MSC is the one Windows
associates with <hdc> (i.e., the primary monitor).

wglGetMscRateOML returns the rate at which the MSC will be incremented
for the display associated with <hdc>. The rate is expressed in Hertz
as <numerator> / <denominator>. If the MSC rate in Hertz is an
integer, then <denominator> will be 1 and <numerator> will be
the MSC rate.

wglSwapBuffersMscOML has the same functionality as SwapBuffers,
except for the following. The swap indicated by a call to
wglSwapBuffersMscOML does not perform an implicit glFlush. The
indicated swap will not occur until all prior rendering commands
affecting the buffer have been completed. Once prior rendering
commands have been completed, if the current MSC is less than
<target_msc>, the buffer swap will occur when the MSC value becomes
equal to <target_msc>. Once prior rendering commands have completed,
if the current MSC is greater than or equal to <target_msc>, the
buffer swap will occur the next time the MSC value is incremented
to a value such that MSC % <divisor> = <remainder>. If <divisor> = 0,
the swap will occur when MSC becomes greater than or equal to
<target_msc>.

Once wglSwapBuffersMscOML has been called, subsequent OpenGL commands
can be issued immediately. If the thread's current context is made
current to another drawable, or if the thread makes another context
current on another drawable, rendering can proceed immediately.

If there are multiple outstanding swaps for the same window, at most
one such swap can be satisfied per increment of MSC. The order of
satisfying outstanding swaps of a window must be the order they were
issued. Each window that has an outstanding swap satisfied by the same
current MSC should have one swap done.

If a thread issues a wglSwapBuffersMscOML call on a window, then
issues OpenGL commands while still current to this window (which now
has a pending wglSwapBuffersMscOML call), the commands will be executed
in the order they were received, subject to implementation resource
constraints. Furthermore, subsequent commands that would affect
the back buffer will only affect the new back buffer (that is, the
back buffer after the swap completes). Such commands do not affect
the current front buffer.

If the graphics driver utilizes an extra thread to perform the wait,
it is expected that this thread will have a high priority so that
the swap will occur at the earliest possible moment once all the
conditions for swapping have been satisfied.

wglSwapLayerBuffersMscOML works identically to wglSwapBuffersMscOML,
except that the specified layers of a window are swapped when the
buffer swap occurs, as defined in wglSwapLayerBuffers. The <planes>
parameter has the same definition as it has in the
wglSwapLayerBuffers function, and it indicates whether to swap
buffers for the overlay, underlay, or main planes of the window.

Both wglSwapBuffersMscOML and wglSwapLayerBuffersMscOML return the
value that will correspond to the value of the SBC when the buffer
swap actually occurs (in other words, the return value will be the
current value of the SBC + the number of pending buffer swaps + 1).
Both functions will return a value of -1 if the function failed
because of errors detected in the input parameters. Both functions
are no-ops if the current pixel format for <hdc> does not include
a back buffer.

wglWaitForMscOML can be used to cause the calling thread to wait
until a specific graphics MSC value has been reached. If the current
MSC is less than the <target_msc> parameter for wglWaitForMscOML,
wglWaitForMscOML will block until the MSC value becomes equal to
<target_msc> and then will return the current values for UST, MSC,
and SBC. Otherwise, the function will block until the MSC value is
incremented to a value such that MSC % <divisor> = <remainder> and
then will return the current values for UST, MSC, and SBC. If
<divisor> = 0, then the wait will return as soon as MSC >= <target_msc>.

wglWaitForSbcOML can be used to cause the calling thread to wait
until a specific SBC value has been reached. This function will block
until the SBC value for <hdc> becomes equal to <target_sbc> and then
will return the current values for UST, MSC, and SBC. If the SBC
value is already greater than or equal to <target_sbc>, the function
will return immediately with the current values for UST, MSC, and
SBC. If <target_sbc> = 0, the function will block until all previous
swaps requested with wglSwapBuffersMscOML or wglSwapLayerBuffersMscOML
for that window have completed. It will then return the current values
for UST, MSC, and SBC.

When wglSwapBuffersMscOML or wglSwapLayerBuffersMscOML has been
called to cause a swap at a particular MSC, an application process
would observe the following order of execution for that MSC:

1. The window for which a wglSwapBuffersMscOML call has been
issued has been completely scanned out to the display for
the previous MSC
2. The swap buffer action for that window begins
3. All the swap buffer actions for all the windows for the
application process are completed
4. SBC and MSC values are atomically incremented
5. Any calls to wglWaitForMscOML or wglWaitForSbcOML that
are satisfied by the new values for SBC and graphics
MSC are released

The functions wglGetSyncValuesOML, wglGetMscRateOML, wglWaitForMscOML,
and wglWaitForSbcOML will each return TRUE if the function completed
successfully, FALSE otherwise.

Dependencies on WGL_ARB_extensions_string


    Because there is no way to extend wgl, these calls are defined in
the ICD and can be called by obtaining the address with
wglGetProcAddress. Because this is not a GL extension, it is not
included in the GL_EXTENSIONS string. If this extension is supported
by the implementation, its name will be returned in the extension
string returned by wglGetExtensionString.

Errors


    To get extended error information, call GetLastError. Each of the
functions defined by this extension may generate the following error:

ERROR_DC_NOT_FOUND The <hDC> parameter was not valid.

The following error will be generated for the functions
wglSwapBuffersMscOML, wglSwapLayerBuffersMscOML, and
wglWaitForMscOML, if <divisor> is less than zero, or if <remainder>
is less than zero, or if <remainder> is greater than or equal to
a non-zero <divisor>, or if <target_msc> is less than zero; and
for the function wglWaitForSbcOML if <target_sbc> is less than zero:

ERROR_INVALID_DATA A parameter is incorrect.

New State


    Get Value		Get Command	   Type     Initial Value
--------- ----------- ---- -------------
[UST] wglGetSyncValuesOML Z unspecified
[MSC] wglGetSyncValuesOML Z 0
[SBC] wglGetSyncValuesOML Z 0

New Implementation Dependent State


    None








Implementation Support


   List of OpenGL implementations supporting the WGL_OML_sync_control extension

Original File


   Original text file for the WGL_OML_sync_control extension


Page generated on Sun Nov 20 18:40:39 2005