xref: /third_party/openGLES/extensions/OML/WGL_OML_sync_control.txt

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