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<book id="dpms"> 9 10<bookinfo> 11 <title>X Display Power Management Signaling (DPMS) Extension Protocol Specification</title> 12 <subtitle>X Project Team Standard</subtitle> 13 <authorgroup> 14 <author> 15 <firstname>Rob </firstname><surname>Lembree</surname> 16 <affiliation><orgname>Digital Equipment Corporation</orgname></affiliation> 17 <email>lembree@zk3.dec.com</email> 18 </author> 19 </authorgroup> 20 <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo> 21 <releaseinfo>Version 1.0</releaseinfo> 22 <copyright><year>1996</year><holder>Digital Equipment Corporation</holder></copyright> 23 24<legalnotice> 25<para> 26Permission to use, copy, modify, distribute, and sell this 27documentation for any purpose is hereby granted without fee, 28provided that the above copyright notice and this permission 29notice appear in all copies. Digital Equipment Corporation 30makes no representations about the suitability for any purpose 31of the information in this document. This documentation is 32provided “as is” without express or implied warranty. 33</para> 34 35</legalnotice> 36</bookinfo> 37 38<chapter id="Overview"> 39<title>Overview</title> 40<para> 41This extension provides X Protocol control over the VESA Display 42Power Management Signaling (DPMS) characteristics of video boards 43under control of the X Window System.<footnote> 44<para> 45<emphasis remap='I'>X Window System</emphasis> is a trademark of The Open Group. 46</para> 47</footnote> 48</para> 49 50 51<para> 52<!-- .LP --> 53Traditionally, the X Window System has provided for both blanking and 54non-blanking screen savers. Timeouts associated with these built-in 55screen saver mechanisms are limited to idle (dwell) time, and a change 56timeout that specifies the change interval for non-blanking screen savers. 57</para> 58<para> 59<!-- .LP --> 60The United States' Environmental Protection Agency (EPA) Energy Star program 61requires that monitors power down after some idle time by default. 62While it is possible to simply overload the existing screen saver timeouts, 63this solution leaves the non-privileged user little to no control over 64the DPMS characteristics of his or her system. For example, disabling 65DPMS would require some unintended side effect in the core screen saver, 66such as disabling the changing of a non-blanking screen saver. Providing 67clients with this control requires an extension to the core X Window System 68Protocol, and this extension seeks to fill this gap. 69</para> 70<para> 71<!-- .LP --> 72The design goal of the DPMS extension is to be a logical extension to 73the traditional screen saver. The protocol and sample implementation is 74designed to use the same date types and time units as the screen saver. 75The sample implementation works independently from the screen saver so that 76policy as it pertains to the interaction between screen saver and DPMS can 77be deferred to the user or screen saver application. The extension has 78been tested with and shown to work correctly with both the internal blanking 79and non-blanking screen savers, as well as with screen saver extension 80clients. 81</para> 82<para> 83The DPMS extension is designed to be simple, yet export sufficient 84VESA DPMS information to enable full function clients to be written. 85Included is the ability to sense DPMS capability, set and get DPMS timeouts, 86enable and disable individual DPMS modes, enable and disable DPMS (without 87destroying timeout values), and sense current DPMS on/off state and 88power level. 89</para> 90<para> 91There are four power levels specified by the Video Electronics Standards 92Association (VESA) Display Power Management Signaling (DPMS) standard. 93These are: 94</para> 95 96<literallayout class="monospaced"> 97<function>DPMS Extension Power Levels</function> 98 0 DPMSModeOn In use 99 1 DPMSModeStandby Blanked, low power 100 2 DPMSModeSuspend Blanked, lower power 101 3 DPMSModeOff Shut off, awaiting activity 102</literallayout> 103 104<para> 105It is logical to assume that successive DPMS modes be chronologically 106at the same time or later than one another, and the protocol is designed 107to enforce this rule. 108</para> 109 110<para> 111Note however that a conscious decision is made to decouple the timeouts 112associated with screen saver from the DPMS timeouts. While it might be 113considered logical to require that the first non-zero DPMS timeout be 114greater than or equal to the screen saver timeout, this is intentionally 115omitted, leaving this policy decision to the user or the screen saver 116application. In the case of a laptop where power may be scarce, the 117importance of power savings should supersede the screen saver. If the 118laptop user plugs the unit in and power is no longer a scarce commodity, 119it may be decided to make DPMS less aggressive, or disable it completely. 120</para> 121</chapter> 122 123<chapter id="Requests"> 124<title>Requests</title> 125<para> 126<olink targetdoc='dpmslib' targetptr='DPMSGetVersion'><function>DPMSGetVersion</function></olink> 127</para> 128 129<informaltable frame="none"> 130 <?dbfo keep-together="always" ?> 131 <tgroup cols='1' align='left' colsep='0' rowsep='0'> 132 <colspec colname='c1' colwidth="1.0*"/> 133 <tbody> 134 <row> 135 <entry> 136<emphasis remap='I'>client_major_version</emphasis>: CARD16 137 </entry> 138 </row> 139 <row> 140 <entry> 141<emphasis remap='I'>client_minor_version</emphasis>: CARD16 142 </entry> 143 </row> 144 <row> 145 <entry>=></entry> 146 </row> 147 <row> 148 <entry> 149<emphasis remap='I'>server_major_version</emphasis>: CARD16 150 </entry> 151 </row> 152 <row> 153 <entry> 154<emphasis remap='I'>server_minor_version</emphasis>: CARD16 155 </entry> 156 </row> 157 </tbody> 158 </tgroup> 159</informaltable> 160 161<para> 162If supplied, the <emphasis remap='I'>client_major_version</emphasis> and 163<emphasis remap='I'>client_minor_version</emphasis> indicate what version 164of the protocol the 165client wants the server to implement. The server version numbers 166returned indicate the protocol this extension actually supports. This 167might not equal the version sent by the client. An implementation can 168(but need not) support more than one version simultaneously. The 169<emphasis remap='I'>server_major_version</emphasis> and the 170<emphasis remap='I'>server_minor_version</emphasis> are a 171mechanism to support future revisions of the Display Power Management 172Signaling protocol which may be necessary. In general, the major version 173would increment for incompatible changes, and the minor version would 174increment for small, upward-compatible changes. Servers that support the 175protocol defined in this document will return a 176<emphasis remap='I'>server_major_version</emphasis> 177of one (1), and a <emphasis remap='I'>server_minor_version</emphasis> 178of two (2). 179</para> 180 181<para> 182<olink targetdoc='dpmslib' targetptr='DPMSCapable'><function>DPMSCapable</function></olink> 183</para> 184 185<informaltable frame="none"> 186 <?dbfo keep-together="always" ?> 187 <tgroup cols='1' align='left' colsep='0' rowsep='0'> 188 <colspec colname='c1' colwidth="1.0*"/> 189 <tbody> 190 <row> 191 <entry>=></entry> 192 </row> 193 <row> 194 <entry> 195<emphasis remap='I'>capable</emphasis>: BOOL 196 </entry> 197 </row> 198 </tbody> 199 </tgroup> 200</informaltable> 201 202<para> 203This request is used to determine whether or not the currently running 204server's devices are capable of DPMS operations. The truth value of this 205request is implementation defined, but is generally based on the capabilities 206of the graphic card and monitor combination. Also, the return value in the 207case of heterogeneous multi-head servers is implementation defined. 208</para> 209 210<para> 211<olink targetdoc='dpmslib' targetptr='DPMSGetTimeouts'><function>DPMSGetTimeouts</function></olink> 212</para> 213 214<informaltable frame="none"> 215 <?dbfo keep-together="always" ?> 216 <tgroup cols='1' align='left' colsep='0' rowsep='0'> 217 <colspec colname='c1' colwidth="1.0*"/> 218 <tbody> 219 <row> 220 <entry>=></entry> 221 </row> 222 <row> 223 <entry> 224<emphasis remap='I'>standby_timeout</emphasis>: CARD16 225 </entry> 226 </row> 227 <row> 228 <entry> 229<emphasis remap='I'>suspend_timeout</emphasis>: CARD16 230 </entry> 231 </row> 232 <row> 233 <entry> 234<emphasis remap='I'>off_timeout</emphasis>: CARD16 235 </entry> 236 </row> 237 </tbody> 238 </tgroup> 239</informaltable> 240 241<para> 242This request returns the current values of the DPMS timeout values. All 243values are in units of seconds. 244</para> 245 246<para> 247<emphasis remap='I'>standby_timeout</emphasis> is the amount of time 248of inactivity before standby 249mode is invoked. The actual effects of this mode are implementation defined, 250but in the case of DPMS compliant hardware, it is implemented by shutting off 251the horizontal sync signal, and pulsing the vertical sync signal. Standby 252mode provides the quickest monitor recovery time. Note also that many 253monitors implement this mode identically to suspend mode. A value of 254zero indicates that this mode is disabled. 255</para> 256 257<para> 258<emphasis remap='I'>suspend_timeout</emphasis> is the amount of time 259of inactivity before the second 260level of power savings is invoked. Suspend mode's physical and electrical 261characteristics are implementation defined, but in DPMS compliant hardware, 262results in the pulsing of the horizontal sync signal, and shutting off of 263the vertical sync signal. Suspend mode recovery is considered to be slower 264than standby mode, but faster than off mode, however this is monitor 265dependent. As noted above, many monitors implement this mode identically to 266standby mode. A value of zero indicates that this mode is disabled. 267</para> 268 269<para> 270<emphasis remap='I'>off_timeout</emphasis> is the amount of time of 271inactivity before the third and 272final level of power savings is invoked. Off mode's physical and electrical 273characteristics are implementation defined, but in DPMS compliant hardware, 274is implemented by shutting off both horizontal and vertical sync signals, 275resulting in the power-down of the monitor. Recovery time is implementation 276dependent, but frequently is similar to the power-up time of the monitor. A 277value of zero indicates that this mode is disabled. 278</para> 279 280<para> 281<olink targetdoc='dpmslib' targetptr='DPMSSetTimeouts'><function>DPMSSetTimeouts</function></olink> 282</para> 283 284<informaltable frame="none"> 285 <?dbfo keep-together="always" ?> 286 <tgroup cols='1' align='left' colsep='0' rowsep='0'> 287 <colspec colname='c1' colwidth="1.0*"/> 288 <tbody> 289 <row> 290 <entry> 291<emphasis remap='I'>standby_timeout</emphasis>: CARD16 292 </entry> 293 </row> 294 <row> 295 <entry> 296<emphasis remap='I'>suspend_timeout</emphasis>: CARD16 297 </entry> 298 </row> 299 <row> 300 <entry> 301<emphasis remap='I'>off_timeout</emphasis>: CARD16 302 </entry> 303 </row> 304 <row> 305 <entry>=></entry> 306 </row> 307 </tbody> 308 </tgroup> 309</informaltable> 310 311 312<para> 313All values are in units of seconds. 314<emphasis remap='I'>standby_timeout</emphasis> is the amount of 315time of inactivity before standby mode will be invoked. This is the 316lightest level of power savings, and the monitor is generally immediately 317ready upon detection of user activity. This is most often implemented by 318shutting off the horizontal sync signal to the monitor. 319A value of zero disables this mode. 320</para> 321 322<para> 323The <emphasis remap='I'>suspend_timeout</emphasis> specifies the amount 324of time of inactivity 325before the screen is placed into suspend mode. Suspend mode is the 326middle level of power savings, resulting in a slightly longer recovery 327upon detection of activity. Suspend mode is most often implemented by 328pulsing the horizontal sync signal, and removing the vertical sync 329signal. A value of zero disables this mode. 330</para> 331 332<para> 333The <emphasis remap='I'>off_timeout</emphasis> specifies the amount of 334time of inactivity before 335the monitor is shut off. Off mode is the deepest level of power management, 336resulting in the greatest power savings and the longest recovery time. 337Off mode is most often implemented by removing both the horizontal and 338vertical signals. A value of zero disables this mode. 339</para> 340<para> 341The values of successive power levels must be greater than or equal 342to the value of the previous (non-zero) level. A BadValue error is generated 343if an illegal combination is detected. 344</para> 345<para> 346<olink targetdoc='dpmslib' targetptr='DPMSEnable'><function>DPMSEnable</function></olink> 347</para> 348<para> 349=> 350</para> 351 352<para> 353This request enables the DPMS characteristics of the server, using the 354server's currently stored timeouts. If DPMS is already enabled, no change is 355effected. 356</para> 357 358<para> 359<olink targetdoc='dpmslib' targetptr='DPMSDisable'><function>DPMSDisable</function></olink> 360</para> 361<para> 362=> 363</para> 364 365<para> 366This request disables the DPMS characteristics of the server. It does 367not affect the core or extension screen savers. If DPMS is already 368disabled, no change is effected. This request is provided so that DPMS 369may be disabled without damaging the server's stored timeout values. 370</para> 371 372<para> 373<olink targetdoc='dpmslib' targetptr='DPMSForceLevel'><function>DPMSForceLevel</function></olink> 374</para> 375 376<informaltable frame="none"> 377 <?dbfo keep-together="always" ?> 378 <tgroup cols='1' align='left' colsep='0' rowsep='0'> 379 <colspec colname='c1' colwidth="1.0*"/> 380 <tbody> 381 <row> 382 <entry> 383<emphasis remap='I'>power_level</emphasis>: CARD16 384 </entry> 385 </row> 386 <row> 387 <entry>=></entry> 388 </row> 389 </tbody> 390 </tgroup> 391</informaltable> 392 393<para> 394This request forces a specific DPMS level on the server. If DPMS is 395disabled, a BadMatch error is generated. If an erroneous power level 396is specified, a BadValue error is returned, and the error value contains 397the bad value. If the power level specified is already in effect, no 398changes occur. Power Level must be one of DPMSModeOn, DPMSModeStandby, 399DPMSModeSuspend or DPMSModeOff. 400</para> 401 402<para> 403<olink targetdoc='dpmslib' targetptr='DPMSInfo'><function>DPMSInfo</function></olink> 404</para> 405 406<informaltable frame="none"> 407 <?dbfo keep-together="always" ?> 408 <tgroup cols='1' align='left' colsep='0' rowsep='0'> 409 <colspec colname='c1' colwidth="1.0*"/> 410 <tbody> 411 <row> 412 <entry>=></entry> 413 </row> 414 <row> 415 <entry> 416<emphasis remap='I'>power_level</emphasis>: CARD16 417 </entry> 418 </row> 419 <row> 420 <entry> 421<emphasis remap='I'>state</emphasis>: BOOL 422 </entry> 423 </row> 424 </tbody> 425 </tgroup> 426</informaltable> 427 428<para> 429This request returns information about the current DPMS state of the 430display. <emphasis remap='I'>state</emphasis> is one of DPMSEnabled 431or DPMSDisabled. 432If <emphasis remap='I'>state</emphasis> is DPMSEnabled, 433<emphasis remap='I'>power_level</emphasis> is returned as one 434of DPMSModeOn, DPMSModeStandby, DPMSModeSuspend or DPMSModeOff, otherwise 435it is undefined. 436</para> 437 438<para> 439<olink targetdoc='dpmslib' targetptr='DPMSSelectInput'><function>DPMSSelectInput</function></olink> 440</para> 441 442<informaltable frame="none"> 443 <?dbfo keep-together="always" ?> 444 <tgroup cols='1' align='left' colsep='0' rowsep='0'> 445 <colspec colname='c1' colwidth="1.0*"/> 446 <tbody> 447 <row> 448 <entry> 449<emphasis remap='I'>event_mask</emphasis>: CARD32 450 </entry> 451 </row> 452 <row> 453 <entry>=></entry> 454 </row> 455 </tbody> 456 </tgroup> 457</informaltable> 458 459<para> 460This request specifies whether DPMS extension events should be generated for this client. 461If DPMSInfoNotifyMask is set in <emphasis remap='I'>event-mask</emphasis>, then DPMSInfoNotifyEvent 462events will be generated whenever the current DPMS on/off state or power level changes. 463If no bits are set, then no events will be generated. 464</para> 465 466</chapter> 467 468<chapter id="Events"> 469 470<title>Events</title> 471<para> 472The DPMS extension adds one event: 473</para> 474<para> 475<function>DPMSInfoNotifyEvent</function> 476</para> 477 478<informaltable frame="none"> 479 <?dbfo keep-together="always" ?> 480 <tgroup cols='1' align='left' colsep='0' rowsep='0'> 481 <colspec colname='c1' colwidth="1.0*"/> 482 <tbody> 483 <row> 484 <entry> 485<emphasis remap='I'>timestamp</emphasis>: TIMESTAMP 486 </entry> 487 </row> 488 <row> 489 <entry> 490<emphasis remap='I'>power_level</emphasis>: CARD16 491 </entry> 492 </row> 493 <row> 494 <entry> 495<emphasis remap='I'>state</emphasis>: BOOL 496 </entry> 497 </row> 498 </tbody> 499 </tgroup> 500</informaltable> 501 502<para> 503This event is delivered to clients that have requested 504DPMSInfoNotifyMask events using the <function>DPMSSelectInput</function> request 505whenever the current DPMS on/off state or power level changes. 506<emphasis remap='I'>state</emphasis> is one of DPMSEnabled or DPMSDisabled. 507If <emphasis remap='I'>state</emphasis> is DPMSEnabled, 508<emphasis remap='I'>power_level</emphasis> is one 509of DPMSModeOn, DPMSModeStandby, DPMSModeSuspend or DPMSModeOff, otherwise 510it is undefined. 511</para> 512 513</chapter> 514 515<chapter id="Encoding"> 516<title>Encoding</title> 517<para> 518Please refer to the X11 Protocol Encoding document as this document uses 519conventions established there. 520</para> 521 522<para> 523The name of this extension is "DPMS". 524</para> 525 526<literallayout class="monospaced"> 527<olink targetdoc='dpmslib' targetptr='DPMSGetVersion'><function>DPMSGetVersion</function></olink> 528 1 CARD8 opcode 529 1 0 DPMS opcode 530 2 2 request length 531 2 CARD16 client_major_version 532 2 CARD16 client_minor_version 533=> 534 1 1 Reply 535 1 unused 536 2 CARD16 sequence number 537 4 0 length 538 2 CARD16 server_major_version 539 2 CARD16 server_minor_version 540 20 unused 541</literallayout> 542 543<literallayout class="monospaced"> 544<olink targetdoc='dpmslib' targetptr='DPMSCapable'><function>DPMSCapable</function></olink> 545 1 CARD8 opcode 546 1 1 DPMS opcode 547 2 1 request length 548=> 549 1 1 Reply 550 1 unused 551 2 CARD16 sequence number 552 4 0 length 553 1 BOOL capable 554 23 unused 555</literallayout> 556 557<literallayout class="monospaced"> 558<olink targetdoc='dpmslib' targetptr='DPMSGetTimeouts'><function>DPMSGetTimeouts</function></olink> 559 1 CARD8 opcode 560 1 2 DPMS opcode 561 2 1 request length 562=> 563 1 1 Reply 564 1 unused 565 2 CARD16 sequence number 566 4 0 length 567 2 CARD16 standby_timeout 568 2 CARD16 suspend_timeout 569 2 CARD16 off_timeout 570 18 unused 571</literallayout> 572 573<literallayout class="monospaced"> 574<olink targetdoc='dpmslib' targetptr='DPMSSetTimeouts'><function>DPMSSetTimeouts</function></olink> 575 1 CARD8 opcode 576 1 3 DPMS opcode 577 2 3 request length 578 2 CARD16 standby_timeout 579 2 CARD16 suspend_timeout 580 2 CARD16 off_timeout 581 2 unused 582=> 583</literallayout> 584 585<literallayout class="monospaced"> 586<olink targetdoc='dpmslib' targetptr='DPMSEnable'><function>DPMSEnable</function></olink> 587 1 CARD8 opcode 588 1 4 DPMS opcode 589 2 1 request length 590 => 591</literallayout> 592 593<literallayout class="monospaced"> 594<olink targetdoc='dpmslib' targetptr='DPMSDisable'><function>DPMSDisable</function></olink> 595 1 CARD8 opcode 596 1 5 DPMS opcode 597 2 1 request length 598 => 599</literallayout> 600 601<literallayout class="monospaced"> 602<olink targetdoc='dpmslib' targetptr='DPMSForceLevel'><function>DPMSForceLevel</function></olink> 603 1 CARD8 opcode 604 1 6 DPMS opcode 605 2 2 request length 606 2 power_level 607 0 DPMSModeOn 608 1 DPMSModeStandby 609 2 DPMSModeSuspend 610 3 DPMSModeOff 611 2 unused 612=> 613</literallayout> 614 615<literallayout class="monospaced"> 616<olink targetdoc='dpmslib' targetptr='DPMSInfo'><function>DPMSInfo</function></olink> 617 1 CARD8 opcode 618 1 7 DPMS opcode 619 2 1 request length 620=> 621 1 1 Reply 622 1 unused 623 2 CARD16 sequence number 624 4 0 length 625 2 power_level 626 0 DPMSModeOn 627 1 DPMSModeStandby 628 2 DPMSModeSuspend 629 3 DPMSModeOff 630 1 BOOL state 631 21 unused 632 633</literallayout> 634 635<literallayout class="monospaced"> 636<olink targetdoc='dpmslib' targetptr='DPMSSelectInput'><function>DPMSSelectInput</function></olink> 637 1 CARD8 opcode 638 1 8 DPMS opcode 639 2 2 request length 640 4 event mask 641 0 no events 642 1 DPMSInfoNotifyMask 643</literallayout> 644 645<literallayout class="monospaced"> 646<olink targetdoc='dpmslib' targetptr='DPMSInfoNotifyEvent'><function>DPMSInfoNotifyEvent</function></olink> 647 1 GenericEvent type 648 1 CARD8 DPMS extension offset 649 2 CARD16 sequence number 650 4 0 length 651 2 DPMSInfoNotify evtype 652 2 unused 653 4 TIMESTAMP timestamp 654 2 power_level 655 0 DPMSModeOn 656 1 DPMSModeStandby 657 2 DPMSModeSuspend 658 3 DPMSModeOff 659 1 BOOL state 660 13 unused 661</literallayout> 662</chapter> 663</book> 664