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 (i.e., the primary monitor). wglGetMscRateOML returns the rate at which the MSC will be incremented for the display associated with . The rate is expressed in Hertz as / . If the MSC rate in Hertz is an integer, then will be 1 and 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 , the buffer swap will occur when the MSC value becomes equal to . Once prior rendering commands have completed, if the current MSC is greater than or equal to , the buffer swap will occur the next time the MSC value is incremented to a value such that MSC % = . If = 0, the swap will occur when MSC becomes greater than or equal to . 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 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 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 parameter for wglWaitForMscOML, wglWaitForMscOML will block until the MSC value becomes equal to 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 % = and then will return the current values for UST, MSC, and SBC. If = 0, then the wait will return as soon as 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 becomes equal to and then will return the current values for UST, MSC, and SBC. If the SBC value is already greater than or equal to , the function will return immediately with the current values for UST, MSC, and SBC. If = 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 parameter was not valid. The following error will be generated for the functions wglSwapBuffersMscOML, wglSwapLayerBuffersMscOML, and wglWaitForMscOML, if is less than zero, or if is less than zero, or if is greater than or equal to a non-zero , or if is less than zero; and for the function wglWaitForSbcOML if 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