1Name 2 3 OML_sync_control 4 5Name Strings 6 7 WGL_OML_sync_control 8 9Contact 10 11 Randi Rost, 3Dlabs (rost 'at' 3dlabs.com) 12 13Status 14 15 Complete. Approved by the Khronos SIG on July 19, 2001. 16 17Version 18 19 Last Modified Date: 07/23/2001 Revision: 17.0 20 21Number 22 23 242 24 25Dependencies 26 27 The extension is written against the OpenGL 1.2.1 Specification 28 although it should work on any previous OpenGL specification. 29 30 WGL_ARB_extensions_string is required. 31 32Overview 33 34 This extension provides the control necessary to ensure 35 synchronization between events on the graphics card (such as 36 vertical retrace) and other parts of the system. It provides support 37 for applications with real-time rendering requirements by providing 38 precise synchronization between graphics and streaming video or 39 audio. 40 41 This extension incorporates the use of three counters that provide 42 the necessary synchronization. The Unadjusted System Time (or UST) 43 is a 64-bit monotonically increasing counter that is available 44 throughout the system. UST is not a resource that is controlled 45 by OpenGL, so it is not defined further as part of this extension. 46 The graphics Media Stream Counter (or graphics MSC) is a counter 47 that is unique to the graphics subsystem and increments for each 48 vertical retrace that occurs. The Swap Buffer Counter (SBC) is a 49 per-window value that is incremented each time a swap buffer 50 action is performed on the window. 51 52 The use of these three counters allows the application to 53 synchronize graphics rendering to vertical retraces and/or swap 54 buffer actions, and to synchronize other activities in the system 55 (such as streaming video or audio) to vertical retraces and/or 56 swap buffer actions. 57 58 Functions are provided to allow an application to detect when an 59 MSC or SBC has reached a certain value. This function will block 60 until the specified value has been reached. Applications that want 61 to continue other processing while waiting are expected to call 62 these blocking functions from a thread that is separate from the 63 main processing thread(s) of the application. 64 65 This extension carefully defines the observable order in which 66 things occur in order to allow implementations to perform 67 optimizations and avoid artifacts such as tearing, while at the 68 same time providing a framework for consistent behavior from the 69 point of view of an application. 70 71Issues 72 73 None. 74 75IP Status 76 77 No known issues. 78 79New Procedures and Functions 80 81 BOOL wglGetSyncValuesOML(HDC hdc, INT64 *ust, INT64 *msc, INT64 *sbc) 82 83 BOOL wglGetMscRateOML(HDC hdc, INT32 *numerator, INT32 *denominator) 84 85 INT64 wglSwapBuffersMscOML(HDC hdc, INT64 target_msc, INT64 divisor, 86 INT64 remainder) 87 88 INT64 wglSwapLayerBuffersMscOML(HDC hdc, INT fuPlanes, INT64 target_msc, 89 INT64 divisor, INT64 remainder) 90 91 BOOL wglWaitForMscOML(HDC hdc, INT64 target_msc, INT64 divisor, 92 INT64 remainder, INT64 *ust, INT64 *msc, 93 INT64 *sbc) 94 95 BOOL wglWaitForSbcOML(HDC hdc, INT64 target_sbc, INT64 *ust, INT64 *msc, 96 INT64 *sbc) 97 98New Tokens 99 100 None 101 102Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation) 103 104 None 105 106Additions to Chapter 3 of the OpenGL 1.2.1 Specification (Rasterization) 107 108 None 109 110Additions to Chapter 4 of the OpenGL 1.2.1 Specification (Per-Fragment 111Operations and the Framebuffer) 112 113 None 114 115Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) 116 117 None 118 119Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and 120State Requests) 121 122 None 123 124Additions to the WGL Specification 125 126 wglGetSyncValuesOML returns the current UST/MSC/SBC triple. A UST 127 timestamp is obtained each time the graphics MSC is incremented. 128 If this value does not reflect the value of the UST at the time the 129 first scan line of the display begins passing through the video 130 output port, it will be adjusted by the graphics driver to do so 131 prior to being returned by any of the functions defined by this 132 extension. 133 134 This UST timestamp, together with the current graphics MSC and the 135 current SBC, comprise the current UST/MSC/SBC triple. The UST, 136 graphics MSC, and SBC values are not part of the render context 137 state. These values cannot be pushed or popped. The graphics MSC 138 value is initialized to 0 when the graphics device is initialized. 139 The SBC is per-window state and is initialized to 0 when the window 140 is initialized. 141 142 The SBC value is incremented by the graphics driver at the completion 143 of each buffer swap (e.g., the pixel copy has been completed or the 144 hardware register that swaps memory banks has been written). For pixel 145 formats that do not contain a back buffer, the SBC will always be 146 returned as 0. 147 148 The graphics MSC value is incremented once for each screen refresh. 149 For a non-interlaced display, this means that the graphics MSC value 150 is incremented for each frame. For an interlaced display, it means 151 that it will be incremented for each field. For a multi-monitor 152 system, the monitor used to determine MSC is the one Windows 153 associates with <hdc> (i.e., the primary monitor). 154 155 wglGetMscRateOML returns the rate at which the MSC will be incremented 156 for the display associated with <hdc>. The rate is expressed in Hertz 157 as <numerator> / <denominator>. If the MSC rate in Hertz is an 158 integer, then <denominator> will be 1 and <numerator> will be 159 the MSC rate. 160 161 wglSwapBuffersMscOML has the same functionality as SwapBuffers, 162 except for the following. The swap indicated by a call to 163 wglSwapBuffersMscOML does not perform an implicit glFlush. The 164 indicated swap will not occur until all prior rendering commands 165 affecting the buffer have been completed. Once prior rendering 166 commands have been completed, if the current MSC is less than 167 <target_msc>, the buffer swap will occur when the MSC value becomes 168 equal to <target_msc>. Once prior rendering commands have completed, 169 if the current MSC is greater than or equal to <target_msc>, the 170 buffer swap will occur the next time the MSC value is incremented 171 to a value such that MSC % <divisor> = <remainder>. If <divisor> = 0, 172 the swap will occur when MSC becomes greater than or equal to 173 <target_msc>. 174 175 Once wglSwapBuffersMscOML has been called, subsequent OpenGL commands 176 can be issued immediately. If the thread's current context is made 177 current to another drawable, or if the thread makes another context 178 current on another drawable, rendering can proceed immediately. 179 180 If there are multiple outstanding swaps for the same window, at most 181 one such swap can be satisfied per increment of MSC. The order of 182 satisfying outstanding swaps of a window must be the order they were 183 issued. Each window that has an outstanding swap satisfied by the same 184 current MSC should have one swap done. 185 186 If a thread issues a wglSwapBuffersMscOML call on a window, then 187 issues OpenGL commands while still current to this window (which now 188 has a pending wglSwapBuffersMscOML call), the commands will be executed 189 in the order they were received, subject to implementation resource 190 constraints. Furthermore, subsequent commands that would affect 191 the back buffer will only affect the new back buffer (that is, the 192 back buffer after the swap completes). Such commands do not affect 193 the current front buffer. 194 195 If the graphics driver utilizes an extra thread to perform the wait, 196 it is expected that this thread will have a high priority so that 197 the swap will occur at the earliest possible moment once all the 198 conditions for swapping have been satisfied. 199 200 wglSwapLayerBuffersMscOML works identically to wglSwapBuffersMscOML, 201 except that the specified layers of a window are swapped when the 202 buffer swap occurs, as defined in wglSwapLayerBuffers. The <planes> 203 parameter has the same definition as it has in the 204 wglSwapLayerBuffers function, and it indicates whether to swap 205 buffers for the overlay, underlay, or main planes of the window. 206 207 Both wglSwapBuffersMscOML and wglSwapLayerBuffersMscOML return the 208 value that will correspond to the value of the SBC when the buffer 209 swap actually occurs (in other words, the return value will be the 210 current value of the SBC + the number of pending buffer swaps + 1). 211 Both functions will return a value of -1 if the function failed 212 because of errors detected in the input parameters. Both functions 213 are no-ops if the current pixel format for <hdc> does not include 214 a back buffer. 215 216 wglWaitForMscOML can be used to cause the calling thread to wait 217 until a specific graphics MSC value has been reached. If the current 218 MSC is less than the <target_msc> parameter for wglWaitForMscOML, 219 wglWaitForMscOML will block until the MSC value becomes equal to 220 <target_msc> and then will return the current values for UST, MSC, 221 and SBC. Otherwise, the function will block until the MSC value is 222 incremented to a value such that MSC % <divisor> = <remainder> and 223 then will return the current values for UST, MSC, and SBC. If 224 <divisor> = 0, then the wait will return as soon as MSC >= <target_msc>. 225 226 wglWaitForSbcOML can be used to cause the calling thread to wait 227 until a specific SBC value has been reached. This function will block 228 until the SBC value for <hdc> becomes equal to <target_sbc> and then 229 will return the current values for UST, MSC, and SBC. If the SBC 230 value is already greater than or equal to <target_sbc>, the function 231 will return immediately with the current values for UST, MSC, and 232 SBC. If <target_sbc> = 0, the function will block until all previous 233 swaps requested with wglSwapBuffersMscOML or wglSwapLayerBuffersMscOML 234 for that window have completed. It will then return the current values 235 for UST, MSC, and SBC. 236 237 When wglSwapBuffersMscOML or wglSwapLayerBuffersMscOML has been 238 called to cause a swap at a particular MSC, an application process 239 would observe the following order of execution for that MSC: 240 241 1. The window for which a wglSwapBuffersMscOML call has been 242 issued has been completely scanned out to the display for 243 the previous MSC 244 2. The swap buffer action for that window begins 245 3. All the swap buffer actions for all the windows for the 246 application process are completed 247 4. SBC and MSC values are atomically incremented 248 5. Any calls to wglWaitForMscOML or wglWaitForSbcOML that 249 are satisfied by the new values for SBC and graphics 250 MSC are released 251 252 The functions wglGetSyncValuesOML, wglGetMscRateOML, wglWaitForMscOML, 253 and wglWaitForSbcOML will each return TRUE if the function completed 254 successfully, FALSE otherwise. 255 256Dependencies on WGL_ARB_extensions_string 257 258 Because there is no way to extend wgl, these calls are defined in 259 the ICD and can be called by obtaining the address with 260 wglGetProcAddress. Because this is not a GL extension, it is not 261 included in the GL_EXTENSIONS string. If this extension is supported 262 by the implementation, its name will be returned in the extension 263 string returned by wglGetExtensionString. 264 265Errors 266 267 To get extended error information, call GetLastError. Each of the 268 functions defined by this extension may generate the following error: 269 270 ERROR_DC_NOT_FOUND The <hDC> parameter was not valid. 271 272 The following error will be generated for the functions 273 wglSwapBuffersMscOML, wglSwapLayerBuffersMscOML, and 274 wglWaitForMscOML, if <divisor> is less than zero, or if <remainder> 275 is less than zero, or if <remainder> is greater than or equal to 276 a non-zero <divisor>, or if <target_msc> is less than zero; and 277 for the function wglWaitForSbcOML if <target_sbc> is less than zero: 278 279 ERROR_INVALID_DATA A parameter is incorrect. 280 281New State 282 283 Get Value Get Command Type Initial Value 284 --------- ----------- ---- ------------- 285 [UST] wglGetSyncValuesOML Z unspecified 286 [MSC] wglGetSyncValuesOML Z 0 287 [SBC] wglGetSyncValuesOML Z 0 288 289New Implementation Dependent State 290 291 None 292 293 294 295 296 297 298 299 300