specs/dpmslib.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   4
   5 <!-- lifted from troff+ms+XMan by doclifter -->
   6 <book id="dpmslib">
   7
   8 <bookinfo>
   9    <title>X Display Power Management Signaling (DPMS) Extension</title>
  10    <subtitle>X Consortium Standard</subtitle>
  11    <releaseinfo>X Version 11, Release 6.8</releaseinfo>
  12    <authorgroup>
  13       <author>
  14          <firstname>Rob</firstname><surname>Lembree</surname>
  15       </author>
  16    </authorgroup>
  17    <corpname>Digital Equipment Corporation</corpname>
  18    <copyright><year>1996</year><holder>X Consortium</holder></copyright>
  19    <releaseinfo>Version 1.0</releaseinfo>
  20    <affiliation><orgname>X Consortium</orgname></affiliation>
  21    <productnumber>X Version 11, Release 6.8</productnumber>
  22
  23 <legalnotice>
  24 <para>
  25 Permission to use, copy, modify, distribute, and sell this
  26 documentation for any purpose is hereby granted without fee,
  27 provided that the above copyright notice and this permission
  28 notice appear in all copies.  Digital Equipment Corporation
  29 makes no representations about the suitability for any purpose
  30 of the information in this document.  This documentation is
  31 provided "as is" without express or implied warranty.
  32 </para>
  33
  34 <para>
  35 <emphasis remap='I'>X Window System</emphasis> is a trademark of The Open Group.
  36 </para>
  37 </legalnotice>
  38
  39 </bookinfo>
  40
  41 <chapter id='overview'>
  42 <title>Overview</title>
  43
  44 <para>This extension provides X Protocol control over the VESA Display
  45 Power Management Signaling (DPMS) characteristics of video boards
  46 under control of the X Window System.
  47 </para>
  48
  49 <para>
  50 Traditionally, the X Window System has provided for both blanking and
  51 non-blanking screen savers.  Timeouts associated with these built-in
  52 screen saver mechanisms are limited to idle (dwell) time, and a change
  53 timeout that specifies the change interval for non-blanking screen savers.
  54 </para>
  55
  56 <para>
  57 The United States' Environmental Protection Agency (EPA) Energy Star program
  58 requires that monitors power down after some idle time by default.
  59 While it is possible to simply overload the existing screen saver timeouts,
  60 this solution leaves the non-privileged user little to no control over
  61 the DPMS characteristics of his or her system.  For example, disabling
  62 DPMS would require some unintended side effect in the core screen saver,
  63 such as disabling the changing of a non-blanking screen saver.  Providing
  64 clients with this control requires an extension to the core X Window System
  65 Protocol, and this extension seeks to fill this gap.
  66 </para>
  67
  68 <para>
  69 There are four power levels specified by the Video Electronics Standards
  70 Association (VESA) Display Power Management Signaling (DPMS) standard.
  71 These are mapped onto the X DPMS Extension like this:
  72 </para>
  73
  74 <literallayout remap='Ds'>
  75 <function>DPMS Extension Power Levels</function>
  76      0     DPMSModeOn               In use
  77      1     DPMSModeStandby          Blanked, low power
  78      2     DPMSModeSuspend          Blanked, lower power
  79      3     DPMSModeOff               Shut off, awaiting activity
  80 </literallayout> <!-- remap='De' -->
  81
  82 </chapter>
  83
  84 <chapter id='dpms_functions'>
  85 <title>DPMS Functions</title>
  86
  87
  88 <funcsynopsis>
  89 <funcprototype>
  90   <funcdef>Bool <function>DPMSQueryExtention</function></funcdef>
  91     <paramdef>Display <parameter>*display</parameter></paramdef>
  92     <paramdef>int <parameter>event_base</parameter></paramdef>
  93     <paramdef>int <parameter>error_base</parameter></paramdef>
  94 </funcprototype>
  95 </funcsynopsis>
  96
  97 <variablelist remap='IP'>
  98   <varlistentry>
  99     <term><emphasis remap='I'>*display</emphasis></term>
 100     <listitem><para>Specifies the connection to the X server.</para></listitem>
 101   </varlistentry>
 102   <varlistentry>
 103     <term><emphasis remap='I'>event_base</emphasis></term>
 104     <listitem><para>Specifies the return location for the assigned base event</para></listitem>
 105   </varlistentry>
 106   <varlistentry>
 107     <term><emphasis remap='I'>error_base</emphasis></term>
 108     <listitem><para>Specifies the return location for the assigned base error</para></listitem>
 109   </varlistentry>
 110 </variablelist>
 111
 112 <para>
 113 The DPMSQueryExtension function queries the X server to determine the
 114 availability of the DPMS Extension.  If the extension is available, the
 115 return value is TRUE, and <emphasis remap='I'>event_base</emphasis> and
 116 <emphasis remap='I'>error_base</emphasis> are set to the base event number
 117 and base error number for the extension, respectively.  Otherwise, the
 118 return value is FALSE, and the values of
 119 <emphasis remap='I'>event_base</emphasis> and
 120 <emphasis remap='I'>error_base</emphasis> are undefined.
 121 </para>
 122
 123 <funcsynopsis>
 124 <funcprototype>
 125   <funcdef>Status <function>DPMSGetVersion</function></funcdef>
 126     <paramdef>Display <parameter>*display</parameter></paramdef>
 127     <paramdef>int <parameter>*major_version</parameter></paramdef>
 128     <paramdef>int <parameter>*minor_version</parameter></paramdef>
 129 </funcprototype>
 130 </funcsynopsis>
 131
 132 <variablelist remap='IP'>
 133   <varlistentry>
 134     <term><emphasis remap='I'>display</emphasis></term>
 135     <listitem><para>Specifies the connection to the X server.</para></listitem>
 136   </varlistentry>
 137   <varlistentry>
 138     <term><emphasis remap='I'>major_version</emphasis></term>
 139     <listitem><para>Specifies the return location for the extension major version.</para></listitem>
 140   </varlistentry>
 141   <varlistentry>
 142     <term><emphasis remap='I'>minor_version</emphasis></term>
 143     <listitem><para>Specifies the return location for the extension minor version.</para></listitem>
 144   </varlistentry>
 145 </variablelist>
 146
 147
 148 <para>
 149 The DPMSGetVersion function returns the version of the DPMS extension
 150 implemented by the X server.  The version is returned in
 151 <emphasis remap='I'>major_version</emphasis> and
 152 <emphasis remap='I'>minor_version</emphasis>.
 153 The major version and minor version for this specification are '1' and '1',
 154 respectively.  The major version will be incremented for protocol
 155 incompatible changes, and the minor version will be incremented for small,
 156 upwardly compatible changes.
 157 </para>
 158
 159 <funcsynopsis>
 160 <funcprototype>
 161   <funcdef>Bool <function>DPMSCapable</function></funcdef>
 162     <paramdef>Display <parameter>*display</parameter></paramdef>
 163 </funcprototype>
 164 </funcsynopsis>
 165
 166 <variablelist remap='IP'>
 167   <varlistentry>
 168     <term><emphasis remap='I'>display</emphasis></term>
 169     <listitem><para>Specifies the connection to the X server.</para></listitem>
 170   </varlistentry>
 171 </variablelist>
 172
 173
 174 <para>
 175 The DPMSCapable function returns the DPMS capability of the X server, either
 176 TRUE (capable of DPMS) or FALSE (incapable of DPMS).  The capability of an
 177 X server is implementation defined.  For example, if a multi-headed  X server
 178 is capable of DPMS on one head, and incapable on another, the truth value of
 179 this function is defined by the X server implementation.
 180 </para>
 181
 182 <funcsynopsis>
 183 <funcprototype>
 184   <funcdef>Status <function>DPMSSetTimeouts</function></funcdef>
 185     <paramdef>Display <parameter>*display</parameter></paramdef>
 186     <paramdef>CARD16 <parameter>standby</parameter></paramdef>
 187     <paramdef>CARD16 <parameter>suspend</parameter></paramdef>
 188     <paramdef>CARD16 <parameter>off</parameter></paramdef>
 189 </funcprototype>
 190 </funcsynopsis>
 191
 192 <variablelist remap='IP'>
 193   <varlistentry>
 194     <term><emphasis remap='I'>display</emphasis></term>
 195     <listitem><para>Specifies the connection to the X server.</para></listitem>
 196   </varlistentry>
 197   <varlistentry>
 198     <term><emphasis remap='I'>standby</emphasis></term>
 199     <listitem><para>Specifies the new standby timeout in seconds.</para></listitem>
 200   </varlistentry>
 201   <varlistentry>
 202     <term><emphasis remap='I'>suspend</emphasis></term>
 203     <listitem><para>Specifies the new suspend timeout in seconds.</para></listitem>
 204   </varlistentry>
 205   <varlistentry>
 206     <term><emphasis remap='I'>off</emphasis></term>
 207     <listitem><para>Specifies the new off timeout in seconds.</para></listitem>
 208   </varlistentry>
 209 </variablelist>
 210
 211 <para>
 212 The DPMSSetTimeouts function permits applications to set the timeout values
 213 used by the X server for DPMS timings.
 214 </para>
 215
 216 <para>
 217 The value <emphasis remap='I'>standby</emphasis> is the amount of time of
 218 inactivity in seconds before standby mode is invoked. The actual effects of
 219 this mode are implementation defined, but in the case of DPMS compliant
 220 hardware, it is implemented by shutting off the horizontal sync signal,
 221 and pulsing the vertical sync signal.
 222 Standby mode provides the quickest monitor recovery time.  Note also that
 223 many monitors implement this mode identically to suspend mode.  A value
 224 of zero disables this mode.
 225 </para>
 226
 227 <para>
 228 The value <emphasis remap='I'>suspend</emphasis> is the amount of time of
 229 inactivity in seconds before the second level of power savings is invoked.
 230 Suspend mode's physical and electrical characteristics are implementation
 231 defined, but in DPMS compliant hardware, results in the pulsing of the
 232 horizontal sync signal, and shutting off of the vertical sync signal.
 233 Suspend mode recovery is considered to be slower than standby mode, but
 234 faster than off mode, however this is monitor dependent.  As noted above,
 235 many monitors implement this mode identically to standby mode.  A value of
 236 zero disables this mode.
 237 </para>
 238
 239 <para>
 240 The value <emphasis remap='I'>off</emphasis> is the amount of time of
 241 inactivity in seconds before the third and final level of power savings is
 242 invoked. Off mode's physical and electrical characteristics are
 243 implementation defined, but in DPMS compliant hardware, is implemented by
 244 shutting off both horizontal and vertical sync signals, resulting in
 245 the power-down of the monitor.  Recovery time is implementation dependant,
 246 but frequently is similar to the power-up time of the monitor.  A value
 247 of zero disables this mode.
 248 </para>
 249
 250 <para>
 251 Chronologically, standby mode occurs before or simultaneously with
 252 suspend mode, and suspend mode must occur before or simultaneously with
 253 off mode.  Therefore, non-zero mode timeout values must be greater than
 254 or equal to the timeout values of earlier modes.  If inconsistent values
 255 are supplied, a BadValue error will result.
 256 </para>
 257
 258 <funcsynopsis>
 259 <funcprototype>
 260   <funcdef>Status <function>DPMSGetTimeouts</function></funcdef>
 261     <paramdef>Display <parameter>*display</parameter></paramdef>
 262     <paramdef>CARD16 <parameter>*standby</parameter></paramdef>
 263     <paramdef>CARD16 <parameter>*suspend</parameter></paramdef>
 264     <paramdef>CARD16 <parameter>*off</parameter></paramdef>
 265 </funcprototype>
 266 </funcsynopsis>
 267
 268 <variablelist remap='IP'>
 269   <varlistentry>
 270     <term><emphasis remap='I'>display</emphasis></term>
 271     <listitem><para>Specifies the connection to the X server.</para></listitem>
 272   </varlistentry>
 273   <varlistentry>
 274     <term><emphasis remap='I'>standby</emphasis></term>
 275     <listitem><para>Specifies the new standby timeout in seconds.</para></listitem>
 276   </varlistentry>
 277   <varlistentry>
 278     <term><emphasis remap='I'>suspend</emphasis></term>
 279     <listitem><para>Specifies the new suspend timeout in seconds.</para></listitem>
 280   </varlistentry>
 281   <varlistentry>
 282     <term><emphasis remap='I'>off</emphasis></term>
 283     <listitem><para>Specifies the new off timeout in seconds.</para></listitem>
 284   </varlistentry>
 285 </variablelist>
 286
 287 <para>
 288 The DPMSGetTimeouts function retrieves the timeout values used by the X
 289 server for DPMS timings.
 290 </para>
 291
 292 <para>
 293 The value <emphasis remap='I'>standby</emphasis> is the amount of time of
 294 inactivity in seconds before standby mode is invoked. A value of zero
 295 indicates that this mode has been disabled.
 296 </para>
 297
 298 <para>
 299 The value <emphasis remap='I'>suspend</emphasis> is the amount of time of
 300 inactivity in seconds before the second level of power savings is invoked.
 301 A value of zero indicates that this mode has been disabled.
 302 </para>
 303
 304 <para>
 305 The value <emphasis remap='I'>off</emphasis> is the amount of time of
 306 inactivity in seconds before the third and final level of power savings is
 307 invoked. A value of zero indicates that this mode has been disabled.
 308 </para>
 309
 310 <funcsynopsis>
 311 <funcprototype>
 312   <funcdef>Status <function>DPMSEnable</function></funcdef>
 313     <paramdef>Display <parameter>*display</parameter></paramdef>
 314 </funcprototype>
 315 </funcsynopsis>
 316
 317 <variablelist remap='IP'>
 318   <varlistentry>
 319     <term><emphasis remap='I'>display</emphasis></term>
 320     <listitem><para>Specifies the connection to the X server.</para></listitem>
 321   </varlistentry>
 322 </variablelist>
 323
 324 <para>
 325 The DPMSEnable function enables DPMS on the specified display.  When
 326 enabled, DPMS will use the currently saved timeout values, and will
 327 invoke the DPMS power mode appropriate for the amount of time that
 328 the workstation input devices have been idle.  If DPMSEnable is invoked
 329 on a display with DPMS already enabled, no change is made, and no
 330 error is returned.  If DPMSEnable is invoked on a display without
 331 support for DPMS, no change is made and no error is returned.
 332 </para>
 333
 334 <funcsynopsis>
 335 <funcprototype>
 336   <funcdef>Status <function>DPMSDisable</function></funcdef>
 337     <paramdef>Display <parameter>*display</parameter></paramdef>
 338 </funcprototype>
 339 </funcsynopsis>
 340
 341 <variablelist remap='IP'>
 342   <varlistentry>
 343     <term><emphasis remap='I'>display</emphasis></term>
 344     <listitem><para>Specifies the connection to the X server.</para></listitem>
 345   </varlistentry>
 346 </variablelist>
 347
 348 <para>
 349 The DPMSDisable function disables DPMS on the specified display.  When
 350 disabled, DPMS returns the display to DPMSModeOn.  If DPMSDisable is
 351 invoked on a display with DPMS already disabled, no change is made,
 352 and no error is returned.  If DPMSDisable is invoked on a display
 353 without support for DPMS, no change is made and no error is returned.
 354 </para>
 355
 356 <funcsynopsis>
 357 <funcprototype>
 358   <funcdef>Status <function>DPMSForceLevel</function></funcdef>
 359     <paramdef>Display <parameter>*display</parameter></paramdef>
 360     <paramdef>CARD16 <parameter>level</parameter></paramdef>
 361 </funcprototype>
 362 </funcsynopsis>
 363
 364 <variablelist remap='IP'>
 365   <varlistentry>
 366     <term><emphasis remap='I'>display</emphasis></term>
 367     <listitem><para>Specifies the connection to the X server.</para></listitem>
 368   </varlistentry>
 369   <varlistentry>
 370     <term><emphasis remap='I'>level</emphasis></term>
 371     <listitem><para>Specifies the level to force power to.</para></listitem>
 372   </varlistentry>
 373 </variablelist>
 374
 375 <para>
 376 The DPMSForceLevel function forces a DPMS capable display into the
 377 specified power level.  The <emphasis remap='I'>level</emphasis> must be one of
 378 DPMSModeOn, DPMSModeStandby, DPMSModeSuspend, or DPMSModeOff.
 379 Values other than these will result in a BadValue error.  If DPMS
 380 is disabled on the display, a BadMatch protocol error will result.
 381 </para>
 382
 383 <para>Status DPMSInfo(<emphasis remap='I'>display, power_level, state</emphasis>)</para>
 384
 385 <funcsynopsis>
 386 <funcprototype>
 387   <funcdef>Status <function>DPMSInfo</function></funcdef>
 388     <paramdef>Display <parameter>*display</parameter></paramdef>
 389     <paramdef>CARD16 <parameter>power_level</parameter></paramdef>
 390     <paramdef>BOOL <parameter>*state</parameter></paramdef>
 391 </funcprototype>
 392 </funcsynopsis>
 393
 394 <variablelist remap='IP'>
 395   <varlistentry>
 396     <term><emphasis remap='I'>display</emphasis></term>
 397     <listitem><para>Specifies the connection to the X server.</para></listitem>
 398   </varlistentry>
 399   <varlistentry>
 400     <term><emphasis remap='I'>power_level</emphasis></term>
 401     <listitem><para>Specifies the current power level.</para></listitem>
 402   </varlistentry>
 403   <varlistentry>
 404     <term><emphasis remap='I'>state</emphasis></term>
 405     <listitem><para>Specifies the current DPMS state.</para></listitem>
 406   </varlistentry>
 407 </variablelist>
 408
 409 <para>
 410 The DPMSInfo function returns information about the current DPMS state.
 411 The <emphasis remap='I'>state</emphasis> return parameter indicates whether
 412 or not DPMS is enabled (TRUE) or disabled (FALSE).  The
 413 <emphasis remap='I'>power_level</emphasis> return parameter indicates the
 414 current power level (one of DPMSModeOn, DPMSModeStandby, DPMSModeSuspend,
 415 or DPMSModeOff.)
 416 </para>
 417
 418 </chapter>
 419 </book>