














   XX DDiissppllaayy PPoowweerr MMaannaaggeemmeenntt SSiiggnnaalliinngg ((DDPPMMSS)) EExxtteennssiioonn

                   LLiibbrraarryy SSppeecciiffiiccaattiioonn



                    Version 0.5 (DRAFT)






                        Rob Lembree
                    _l_e_m_b_r_e_e_@_z_k_3_._d_e_c_._c_o_m
               Digital Equipment Corporation
                       24 April 1996








































Copyright (C) Digital Equipment Corporation, 1996

Permission  to  use, copy, modify, distribute, and sell this
documentation for any purpose is hereby granted without fee,
provided that the above copyright notice and this permission
notice appear in all copies.  Digital Equipment  Corporation
makes  no representations about the suitability for any pur-
pose of the information in this document.   This  documenta-
tion  is  provided ``as is'' without express or implied war-
ranty.
























































11..  OOvveerrvviieeww

This extension provides X Protocol  control  over  the  VESA
Display Power Management Signaling (DPMS) characteristics of
video boards under control of the X Window System.

Traditionally,  the  X  Window  System has provided for both
blanking and non-blanking screen savers.   Timeouts  associ-
ated with these built-in screen saver mechanisms are limited
to idle (dwell) time, and a change  timeout  that  specifies
the change interval for non-blanking screen savers.

The  United  States'  Environmental  Protection Agency (EPA)
Energy Star program requires that monitors power down  after
some  idle  time by default.  While it is possible to simply
overload the existing screen saver timeouts,  this  solution
leaves the non-privileged user little to no control over the
DPMS characteristics of his or  her  system.   For  example,
disabling  DPMS would require some unintended side effect in
the core screen saver, such as disabling the changing  of  a
non-blanking screen saver.  Providing clients with this con-
trol requires an extension to the core X Window System  Pro-
tocol, and this extension seeks to fill this gap.

There are four power levels specified by the Video Electron-
ics Standards Association (VESA)  Display  Power  Management
Signaling (DPMS) standard.  These are mapped onto the X DPMS
Extension like this:

  0            DPMSModeOn          In                    use
  1            DPMSModeStandby     Blanked,     low    power
  2            DPMSModeSuspend     Blanked,   lower    power
  3            DPMSModeOff         Shut off, awaiting activ-
ity


22..  DDPPMMSS FFuunnccttiioonnss



Bool DPMSQueryExtension (_d_i_s_p_l_a_y_, _e_v_e_n_t___b_a_s_e_, _e_r_r_o_r___b_a_s_e)

         Display _*_d_i_s_p_l_a_y_;
         int _*_e_v_e_n_t___b_a_s_e_, _*_e_r_r_o_r___b_a_s_e_;

_d_i_s_p_l_a_y   Specifies the connection to the X server.
_e_v_e_n_t___b_a_s_e     Specifies  the  return   location   for   the
assigned base event
_e_r_r_o_r___b_a_s_e     Specifies   the   return   location  for  the
assigned base error

-----------
1. _X _W_i_n_d_o_w _S_y_s_t_e_m is a trademark of X Consortium,
Inc.



                              11





DDiissppllaayy PPoowweerr MMaannaaggeemmeenntt SSiiggnnaalliinngg ((DDPPMMSS)) EExxtteennssiioonn    DDRRAAFFTT


The DPMSQueryExtension function  queries  the  X  server  to
determine  the  availability  of the DPMS Extension.  If the
extension is  available,  the  return  value  is  TRUE,  and
_e_v_e_n_t___b_a_s_e  and  _e_r_r_o_r___b_a_s_e are set to the base event number
and base error number for the extension, respectively.  Oth-
erwise,  the  return  value  is  FALSE,  and  the  values of
_e_v_e_n_t___b_a_s_e and _e_r_r_o_r___b_a_s_e are undefined.




Status DPMSGetVersion(_d_i_s_p_l_a_y_, _m_a_j_o_r___v_e_r_s_i_o_n_, _m_i_n_o_r___v_e_r_s_i_o_n)

         Display _*_d_i_s_p_l_a_y_;
         int     _*_m_a_j_o_r___v_e_r_s_i_o_n_, _*_m_i_n_o_r___v_e_r_s_i_o_n_;

