specs/synclib.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3                    "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
   4 [
   5 <!ENTITY % defs SYSTEM "defs.ent"> %defs;
   6 ]>
   7
   8
   9 <!-- lifted from troff+ms+XMan by doclifter -->
  10 <book id="synclib">
  11
  12 <bookinfo>
  13    <title>X Synchronization Extension Library</title>
  14    <subtitle>X Consortium Standard</subtitle>
  15    <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo>
  16    <releaseinfo>Version 3.0</releaseinfo>
  17    <authorgroup>
  18       <author>
  19         <firstname>Tim</firstname><surname>Glauert</surname>
  20         <affiliation>
  21           <orgname>Olivetti Research</orgname>
  22           <orgdiv>MultiWorks</orgdiv>
  23         </affiliation>
  24       </author>
  25       <author>
  26           <firstname>Dave</firstname>
  27           <surname>Carver</surname>
  28           <affiliation>
  29             <orgname>Digital Equipment Corporation</orgname>
  30             <orgdiv>MIT/Project Athena</orgdiv>
  31           </affiliation>
  32       </author>
  33       <author>
  34         <firstname>Jim</firstname>
  35         <surname>Gettys</surname>
  36         <affiliation>
  37           <orgname>Digital Equipment Corporation</orgname>
  38           <orgdiv>Cambridge Research Laboratory</orgdiv>
  39         </affiliation>
  40       </author>
  41       <author>
  42         <firstname>David</firstname>
  43         <othername>P.</othername>
  44         <surname>Wiggins</surname>
  45         <affiliation><orgname>X Consortium, Inc.</orgname></affiliation>
  46       </author>
  47    </authorgroup>
  48    <copyright><year>1991</year>
  49      <holder>Olivetti Research Limited, Cambridge England</holder>
  50      <holder>Digital Equipment Corporation, Maynard, Massachusetts</holder>
  51    </copyright>
  52
  53 <legalnotice>
  54 <para>
  55 Permission to use, copy, modify, and distribute this documentation for any
  56 purpose and without fee is hereby granted, provided that the above
  57 copyright notice appear in all copies. Olivetti, Digital, MIT, and the
  58 X Consortium make no representations about the suitability for any purpose
  59 of the information in this document. This documentation is provided as
  60 is without express or implied warranty.
  61 </para>
  62 </legalnotice>
  63
  64 <legalnotice>
  65 <para role="multiLicensing">Copyright &copy; 1991 X Consortium, Inc.</para>
  66 <para>
  67 Permission is hereby granted, free of charge, to any person obtaining
  68 a copy of this software and associated documentation files
  69 (the "Software"), to deal in the Software without
  70 restriction, including without limitation the rights to use, copy,
  71 modify, merge, publish, distribute, sublicense, and/or sell copies of
  72 the Software, and to permit persons to whom the Software is furnished
  73 to do so, subject to the following conditions:
  74 </para>
  75
  76 <para>
  77 The above copyright notice and this permission notice shall be included in
  78 all copies or substantial portions of the Software.
  79 </para>
  80
  81 <para>THE SOFTWARE IS PROVIDED &ldquo;AS IS&rdquo;, WITHOUT WARRANTY OF ANY KIND,
  82 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  83 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  84 IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
  85 OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  86 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  87 OTHER DEALINGS IN THE SOFTWARE.
  88 </para>
  89
  90 <para>
  91 Except as contained in this notice, the name of the X Consortium shall
  92 not be used in advertising or otherwise to promote the sale, use or other
  93 dealings in this Software without prior written authorization from the
  94 X Consortium.
  95 </para>
  96 <para>X Window System is a trademark of The OpenGroup.</para>
  97
  98 </legalnotice>
  99 </bookinfo>
 100
 101 <chapter id="synchronization_protocol">
 102 <title>Synchronization Protocol</title>
 103
 104 <para>
 105 The core X protocol makes no guarantees about the relative order of
 106 execution of requests for different clients.  This means that any
 107 synchronization between clients must be done at the client level in an
 108 operating system-dependent and network-dependent manner. Even if there
 109 was an accepted standard for such synchronization, the use of a network
 110 introduces unpredictable delays between the synchronization of the clients and
 111 the delivery of the resulting requests to the X server.
 112 </para>
 113 <para>
 114 The core X protocol also makes no guarantees about the time at which
 115 requests are executed, which means that all clients with real-time constraints
 116 must implement their timing on the host computer. Any such timings are
 117 subject to error introduced by delays within the operating system and
 118 network and are ineﬃcient because of the need for round-trip requests that
 119 keep the client and server synchronized.
 120 </para>
 121 <para>
 122 The synchronization extension provides primitives that allow synchronization
 123 between clients to take place entirely within the X server. This removes any
 124 error introduced by the network and makes it possible to synchronize clients
 125 on different hosts running different operating systems. This is important for
 126 multimedia applications, where audio, video, and graphics data streams are
 127 being synchronized. The extension also provides internal timers within the X
 128 server to which client requests can be synchronized. This allows simple
 129 animation applications to be implemented without any round-trip requests
 130 and makes best use of buffering within the client, network, and server.
 131 </para>
 132
 133 <sect1 id="description">
 134 <title>Description</title>
 135 <para>
 136 The mechanism used by this extension for synchronization within the X server
 137 is to block the processing of requests from a client until a specific
 138 synchronization condition occurs. When the condition occurs, the client is
 139 released and processing of requests continues. Multiple clients may block on
 140 the same condition to give inter-client synchronization. Alternatively, a single
 141 client may block on a condition such as an animation frame marker.
 142 </para>
 143 <para>
 144 The extension adds <function>Counter</function> and
 145 <function>Alarm</function> to the set of resources managed by
 146 the server. A counter has a 64-bit integer value that may be increased or
 147 decreased by client requests or by the server internally. A client can
 148 block by sending an <function>Await</function> request that waits until
 149 one of a set of synchronization conditions, called TRIGGERs, becomes TRUE.
 150 </para>
 151 <para>
 152 The <function>CreateCounter</function> request allows a client to create
 153 a <function>Counter</function> that can be changed by explicit
 154 <function>SetCounter</function> and <function>ChangeCounter</function>
 155 requests. These can be used to implement synchronization between
 156 different clients.
 157 </para>
 158 <para>
 159 There are some counters, called <function>System Counters</function>,
 160 that are changed by the server internally rather than by client
 161 requests. The effect of any change to a system counter is not visible
 162 until the server has finished processing the current request. In other
 163 words, system counters are apparently updated in the gaps between the
 164 execution of requests rather than during the actual execution of a
 165 request. The extension provides a system counter that advances with the
 166 server time as defined by the core protocol, and it may also provide
 167 counters that advance with the real-world time or that change each
 168 time the CRT screen is refreshed. Other extensions may provide their own
 169 extension-specific system counters.
 170 </para>
 171 <para>
 172 The extension provides an <function>Alarm</function> mechanism that allows clients to receive an
 173 event on a regular basis when a particular counter is changed.
 174 </para>
 175 </sect1>
 176 </chapter>
 177
 178 <chapter id="c_language_binding">
 179 <title>C Language Binding</title>
 180
 181 <para>
 182 The C routines provide direct access to the protocol and add no additional
 183 semantics.
 184 </para>
 185 <para>
 186 The include file for this extension is &lt;X11/extensions/sync.h&gt;.
 187 Most of the names in the language binding are derived from the protocol
 188 names by prepending XSync to the protocol name and changing the
 189 capitalization.
 190 </para>
 191
 192 <sect1 id="c_functions">
 193 <title>C Functions</title>
 194
 195 <para>
 196 Most of the following functions generate SYNC protocol requests.
 197 </para>
 198
 199 <funcsynopsis id='xsyncqueryextension'>
 200 <funcprototype>
 201   <funcdef>Status <function>XSyncQueryExtension</function></funcdef>
 202     <paramdef>Display <parameter> *dpy</parameter></paramdef>
 203     <paramdef>int <parameter> *event_base_return</parameter></paramdef>
 204     <paramdef>int <parameter> *error_base_return</parameter></paramdef>
 205 </funcprototype>
 206 </funcsynopsis>
 207
 208 <para>
 209 If dpy supports the SYNC extension,
 210 <function>XSyncQueryExtension</function> returns True,
 211 sets *event_base_return to the event number for the first SYNC event, and
 212 sets *error_base_return to the error number for the first SYNC error. If dpy
 213 does not support the SYNC extension, it returns False.
 214 </para>
 215
 216 <funcsynopsis id='xsyncinitialize'>
 217 <funcprototype>
 218   <funcdef>Status <function>XSyncInitialize</function></funcdef>
 219     <paramdef>Display <parameter> *dpy</parameter></paramdef>
 220     <paramdef>int <parameter> *major_version_return</parameter></paramdef>
 221     <paramdef>int <parameter> *minor_version_return</parameter></paramdef>
 222 </funcprototype>
 223 </funcsynopsis>
 224
 225 <para>
 226 <function>XSyncInitialize</function> sets *major_version_return and
 227 *minor version return to the major/minor SYNC protocol version supported
 228 by the server. If the XSync library is compatible with the version
 229 returned by the server, this function returns <function>True</function>.
 230 If dpy does not support the SYNC extension, or if there was an error
 231 during communication with the server, or if the server and library protocol
 232 versions are incompatible, this function returns <function>False</function>.
 233 The only XSync function that may be called before this function is
 234 XSyncQueryExtension. If a client violates this rule, the effects of all XSync
 235 calls that it makes are undefined.
 236 </para>
 237
 238 <funcsynopsis id='xsynclistsystemcounters'>
 239 <funcprototype>
 240   <funcdef>XSyncSystemCounter *<function>XSyncListSystemCounters</function></funcdef>
 241     <paramdef>Display <parameter> *dpy</parameter></paramdef>
 242     <paramdef>int <parameter> *n_counters_return</parameter></paramdef>
 243 </funcprototype>
 244 </funcsynopsis>
 245
 246 <para>
 247 <function>XSyncListSystemCounters</function> returns a pointer to an array
 248 of system counters supported by the display and sets *n_counters_return
 249 to the number of counters in the array.  The array should be freed with
 250 <function>XSyncFreeSystemCounterList</function>. If dpy does not support
 251 the SYNC extension, or if there was an error during communication with
 252 the server, or if the server does not support any system counters,
 253 this function returns NULL.
 254 </para>
 255
 256 <para>
 257 XSyncSystemCounter has the following fields:
 258 </para>
 259
 260 <literallayout remap='Ds'>
 261 char *              name;        /* null-terminated name of system counter */
 262 XSyncCounter        counter;     /* counter id of this system counter */
 263 XSyncValue          resolution;  /* resolution of this system counter */
 264 </literallayout>
 265
 266 <funcsynopsis id='xsyncfreesystemcounterlist'>
 267 <funcprototype>
 268   <funcdef>void <function>XSyncFreeSystemCounterList</function></funcdef>
 269     <paramdef>XSyncSystemCounter <parameter> *list</parameter></paramdef>
 270 </funcprototype>
 271 </funcsynopsis>
 272
 273 <para>
 274 <function>XSyncFreeSystemCounterList</function> frees the memory
 275 associated with the system counter list returned by
 276 <function>XSyncListSystemCounters</function>.
 277 </para>
 278
 279 <funcsynopsis id='xsynccreatecounter'>
 280 <funcprototype>
 281   <funcdef>XSyncCounter <function>XSyncCreateCounter</function></funcdef>
 282     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 283     <paramdef>XSyncValue<parameter> initial_value</parameter></paramdef>
 284 </funcprototype>
 285 </funcsynopsis>
 286
 287 <para>
 288 <function>XSyncCreateCounter</function> creates a counter on the dpy
 289 with the given initial value and returns the counter ID. It returns
 290 <function>None</function> if dpy does not support the SYNC extension.
 291 </para>
 292
 293 <funcsynopsis id='xsyncsetcounter'>
 294 <funcprototype>
 295   <funcdef>Status <function>XSyncSetCounter</function></funcdef>
 296     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 297     <paramdef>XSyncCounter<parameter> counter</parameter></paramdef>
 298     <paramdef>XSyncValue<parameter> value</parameter></paramdef>
 299 </funcprototype>
 300 </funcsynopsis>
 301
 302
 303 <para>
 304 <function>XSyncSetCounter</function> sets counter to value. It returns
 305 <function>False </function> if dpy does not
 306 support the SYNC extension; otherwise, it returns <function>True</function>.
 307 </para>
 308
 309 <funcsynopsis id='xsyncchangecounter'>
 310 <funcprototype>
 311   <funcdef>Status <function>XSyncChangeCounter</function></funcdef>
 312     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 313     <paramdef>XSyncCounter<parameter> counter</parameter></paramdef>
 314     <paramdef>XSyncValue<parameter> value</parameter></paramdef>
 315 </funcprototype>
 316 </funcsynopsis>
 317
 318 <para>
 319 <function>XSyncChangeCounter</function> adds value to counter. It returns
 320 <function>False</function> if dpy does not support the SYNC extension;
 321 otherwise, it returns
 322 <function>True</function>.
 323 </para>
 324 <funcsynopsis id='xsyncdestroycounter'>
 325 <funcprototype>
 326   <funcdef>Status <function>XSyncDestroyCounter</function></funcdef>
 327     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 328     <paramdef>XSyncCounter<parameter> counter</parameter></paramdef>
 329 </funcprototype>
 330 </funcsynopsis>
 331
 332 <para>
 333 <function>XSyncDestroyCounter</function> destroys counter. It returns
 334 <function>False</function> if dpy does not support the SYNC extension;
 335 otherwise, it returns <function>True</function>.
 336 </para>
 337
 338 <funcsynopsis id='xsyncquerycounter'>
 339 <funcprototype>
 340   <funcdef>Status <function>XSyncQueryCounter</function></funcdef>
 341     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 342     <paramdef>XSyncCounter<parameter> counter</parameter></paramdef>
 343     <paramdef>XSyncValue<parameter> *value_return</parameter></paramdef>
 344 </funcprototype>
 345 </funcsynopsis>
 346
 347 <para>
 348 <function>XSyncQueryCounter</function> sets *value_return to the current
 349 value of counter. It returns <function>False</function> if there was an
 350 error during communication with the server or if dpy does not support the
 351 SYNC extension; otherwise, it returns <function>True</function>.
 352 </para>
 353
 354 <funcsynopsis id='xsyncawait'>
 355 <funcprototype>
 356   <funcdef>Status <function>XSyncAwait</function></funcdef>
 357     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 358     <paramdef>XSyncWaitCondition<parameter> *wait_list</parameter></paramdef>
 359     <paramdef>int<parameter> n_conditions</parameter></paramdef>
 360 </funcprototype>
 361 </funcsynopsis>
 362
 363 <para>
 364 <function>XSyncAwait</function> awaits on the conditions in wait_list.
 365 The n_conditions is the number of wait conditions in wait_list. It
 366 returns <function>False</function> if dpy does not support the SYNC
 367 extension; otherwise, it returns <function>True</function>. The await is
 368 processed asynchronously by the server; this function always returns
 369 immediately after issuing the request.
 370 </para>
 371 <para>
 372 XSyncWaitCondition has the following fields:
 373 </para>
 374
 375 <literallayout remap='Ds'>
 376 XSyncCounter     trigger.counter;    /*counter to trigger on */
 377 XSyncValueType   trigger.value_type; /*absolute/relative */
 378 XSyncValue       trigger.wait_value; /*value to compare counter to */
 379 XSyncTestType    trigger.test_type;  /*pos/neg comparison/transtion */
 380 XSyncValue       event_threshold;    /*send event if past threshold */
 381 </literallayout>
 382
 383 <para>
 384 <function>XSyncValueType</function> can be either
 385 <function>XSyncAbsolute</function> or <function>XSyncRelative</function>.
 386 </para>
 387
 388 <para>
 389 <function>XSyncTestType</function> can be one of
 390 <function>XSyncPositiveTransition</function>,
 391 <function>XSyncNegativeTransition</function>,
 392 <function>XSyncPositiveComparison</function>, or
 393 <function>XSyncNegativeComparison</function>.
 394 </para>
 395
 396 <funcsynopsis id='xsynccreatealarm'>
 397 <funcprototype>
 398   <funcdef>XSyncAlarm <function>XSyncCreateAlarm</function></funcdef>
 399     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 400     <paramdef>unsigned long<parameter> values_mask</parameter></paramdef>
 401     <paramdef>XSyncAlarmAttributes<parameter> *values`</parameter></paramdef>
 402 </funcprototype>
 403 </funcsynopsis>
 404
 405 <para>
 406 <function>XSyncCreateAlarm</function> creates an alarm and returns the
 407 alarm ID. It returns None if the display does not support the SYNC
 408 extension. The values_mask and values specify the alarm attributes.
 409 </para>
 410
 411 <para>
 412 <function>XSyncAlarmAttributes</function> has the following fields. The
 413 attribute_mask column specifies the symbol that the caller should OR
 414 into values_mask to indicate that the value for the corresponding
 415 attribute was actually supplied. Default values are used for all
 416 attributes that do not have their attribute_mask OR’ed into values_mask.
 417 See the protocol description for <function>CreateAlarm</function> for the
 418 defaults.
 419 </para>
 420
 421 <literallayout remap='Ds'>
 422 type                 field name           attribute_mask
 423 XSyncCounter       trigger.counter;     XSyncCACounter
 424 XSyncValueType     trigger.value_type;  XSyncCAValueType
 425 XSyncValue         trigger.wait_value;  XSyncCAValue
 426 XSyncTestType      trigger.test_type;   XSyncCATestType
 427 XSyncValue         delta;               XSyncCADelta
 428 Bool               events;              XSyncCAEvents
 429 XSyncAlarmState    state;               client cannot set this
 430 </literallayout>
 431
 432 <funcsynopsis id='xsyncdestroyalarm'>
 433 <funcprototype>
 434   <funcdef>Status <function>XSyncDestroyAlarm</function></funcdef>
 435     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 436     <paramdef>XSyncAlarm<parameter> alarm</parameter></paramdef>
 437 </funcprototype>
 438 </funcsynopsis>
 439
 440 <para>
 441 <function>XSyncDestroyAlarm</function> destroys alarm. It returns
 442 <function>False</function> if dpy does not support
 443 the SYNC extension; otherwise, it returns <function>True</function>.
 444 </para>
 445
 446 <funcsynopsis id='xsyncqueryalarm'>
 447 <funcprototype>
 448   <funcdef>Status <function>XSyncQueryAlarm</function></funcdef>
 449     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 450     <paramdef>XSyncAlarm<parameter> alarm</parameter></paramdef>
 451     <paramdef>XSyncAlarmAttributes<parameter> *values_return</parameter></paramdef>
 452 </funcprototype>
 453 </funcsynopsis>
 454
 455
 456 <para>
 457 <function>XSyncQueryAlarm</function> sets *values_return to the alarm’s
 458 attributes. It returns <function>False</function> if there was an error
 459 during communication with the server or if dpy does not support the
 460 SYNC extension; otherwise, it returns <function>True</function>.
 461 </para>
 462
 463 <funcsynopsis id='xsyncchangealarm'>
 464 <funcprototype>
 465   <funcdef>Status <function>XSyncChangeAlarm</function></funcdef>
 466     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 467     <paramdef>XSyncAlarm<parameter> alarm</parameter></paramdef>
 468     <paramdef>unsigned long<parameter> values_mask</parameter></paramdef>
 469     <paramdef>XSyncAlarmAttributes<parameter> *values</parameter></paramdef>
 470 </funcprototype>
 471 </funcsynopsis>
 472
 473 <para>
 474 <function>XSyncChangeAlarm</function> changes alarm’s attributes. The
 475 attributes to change are specified as in
 476 <function>XSyncCreateAlarm</function>. It returns
 477 <function>False</function> if dpy does not support
 478 the SYNC extension; otherwise, it returns <function>True</function>.
 479 </para>
 480
 481 <funcsynopsis id='xsyncsetpriority'>
 482 <funcprototype>
 483   <funcdef>Status <function>XSyncSetPriority</function></funcdef>
 484     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 485     <paramdef>XID<parameter> client_resource_id</parameter></paramdef>
 486     <paramdef>int<parameter> priority</parameter></paramdef>
 487 </funcprototype>
 488 </funcsynopsis>
 489
 490 <para>
 491 <function>XSyncSetPriority</function> sets the priority of the client
 492 owning client_resource_id to priority. If client_resource_id is None, it
 493 sets the caller’s priority. It returns
 494 <function>False</function> if dpy does not support the SYNC extension;
 495 otherwise, it returns <function>True</function>.
 496 </para>
 497
 498 <funcsynopsis id='xsyncgetpriority'>
 499 <funcprototype>
 500   <funcdef>Status <function>XSyncGetPriority</function></funcdef>
 501     <paramdef>Display<parameter> *dpy</parameter></paramdef>
 502     <paramdef>XID<parameter> client_resource_id</parameter></paramdef>
 503     <paramdef>int<parameter> *return_priority</parameter></paramdef>
 504 </funcprototype>
 505 </funcsynopsis>
 506
 507 <para>
 508 <function>XSyncGetPriority</function> sets *return_priority to the
 509 priority of the client owning client_resource_id. If client_resource_id
 510 is None, it sets *return_priority to the caller’s priority. It returns
 511 <function>False</function> if there was an error during communication
 512 with the server or if dpy does not support the SYNC extension; otherwise, it
 513 returns <function>True</function>.
 514 </para>
 515
 516 </sect1>
 517
 518 <sect1 id="c_macros_functions">
 519 <title>C Macros/Functions</title>
 520
 521 <para>
 522 The following procedures manipulate 64-bit values. They are defined both as
 523 macros and as functions. By default, the macro form is used. To use the
 524 function form, #undef the macro name to uncover the function.
 525 </para>
 526
 527 <funcsynopsis id='xsyncinttovalue'>
 528 <funcprototype>
 529   <funcdef>void <function>XSyncIntToValue</function></funcdef>
 530     <paramdef>XSyncValue<parameter> *pv</parameter></paramdef>
 531     <paramdef>int<parameter> i</parameter></paramdef>
 532 </funcprototype>
 533 </funcsynopsis>
 534
 535 <para>
 536 Converts i to an <function>XSyncValue</function> and stores it in *pv.
 537 Performs sign extension (*pv will have the same sign as i.)
 538 </para>
 539
 540 <funcsynopsis id='xsyncintstovalue'>
 541 <funcprototype>
 542   <funcdef>void <function>XSyncIntsToValue</function></funcdef>
 543     <paramdef>XSyncValue<parameter> *pv</parameter></paramdef>
 544     <paramdef>unsigned int<parameter> low</parameter></paramdef>
 545     <paramdef>int<parameter> high</parameter></paramdef>
 546 </funcprototype>
 547 </funcsynopsis>
 548
 549 <para>
 550 Stores low in the low 32 bits of *pv and high in the high 32 bits of *pv.
 551 </para>
 552
 553
 554 <funcsynopsis id='xsyncvaluegreaterthan'>
 555 <funcprototype>
 556   <funcdef>Bool <function>XSyncValueGreaterThan</function></funcdef>
 557     <paramdef>XSyncValue<parameter> a</parameter></paramdef>
 558     <paramdef>XSyncValue<parameter> b</parameter></paramdef>
 559 </funcprototype>
 560 </funcsynopsis>
 561
 562 <para>
 563 Returns <function>True</function> if a is greater than b, else returns
 564 <function>False</function>.
 565 </para>
 566
 567 <funcsynopsis id='xsyncvaluelessthan'>
 568 <funcprototype>
 569   <funcdef>Bool <function>XSyncValueLessThan</function></funcdef>
 570     <paramdef>XSyncValue<parameter> a</parameter></paramdef>
 571     <paramdef>XSyncValue<parameter> b</parameter></paramdef>
 572 </funcprototype>
 573 </funcsynopsis>
 574
 575 <para>
 576 Returns <function>True</function> if a is less than b, else returns
 577 <function>False</function>.
 578 </para>
 579
 580
 581 <funcsynopsis id='xsyncvaluegreaterorequal'>
 582 <funcprototype>
 583   <funcdef>Bool <function>XSyncValueGreaterOrEqual</function></funcdef>
 584     <paramdef>XSyncValue<parameter> a</parameter></paramdef>
 585     <paramdef>XSyncValue<parameter> b</parameter></paramdef>
 586 </funcprototype>
 587 </funcsynopsis>
 588
 589 <para>
 590 Returns <function>True</function> if a is greater than or equal to b,
 591 else returns <function>False</function>.
 592 </para>
 593
 594 <funcsynopsis id='xsyncvaluelessorequal'>
 595 <funcprototype>
 596   <funcdef>Bool <function>XSyncValueLessOrEqual</function></funcdef>
 597     <paramdef>XSyncValue<parameter> a</parameter></paramdef>
 598     <paramdef>XSyncValue<parameter> b</parameter></paramdef>
 599 </funcprototype>
 600 </funcsynopsis>
 601
 602 <para>
 603 Returns <function>True</function> if a is less than or equal to b,
 604 else returns <function>False</function>.
 605 </para>
 606
 607 <funcsynopsis id='xsyncvalueequal'>
 608 <funcprototype>
 609   <funcdef>Bool <function>XSyncValueEqual</function></funcdef>
 610     <paramdef>XSyncValue<parameter> a</parameter></paramdef>
 611     <paramdef>XSyncValue<parameter> b</parameter></paramdef>
 612 </funcprototype>
 613 </funcsynopsis>
 614
 615 <para>
 616 Returns <function>True</function> if a is equal to b,
 617 else returns <function>False</function>.
 618 </para>
 619
 620 <funcsynopsis id='xsyncvalueisnegative'>
 621 <funcprototype>
 622   <funcdef>Bool <function>XSyncValueIsNegative</function></funcdef>
 623     <paramdef>XSyncValue<parameter> v</parameter></paramdef>
 624 </funcprototype>
 625 </funcsynopsis>
 626
 627 <para>
 628 Returns <function>True</function> if v is negative,
 629 else returns <function>False</function>.
 630 </para>
 631
 632 <funcsynopsis id='xsyncvalueiszero'>
 633 <funcprototype>
 634   <funcdef>Bool <function>XSyncValueIsZero</function></funcdef>
 635     <paramdef>XSyncValue<parameter> v</parameter></paramdef>
 636 </funcprototype>
 637 </funcsynopsis>
 638
 639 <para>
 640 Returns <function>True</function> if v is zero,
 641 else returns <function>False</function>.
 642 </para>
 643
 644 <funcsynopsis id='xsyncvalueispositive'>
 645 <funcprototype>
 646   <funcdef>Bool <function>XSyncValueIsPositive</function></funcdef>
 647     <paramdef>XSyncValue<parameter> v</parameter></paramdef>
 648 </funcprototype>
 649 </funcsynopsis>
 650
 651 <para>
 652 Returns <function>True</function> if v is positive,
 653 else returns <function>False</function>.
 654 </para>
 655
 656 <funcsynopsis id='xsyncvaluelow32'>
 657 <funcprototype>
 658   <funcdef>unsigned int <function>XSyncValueLow32</function></funcdef>
 659     <paramdef>XSyncValue<parameter> v</parameter></paramdef>
 660 </funcprototype>
 661 </funcsynopsis>
 662
 663 <para>
 664 Returns the low 32 bits of v.
 665 </para>
 666
 667 <funcsynopsis id='xsyncvaluehigh32'>
 668 <funcprototype>
 669   <funcdef>unsigned int <function>XSyncValueHigh32</function></funcdef>
 670     <paramdef>XSyncValue<parameter> v</parameter></paramdef>
 671 </funcprototype>
 672 </funcsynopsis>
 673
 674 <para>
 675 Returns the high 32 bits of v.
 676 </para>
 677
 678 <funcsynopsis id='xsyncvalueadd'>
 679 <funcprototype>
 680   <funcdef>void <function>XSyncValueAdd</function></funcdef>
 681     <paramdef>XSyncValue<parameter> *presult</parameter></paramdef>
 682     <paramdef>XSyncValue<parameter> a</parameter></paramdef>
 683     <paramdef>XSyncValue<parameter> b</parameter></paramdef>
 684     <paramdef>Bool<parameter> *poverflow</parameter></paramdef>
 685 </funcprototype>
 686 </funcsynopsis>
 687
 688 <para>
 689 Adds a to b and stores the result in *presult. If the result could not
 690 fit in 64 bits, *poverﬂow is set to <function>True</function>, else it is
 691 set to <function>False</function>.
 692 </para>
 693
 694 <funcsynopsis id='xsyncvaluesubtract'>
 695 <funcprototype>
 696   <funcdef>void <function>XSyncValueSubtract</function></funcdef>
 697     <paramdef>XSyncValue<parameter> *presult</parameter></paramdef>
 698     <paramdef>XSyncValue<parameter> a</parameter></paramdef>
 699     <paramdef>XSyncValue<parameter> b</parameter></paramdef>
 700     <paramdef>Bool<parameter> *poverflow</parameter></paramdef>
 701 </funcprototype>
 702 </funcsynopsis>
 703
 704 <para>
 705 Subtracts b from a and stores the result in *presult. If the result could not
 706 fit in 64 bits, *poverﬂow is set to <function>True</function>, else it is
 707 set to <function>False</function>.
 708 </para>
 709
 710 <funcsynopsis id='xsyncmaxvalue'>
 711 <funcprototype>
 712   <funcdef>void <function>XSyncMaxValue</function></funcdef>
 713     <paramdef>XSyncValue<parameter> *pv</parameter></paramdef>
 714 </funcprototype>
 715 </funcsynopsis>
 716
 717 <para>
 718 Sets *pv to the maximum value expressible in 64 bits.
 719 </para>
 720
 721 <funcsynopsis id='xsyncminvalue'>
 722 <funcprototype>
 723   <funcdef>void <function>XSyncMinValue</function></funcdef>
 724     <paramdef>XSyncValue<parameter> *pv</parameter></paramdef>
 725 </funcprototype>
 726 </funcsynopsis>
 727
 728 <para>
 729 Sets *pv to the minimum value expressible in 64 bits.
 730 </para>
 731
 732 </sect1>
 733
 734 <sect1 id="events">
 735 <title>Events</title>
 736
 737 <para>
 738 Let <emphasis remap='I'>event_base</emphasis> be the value event base return as defined in the function
 739 <function>XSyncQueryExtension</function>.
 740 </para>
 741
 742 <para>
 743 An <function>XSyncCounterNotifyEvent</function>’s type field has the value
 744 event_base + <function>XSyncCounterNotify</function>. The fields of this
 745 structure are:
 746 </para>
 747
 748 <literallayout remap='Ds'>
 749 int              type;          /* event base + XSyncCounterNotify */
 750 unsigned long    serial;        /* number of last request processed by server */
 751 Bool             send event;    /* true if this came from a SendEvent request */
 752 Display *        display;       /* Display the event was read from */
 753 XSyncCounter     counter;       /* counter involved in await */
 754 XSyncValue       wait_value;    /* value being waited for */
 755 XSyncValue       counter_value; /* counter value when this event was sent */
 756 Time             time;          /* milliseconds */
 757 int              count;         /* how many more events to come */
 758 Bool             destroyed;     /* True if counter was destroyed */
 759 </literallayout>
 760
 761 <para>
 762 An <function>XSyncAlarmNotifyEvent</function>’s type field has the value
 763 event_base + <function>XSyncAlarmNotify</function>. The fields of
 764 this structure are:
 765 </para>
 766
 767 <literallayout remap='Ds'>
 768 int             type;         /* event_base + XSyncAlarmNotify */
 769 unsigned long   serial;       /* number of last request processed by server */
 770 Bool            send_event;   /* true if this came from a SendEvent request */
 771 Display *       display;      /*Display the event was read from */
 772 XSyncAlarm      alarm;        /* alarm that triggered */
 773 XSyncValue      counter_value /* value that triggered the alarm */
 774 XSyncValue      alarm_value   /* test value of trigger in alarm */
 775 Time            time;         /* milliseconds */
 776 XSyncAlarmState state;        /* new state of alarm */
 777 </literallayout>
 778
 779 </sect1>
 780
 781 <sect1 id="errors">
 782 <title>Errors</title>
 783 <para>
 784 Let <emphasis remap='I'>error_base</emphasis> be the value
 785 <emphasis remap='I'>error_base_return</emphasis> as defined in the function
 786 <function>XSyncQueryExtension</function>.
 787 </para>
 788
 789 <para>
 790 An <function>XSyncAlarmError</function>’s error_code field has
 791 <function>XSyncBadAlarm</function>. The fields of this structure are:
 792 </para>
 793
 794 <literallayout remap='Ds'>
 795 int                type
 796 Display *          display;      /* Display the event was read from */
 797 XSyncCounter       counter;      /* resource id */
 798 unsigned long      serial;       /* serial number of failed request */
 799 unsigned char      error_code;   /* error_base + XSyncBadAlarm */
 800 unsigned char      request_code; /* Major op-code of failed request */
 801 unsigned char      minor_code;   /* Minor op-code of failed request */
 802 </literallayout>
 803
 804 <para>
 805 An <function>XSyncCounterError</function>’s error code field has the value
 806 error_base + <function>XSyncBadCounter</function>. The fields of this
 807 structure are:
 808 </para>
 809 <literallayout remap='Ds'>
 810 int                type
 811 Display *          display;      /* Display the event was read from */
 812 XSyncCounter       counter;      /* resource id */
 813 unsigned long      serial;       /* serial number of failed request */
 814 unsigned char      error_code;   /* error_base + XSyncBadCounter */
 815 unsigned char      request_code; /* Major op-code of failed request */
 816 unsigned char      minor_code;   /* Minor op-code of failed request */
 817 </literallayout>
 818
 819 </sect1>
 820 </chapter>
 821 </book>