neo/sys/linux/libXNVCtrl/NV-CONTROL-API.txt

   1
   2     NV-CONTROL X Extension - API specificiation v 1.6
   3
   4
   5 1.  INTRODUCTION
   6
   7     The NV-CONTROL X extension provides a mechanism for X clients to
   8     query and set configuration parameters of the NVIDIA X driver.
   9     State set by the NV-CONTROL X extension is assumed to be persistent
  10     only for the current server generation.
  11
  12     Attributes are configurable on a per X screen basis, and some
  13     attributes are also configurable on a per display device basis.
  14     Addtionally, some attributes can only be queried, though most can
  15     be both queried and modified.  The NV-CONTROL extension provides
  16     a mechanism to determine what values are valid for an attribute,
  17     if an attribute is read-only, if it can be read and written, if it
  18     requires a display device qualifier, and if the the attribute is
  19     available on the specified X screen.
  20
  21     Finally, NV-CONTROL clients may also request to be notified when an
  22     attribute is changed by any other NV-CONTROL client.
  23
  24
  25
  26 2.  DISPLAY DEVICES
  27
  28     A "Display Device" refers to some piece of hardware capable of
  29     displaying an image.  Display devices are separated into the three
  30     general categories: analog CRTs, digital flatpanels, and TVs.
  31     Note that analog flatpanels fall under the category of analog CRTs.
  32
  33     The NVIDIA X driver allows multiple display devices to display
  34     portions of the same X screen; this is configured through the
  35     TwinView feature of the NVIDIA X driver.  TwinView is described in
  36     the Appendix on TwinView in the NVIDIA Linux driver text README file.
  37     A consequence of TwinView is that an X screen does not necessarily
  38     uniquely identify a display device.
  39
  40     While most attributes controlled by the NV-CONTROL X extension
  41     apply to an entire X screen, some attributes can be controlled per
  42     display device.  When querying and assigning such attributes, the
  43     particular display device is specified via a display device mask.
  44
  45     A "display device mask" is an unsigned 32 bit value that identifies
  46     one or more display devices: the first 8 bits each identify a CRT, the
  47     next 8 bits each identify a TV, and the next 8 each identify a DFP.
  48     For example, 0x1 refers to CRT-0, 0x3 refers to CRT-0 and CRT-1,
  49     0x10001 refers to CRT-0 and DFP-0, etc.
  50
  51
  52
  53 3.  QUERYING THE EXTENSION
  54
  55     NV-CONTROL clients can query for the existence of the NV-CONTROL X
  56     extension with:
  57
  58         Bool XNVCTRLQueryExtension (Display *dpy,
  59                                     int *event_basep, int *error_basep);
  60
  61     This function returns True if the extension exists, and returns False
  62     if the extension does not.  It also returns the error and event bases.
  63     The arguments are:
  64
  65         dpy - The connection to the X server.
  66         event_basep - The returned event base.  Currently, only one
  67                       extension specific event is defined.
  68         error_basep - The returned error base.  Currently, no extension
  69                       specific errors are defined.
  70
  71     The version of the NV-CONTROL extension can be queried with:
  72
  73         Bool XNVCTRLQueryVersion (Display *dpy, int *major, int *minor);
  74
  75     This function returns True if the extension exists, and returns
  76     False if it does not.  It also returns the major and minor version
  77     numbers of the extension.  The arguments are:
  78
  79         dpy - The connection to the X server.
  80         major - The returned major version number of the extension.
  81         minor - The returned minor version number of the extension.
  82
  83
  84     You can determine if a particular X screen is controlled by the
  85     NVIDIA X driver (and thus supports the NV-CONTROL X extension) with:
  86
  87         Bool XNVCTRLIsNvScreen (Display *dpy, int screen);
  88
  89     This function returns True if the specified screen is controlled by
  90     the NVIDIA driver, and thus supports the NV-CONTROL X extension.
  91     It returns False if the specified screen does not support the
  92     NV-CONTROL X extension.  The arguments are:
  93
  94         dpy - The connection to the X server.
  95         screen - the X screen to query.
  96
  97
  98
  99 4.  QUERYING VALID ATTRIBUTE VALUES
 100
 101     NV-CONTROL clients can query the valid values for any integer
 102     attribute with:
 103
 104         Bool XNVCTRLQueryValidAttributeValues (Display *dpy,
 105                                                int screen,
 106                                                unsigned int display_mask,
 107                                                unsigned int attribute,
 108                                                NVCTRLAttributeValidValuesRec
 109                                                *values);
 110
 111     This function returns True if the attribute exists on the specified
 112     X screen, or False if the attribute is not available on the specified
 113     X screen.
 114
 115     The arguments are:
 116
 117         dpy - The connection to the X server.
 118         screen - the X screen to query.
 119         display_mask - for attributes that can be controlled on a per
 120                        display device basis, the display_mask should
 121                        uniquely identify a single display device.
 122                        This argument is ignored for attributes that
 123                        apply to the entire X screen.
 124         attribute - the integer attribute to query
 125         values - the returned NVCTRLAttributeValidValuesRec structure.
 126
 127     The NVCTRLAttributeValidValuesRec structure is defined as:
 128
 129         typedef struct _NVCTRLAttributeValidValues {
 130             int type;
 131             union {
 132                 struct {
 133                     int min;
 134                     int max;
 135                 } range;
 136                 struct {
 137                     unsigned int ints;
 138                 } bits;
 139             } u;
 140             unsigned int permissions;
 141         } NVCTRLAttributeValidValuesRec;
 142
 143     Where type can be one of:
 144
 145         #define ATTRIBUTE_TYPE_UNKNOWN   0
 146         #define ATTRIBUTE_TYPE_INTEGER   1
 147         #define ATTRIBUTE_TYPE_BITMASK   2
 148         #define ATTRIBUTE_TYPE_BOOL      3
 149         #define ATTRIBUTE_TYPE_RANGE     4
 150         #define ATTRIBUTE_TYPE_INT_BITS  5
 151
 152     ATTRIBUTE_TYPE_INTEGER indicates that the attribute is an integer
 153     value; any integer may be specified when setting this attribute.
 154
 155     ATTRIBUTE_TYPE_BITMASK indicates that the attribute is an integer
 156     value, interpretted as a bitmask.  This is the type, for example,
 157     of the NV_CTRL_CONNECTED_DISPLAYS attribute.
 158
 159     ATTRIBUTE_TYPE_BOOL indicates that the attribute is a boolean;
 160     valid values are 1 (on/true) and 0 (off/false).
 161
 162     ATTRIBUTE_TYPE_RANGE indicates that the attribute can have any
 163     integer value between NVCTRLAttributeValidValues.u.range.min and
 164     NVCTRLAttributeValidValues.u.range.max (inclusive).
 165
 166     ATTRIBUTE_TYPE_INT_BITS indicates that the attribute can
 167     only have certain integer values, indicated by which bits in
 168     NVCTRLAttributeValidValues.u.bits.ints are on (for example: if bit
 169     0 is on, then 0 is a valid value; if bit 5 is on, then 5 is a valid
 170     value, etc).  This is the type, for example, of NV_CTRL_FSAA_MODE.
 171
 172
 173     The permissions field in NVCTRLAttributeValidValuesRec is a bitmask
 174     that can contain any of:
 175
 176         #define ATTRIBUTE_TYPE_READ      0x1
 177         #define ATTRIBUTE_TYPE_WRITE     0x2
 178         #define ATTRIBUTE_TYPE_DISPLAY   0x4
 179
 180     ATTRIBUTE_TYPE_READ indicates that the attribute is readable; in
 181     general, all attributes will be readable.
 182
 183     ATTRIBUTE_TYPE_WRITE indicates that the attribute is writable;
 184     attributes may not be writable for various reasons: they represent
 185     static system information, they can only be changed by changing an
 186     XF86Config option, etc.
 187
 188     ATTRIBUTE_TYPE_DISPLAY indicates that the attribute can be
 189     controlled on a per display device basis, and thus
 190     XNVCTRLQueryAttribute() and XNVCTRLSetAttribute() require that a
 191     display device be specified.
 192
 193     The XNVCTRLQueryValidAttributeValues() function can cause the
 194     following X protocol errors:
 195
 196         BadValue - The screen does not exist.
 197         BadMatch - The NVIDIA driver is not present on that screen.
 198
 199
 200
 201 5.  QUERYING ATTRIBUTE VALUES
 202
 203     NV-CONTROL clients can query the current value of an integer
 204     attribute with:
 205
 206         Bool XNVCTRLQueryAttribute (Display *dpy,
 207                                     int screen,
 208                                     unsigned int display_mask,
 209                                     unsigned int attribute,
 210                                     int *value);
 211
 212     This function returns True if the attribute exists, and stores the
 213     current attribute value in the memory pointed to by the value
 214     argument.  False is returned if the attribute does not exist on the
 215     specified X screen.
 216
 217     The arguments are:
 218
 219         dpy - The connection to the X server.
 220         screen - the X screen to query.
 221         display_mask - if the attribute requires a display device,
 222                        then this indicates the display device to query;
 223                        this field is ignored if the attribute is not
 224                        display device specific.  You can determine
 225                        if an attribute is display device specific by
 226                        querying the valid values and checking for the
 227                        ATTRIBUTE_TYPE_DISPLAY bit in the permissions
 228                        field.
 229         attribute - the attribute to query.
 230         value - the returned attribute value.
 231
 232     This function can cause the following X protocol errors:
 233
 234         BadValue - The screen does not exist.
 235         BadMatch - The NVIDIA driver is not present on that screen.
 236
 237
 238     NV-CONTROL clients can query the read-only string attributes with:
 239
 240         Bool XNVCTRLQueryStringAttribute (Display *dpy,
 241                                           int screen,
 242                                           unsigned int display_mask,
 243                                           unsigned int attribute,
 244                                           char **ptr);
 245
 246     This function returns True if the string attribute exists;
 247     or it returns False if the string attribute does not exist. If
 248     XNVCTRLQueryStringAttribute returns True, *ptr will point to an
 249     allocated string containing the string attribute requested.  It is
 250     the caller's responsibility to free the string with XFree().
 251
 252     The arguments are:
 253
 254         dpy - The connection to the X server.
 255         screen - the X screen to query.
 256         display_mask - if the attribute requires a display device,
 257                        then this indicates the display device to query;
 258                        this field is ignored if the attribute is not
 259                        display device specific.
 260         attribute - the string attribute to query
 261         ptr - the returned allocated string
 262
 263     This function can cause the following X protocol errors:
 264
 265         BadValue - The screen does not exist.
 266         BadMatch - The NVIDIA driver is not present on that screen.
 267         BadAlloc - Insufficient resources to fulfill the request.
 268
 269     See NVCtrl.h (distributed in the src/libXNVCtrl/ directory of
 270     the nvidia-settings source package) for a list of possible string
 271     attributes.
 272
 273
 274
 275 6.  ASSIGNING ATTRIBUTE VALUES
 276
 277     An integer attribute can be assigned a value with:
 278
 279         void XNVCTRLSetAttribute (Display *dpy,
 280                                   int screen,
 281                                   unsigned int display_mask,
 282                                   unsigned int attribute,
 283                                   int value);
 284
 285     This function sets the attribute to the given value.  This function
 286     does not have a return value.  Note that, because it does not
 287     return a value, XNVCTRLSetAttribute() only queues the request in
 288     the X command stream.  The command will not actually be sent to
 289     the server until an X command that flushes the X command stream
 290     (such as XFlush(), or any API command that queries a value from the
 291     server) is called.
 292
 293     The arguments are:
 294
 295         dpy - The connection to the X server.
 296         screen - the X screen to query.
 297         display_mask - if the attribute requires a display device,
 298                        then this indicates the display device to set;
 299                        this field is ignored if the attribute is not
 300                        display device specific.  You can determine
 301                        if an attribute is display device specific by
 302                        querying the valid values and checking for the
 303                        ATTRIBUTE_TYPE_DISPLAY bit in the permissions
 304                        field.
 305         attribute - the attribute to set.
 306         value - the value the attribute should be set to.
 307
 308     See NVCtrl.h (distributed in the src/libXNVCtrl/ directory of
 309     the nvidia-settings source package) for a list of possible integer
 310     attributes.
 311
 312     This function can cause the following X protocol errors:
 313
 314         BadMatch - The NVIDIA driver is not present on that screen.
 315         BadValue - The screen does not exist, or an invalid value is
 316                    specified, or the attribute does not exist on the
 317                    specified X screen, or the attribute requires a
 318                    display device and display_mask does not uniquely
 319                    identify a display device.
 320
 321     Before calling XNVCTRLSetAttribute(), an NV-CONTROL client should
 322     use XNVCTRLQueryAttribute() or XNVCTRLQueryValidAttributeValues()
 323     to determine if the attribute exists on the specified X screen;
 324     if the attribute does not exist and XNVCTRLSetAttribute()
 325     is called for that attribute, then a BadValue X protocol error will
 326     be triggered.
 327
 328
 329
 330 7.  SELECTING EVENT NOTIFICATION
 331
 332     NV-CONTROL clients can enable NV-CONTROL events with:
 333
 334         Bool XNVCtrlSelectNotify (Display *dpy,
 335                                   int screen,
 336                                   int type,
 337                                   Bool onoff);
 338
 339     This function returns True if the extension exists, or False if the
 340     extension does not exist.  The arguments are:
 341
 342         dpy - The connection to the X server.
 343         screen - the X screen on which to enable events.
 344         type - the type of event to enable; currently, the only NV-CONTROL
 345                event type is ATTRIBUTE_CHANGED_EVENT.
 346         onoff - whether to enable (True) or disable (False) receiving
 347                 this event type.
 348
 349     This function can cause the following X protocol errors:
 350
 351         BadValue - The screen does not exist.
 352         BadMatch - The NVIDIA driver is not present on that screen.
 353
 354     When an NV-CONTROL client changes an integer attribute value, all
 355     other NV-CONTROL clients with ATTRIBUTE_CHANGED_EVENT notificaion
 356     enabled will receive an XEvent where XEvent.type is equal to:
 357
 358         event_base + ATTRIBUTE_CHANGED_EVENT
 359
 360     where event_base is the event base returned by
 361     XNVCTRLQueryExtension().  The XEvent can then be cast as an
 362     XNVCtrlAttributeChangedEvent structure:
 363
 364         typedef struct {
 365             int type;
 366             unsigned long serial;
 367             Bool send_event;  /* always FALSE, we don't allow send_events */
 368             Display *display;
 369             Time time;
 370             int screen;
 371             unsigned int display_mask;
 372             unsigned int attribute;
 373             int value;
 374         } XNVCtrlAttributeChangedEvent;
 375
 376     The screen, display_mask, attribute, and value fields correspond to
 377     the arguments passed to XNVCTRLSetAttribute().
 378
 379
 380
 381 8. NV-CONTROL EXTENSION HISTORY
 382
 383     1.0 - 1.5   NVIDIA Internal development versions
 384     1.6         Initial public version
 385