_d_i_s_p_l_a_y        Specifies the connection to the X server.
_m_a_j_o_r___v_e_r_s_i_o_n  Specifies  the return location for the exten-
sion major version.
_m_i_n_o_r___v_e_r_s_i_o_n  Specifies the return location for the  exten-
sion minor version.


The  DPMSGetVersion function returns the version of the DPMS
extension implemented by  the  X  server.   The  version  is
returned in _m_a_j_o_r___v_e_r_s_i_o_n and _m_i_n_o_r___v_e_r_s_i_o_n.  The major ver-
sion and minor version for this specification  are  '1'  and
'1',  respectively.   The  major version will be incremented
for protocol incompatible changes,  and  the  minor  version
will  be incremented for small, upwardly compatible changes.




Bool DPMSCapable(_d_i_s_p_l_a_y)

         Display _*_d_i_s_p_l_a_y_;

_d_i_s_p_l_a_y   Specifies the connection to the X server.


The DPMSCapable function returns the DPMS capability of  the
X  server, either TRUE (capable of DPMS) or FALSE (incapable
of DPMS).  The capability of an X server  is  implementation
defined.   For example, if a multi-headed  X server is capa-
ble of DPMS on one head, and incapable on another, the truth
value  of this function is defined by the X server implemen-
tation.





Status DPMSSetTimeouts(_d_i_s_p_l_a_y_, _s_t_a_n_d_b_y_, _s_u_s_p_e_n_d_, _o_f_f)



                              22





DDiissppllaayy PPoowweerr MMaannaaggeemmeenntt SSiiggnnaalliinngg ((DDPPMMSS)) EExxtteennssiioonn    DDRRAAFFTT


         Display _*_d_i_s_p_l_a_y_;
         CARD16 _s_t_a_n_d_b_y_, _s_u_s_p_e_n_d_, _o_f_f_;

_d_i_s_p_l_a_y   Specifies the connection to the X server.
_s_t_a_n_d_b_y   Specifies the new standby timeout in seconds.
_s_u_s_p_e_n_d   Specifies the new suspend timeout in seconds.
_o_f_f       Specifies the new off timeout in seconds.


The DPMSSetTimeouts function permits applications to set the
timeout values used by the X server for DPMS timings.

The  value  _s_t_a_n_d_b_y  is  the amount of time of inactivity in
seconds before standby mode is invoked. The  actual  effects
of  this mode are implementation defined, but in the case of
DPMS compliant hardware, it is implemented by  shutting  off
the  horizontal  sync  signal, and pulsing the vertical sync
signal.  Standby mode provides the quickest monitor recovery
time.   Note  also  that  many  monitors implement this mode
identically to suspend mode.  A value of zero disables  this
mode.

The  value  _s_u_s_p_e_n_d  is  the amount of time of inactivity in
seconds before the second level of power savings is invoked.
Suspend  mode's  physical and electrical characteristics are
implementation defined,  but  in  DPMS  compliant  hardware,
results  in  the  pulsing of the horizontal sync signal, and
shutting off of the  vertical  sync  signal.   Suspend  mode
recovery  is  considered to be slower than standby mode, but
faster than off mode, however this is monitor dependent.  As
noted  above,  many monitors implement this mode identically
to standby mode.  A value of zero disables this mode.

The value _o_f_f is the amount of time of inactivity in seconds
before  the  third  and  final  level  of  power  savings is
invoked. Off mode's physical and electrical  characteristics
are  implementation defined, but in DPMS compliant hardware,
is implemented by shutting off both horizontal and  vertical
sync  signals,  resulting  in the power-down of the monitor.
Recovery time is implementation dependant, but frequently is
similar  to  the  power-up  time of the monitor.  A value of
zero disables this mode.

Chronologically, standby mode occurs  before  or  simultane-
ously  with suspend mode, and suspend mode must occur before
or simultaneously with off mode.  Therefore,  non-zero  mode
timeout  values must be greater than or equal to the timeout
values of earlier modes.  If inconsistent  values  are  sup-
plied, a BadValue error will result.








                              33





DDiissppllaayy PPoowweerr MMaannaaggeemmeenntt SSiiggnnaalliinngg ((DDPPMMSS)) EExxtteennssiioonn    DDRRAAFFTT


Bool DPMSGetTimeouts(_d_i_s_p_l_a_y_, _s_t_a_n_d_b_y_, _s_u_s_p_e_n_d_, _o_f_f)

         Display _*_d_i_s_p_l_a_y_;
         CARD16 _*_s_t_a_n_d_b_y_, _*_s_u_s_p_e_n_d_, _*_o_f_f_;

_d_i_s_p_l_a_y   Specifies the connection to the X server.
_s_t_a_n_d_b_y   Specifies  the current standby timeout in seconds.
_s_u_s_p_e_n_d   Specifies the current suspend timeout in  seconds.
_o_f_f       Specifies the current off timeout in seconds.


The  DPMSGetTimeouts  function  retrieves the timeout values
used by the X server for DPMS timings.

The value _s_t_a_n_d_b_y is the amount of  time  of  inactivity  in
seconds  before  standby  mode  is  invoked. A value of zero
indicates that this mode has been disabled.

The value _s_u_s_p_e_n_d is the amount of  time  of  inactivity  in
seconds before the second level of power savings is invoked.
A value of zero indicates that this mode has been  disabled.

The value _o_f_f is the amount of time of inactivity in seconds
before the  third  and  final  level  of  power  savings  is
invoked.  A  value of zero indicates that this mode has been
disabled.





Status DPMSEnable(_d_i_s_p_l_a_y)

         Display _*_d_i_s_p_l_a_y_;

_d_i_s_p_l_a_y   Specifies the connection to the X server.


The DPMSEnable function enables DPMS on the  specified  dis-
play.  When enabled, DPMS will use the currently saved time-
out values, and will invoke the DPMS power mode  appropriate
for  the  amount  of time that the workstation input devices
have been idle.  If DPMSEnable is invoked on a display  with
DPMS  already  enabled,  no  change is made, and no error is
returned.  If DPMSEnable is invoked  on  a  display  without
support  for  DPMS,  no  change  is  made  and  no  error is
returned.





Status DPMSDisable(_d_i_s_p_l_a_y)




                              44





DDiissppllaayy PPoowweerr MMaannaaggeemmeenntt SSiiggnnaalliinngg ((DDPPMMSS)) EExxtteennssiioonn    DDRRAAFFTT


         Display _*_d_i_s_p_l_a_y_;

_d_i_s_p_l_a_y   Specifies the connection to the X server.


The DPMSDisable function disables DPMS on the specified dis-
play.   When  disabled, DPMS returns the display to DPMSMod-
eOn.  If DPMSDisable is  invoked  on  a  display  with  DPMS
already  disabled,  no  change  is  made,  and  no  error is
returned.  If DPMSDisable is invoked on  a  display  without
support  for  DPMS,  no  change  is  made  and  no  error is
returned.





Status DPMSForceLevel(_d_i_s_p_l_a_y_, _l_e_v_e_l)

         Display _*_d_i_s_p_l_a_y_;
         CARD16 _l_e_v_e_l_;

_d_i_s_p_l_a_y   Specifies the connection to the X server.
_l_e_v_e_l     Specifies the level to force power to.


The DPMSForceLevel function forces a  DPMS  capable  display
into  the  specified  power level.  The _l_e_v_e_l must be one of
DPMSModeOn, DPMSModeStandby, DPMSModeSuspend,  or  DPMSMode-
Off.   Values  other  than  these  will result in a BadValue
error.  If DPMS is disabled on the display, a BadMatch  pro-
tocol error will result.





Status DPMSInfo(_d_i_s_p_l_a_y_, _p_o_w_e_r___l_e_v_e_l_, _s_t_a_t_e)

         Display _*_d_i_s_p_l_a_y_;
         CARD16 _*_p_o_w_e_r___l_e_v_e_l_;
         BOOL _*_s_t_a_t_e_;

_d_i_s_p_l_a_y        Specifies the connection to the X server.
_p_o_w_e_r___l_e_v_e_l         Specifies the current power level.
_s_t_a_t_e               Specifies the current DPMS state


The  DPMSInfo function returns information about the current
DPMS state.  The _s_t_a_t_e return parameter indicates whether or
not  DPMS  is  enabled  (TRUE)  or  disabled  (FALSE).   The
_p_o_w_e_r___l_e_v_e_l return parameter  indicates  the  current  power
level  (one of DPMSModeOn, DPMSModeStandby, DPMSModeSuspend,
or DPMSModeOff.)



                              55





DDiissppllaayy PPoowweerr MMaannaaggeemmeenntt SSiiggnnaalliinngg ((DDPPMMSS)) EExxtteennssiioonn    DDRRAAFFTT



























































                              66


