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

    NV-CONTROL X Extension - API specificiation v 1.6


1.  INTRODUCTION

    The NV-CONTROL X extension provides a mechanism for X clients to
    query and set configuration parameters of the NVIDIA X driver.
    State set by the NV-CONTROL X extension is assumed to be persistent
    only for the current server generation.

    Attributes are configurable on a per X screen basis, and some
    attributes are also configurable on a per display device basis.
    Addtionally, some attributes can only be queried, though most can
    be both queried and modified.  The NV-CONTROL extension provides
    a mechanism to determine what values are valid for an attribute,
    if an attribute is read-only, if it can be read and written, if it
    requires a display device qualifier, and if the the attribute is
    available on the specified X screen.

    Finally, NV-CONTROL clients may also request to be notified when an
    attribute is changed by any other NV-CONTROL client.



2.  DISPLAY DEVICES

    A "Display Device" refers to some piece of hardware capable of
    displaying an image.  Display devices are separated into the three
    general categories: analog CRTs, digital flatpanels, and TVs.
    Note that analog flatpanels fall under the category of analog CRTs.

    The NVIDIA X driver allows multiple display devices to display
    portions of the same X screen; this is configured through the
    TwinView feature of the NVIDIA X driver.  TwinView is described in
    the Appendix on TwinView in the NVIDIA Linux driver text README file.
    A consequence of TwinView is that an X screen does not necessarily
    uniquely identify a display device.

    While most attributes controlled by the NV-CONTROL X extension
    apply to an entire X screen, some attributes can be controlled per
    display device.  When querying and assigning such attributes, the
    particular display device is specified via a display device mask.

    A "display device mask" is an unsigned 32 bit value that identifies
    one or more display devices: the first 8 bits each identify a CRT, the
    next 8 bits each identify a TV, and the next 8 each identify a DFP.
    For example, 0x1 refers to CRT-0, 0x3 refers to CRT-0 and CRT-1,
    0x10001 refers to CRT-0 and DFP-0, etc.



3.  QUERYING THE EXTENSION

    NV-CONTROL clients can query for the existence of the NV-CONTROL X
    extension with:

        Bool XNVCTRLQueryExtension (Display *dpy,
                                    int *event_basep, int *error_basep);

    This function returns True if the extension exists, and returns False
    if the extension does not.  It also returns the error and event bases.
    The arguments are:

        dpy - The connection to the X server.
        event_basep - The returned event base.  Currently, only one
                      extension specific event is defined.
        error_basep - The returned error base.  Currently, no extension
                      specific errors are defined.

    The version of the NV-CONTROL extension can be queried with:

        Bool XNVCTRLQueryVersion (Display *dpy, int *major, int *minor);

    This function returns True if the extension exists, and returns
    False if it does not.  It also returns the major and minor version
    numbers of the extension.  The arguments are:

        dpy - The connection to the X server.
        major - The returned major version number of the extension.
        minor - The returned minor version number of the extension.


    You can determine if a particular X screen is controlled by the
    NVIDIA X driver (and thus supports the NV-CONTROL X extension) with:

        Bool XNVCTRLIsNvScreen (Display *dpy, int screen);

    This function returns True if the specified screen is controlled by
    the NVIDIA driver, and thus supports the NV-CONTROL X extension.
    It returns False if the specified screen does not support the
    NV-CONTROL X extension.  The arguments are:

        dpy - The connection to the X server.
        screen - the X screen to query.



4.  QUERYING VALID ATTRIBUTE VALUES

    NV-CONTROL clients can query the valid values for any integer
    attribute with:

        Bool XNVCTRLQueryValidAttributeValues (Display *dpy,
                                               int screen,
                                               unsigned int display_mask,
                                               unsigned int attribute,
                                               NVCTRLAttributeValidValuesRec
                                               *values);

    This function returns True if the attribute exists on the specified
    X screen, or False if the attribute is not available on the specified
    X screen.

    The arguments are:

        dpy - The connection to the X server.
        screen - the X screen to query.
        display_mask - for attributes that can be controlled on a per
                       display device basis, the display_mask should
                       uniquely identify a single display device.
                       This argument is ignored for attributes that
                       apply to the entire X screen.
        attribute - the integer attribute to query
        values - the returned NVCTRLAttributeValidValuesRec structure.

    The NVCTRLAttributeValidValuesRec structure is defined as:

        typedef struct _NVCTRLAttributeValidValues {
            int type;
            union {
                struct {
                    int min;
                    int max;
                } range;
                struct {
                    unsigned int ints;
                } bits;
            } u;
            unsigned int permissions;
        } NVCTRLAttributeValidValuesRec;

    Where type can be one of:

        #define ATTRIBUTE_TYPE_UNKNOWN   0
        #define ATTRIBUTE_TYPE_INTEGER   1
        #define ATTRIBUTE_TYPE_BITMASK   2
        #define ATTRIBUTE_TYPE_BOOL      3
        #define ATTRIBUTE_TYPE_RANGE     4
        #define ATTRIBUTE_TYPE_INT_BITS  5

    ATTRIBUTE_TYPE_INTEGER indicates that the attribute is an integer
    value; any integer may be specified when setting this attribute.

    ATTRIBUTE_TYPE_BITMASK indicates that the attribute is an integer
    value, interpretted as a bitmask.  This is the type, for example,
    of the NV_CTRL_CONNECTED_DISPLAYS attribute.

    ATTRIBUTE_TYPE_BOOL indicates that the attribute is a boolean;
    valid values are 1 (on/true) and 0 (off/false).

    ATTRIBUTE_TYPE_RANGE indicates that the attribute can have any
    integer value between NVCTRLAttributeValidValues.u.range.min and
    NVCTRLAttributeValidValues.u.range.max (inclusive).

    ATTRIBUTE_TYPE_INT_BITS indicates that the attribute can
    only have certain integer values, indicated by which bits in
    NVCTRLAttributeValidValues.u.bits.ints are on (for example: if bit
    0 is on, then 0 is a valid value; if bit 5 is on, then 5 is a valid
    value, etc).  This is the type, for example, of NV_CTRL_FSAA_MODE.


    The permissions field in NVCTRLAttributeValidValuesRec is a bitmask
    that can contain any of:

        #define ATTRIBUTE_TYPE_READ      0x1
        #define ATTRIBUTE_TYPE_WRITE     0x2
        #define ATTRIBUTE_TYPE_DISPLAY   0x4

    ATTRIBUTE_TYPE_READ indicates that the attribute is readable; in
    general, all attributes will be readable.

    ATTRIBUTE_TYPE_WRITE indicates that the attribute is writable;
    attributes may not be writable for various reasons: they represent
    static system information, they can only be changed by changing an
    XF86Config option, etc.

    ATTRIBUTE_TYPE_DISPLAY indicates that the attribute can be
    controlled on a per display device basis, and thus
    XNVCTRLQueryAttribute() and XNVCTRLSetAttribute() require that a
    display device be specified.

    The XNVCTRLQueryValidAttributeValues() function can cause the
    following X protocol errors:

        BadValue - The screen does not exist.
        BadMatch - The NVIDIA driver is not present on that screen.



5.  QUERYING ATTRIBUTE VALUES

    NV-CONTROL clients can query the current value of an integer
    attribute with:

        Bool XNVCTRLQueryAttribute (Display *dpy,
                                    int screen,
                                    unsigned int display_mask,
                                    unsigned int attribute,
                                    int *value);

    This function returns True if the attribute exists, and stores the
    current attribute value in the memory pointed to by the value
    argument.  False is returned if the attribute does not exist on the
    specified X screen.

    The arguments are:

        dpy - The connection to the X server.
        screen - the X screen to query.
        display_mask - if the attribute requires a display device,
                       then this indicates the display device to query;
                       this field is ignored if the attribute is not
                       display device specific.  You can determine
                       if an attribute is display device specific by
                       querying the valid values and checking for the
                       ATTRIBUTE_TYPE_DISPLAY bit in the permissions
                       field.
        attribute - the attribute to query.
        value - the returned attribute value.
    
    This function can cause the following X protocol errors:

        BadValue - The screen does not exist.
        BadMatch - The NVIDIA driver is not present on that screen.


    NV-CONTROL clients can query the read-only string attributes with:

        Bool XNVCTRLQueryStringAttribute (Display *dpy,
                                          int screen,
                                          unsigned int display_mask,
                                          unsigned int attribute,
                                          char **ptr);

    This function returns True if the string attribute exists;
    or it returns False if the string attribute does not exist. If
    XNVCTRLQueryStringAttribute returns True, *ptr will point to an
    allocated string containing the string attribute requested.  It is
    the caller's responsibility to free the string with XFree().

    The arguments are:

        dpy - The connection to the X server.
        screen - the X screen to query.
        display_mask - if the attribute requires a display device,
                       then this indicates the display device to query;
                       this field is ignored if the attribute is not
                       display device specific.
        attribute - the string attribute to query
        ptr - the returned allocated string

    This function can cause the following X protocol errors:

        BadValue - The screen does not exist.
        BadMatch - The NVIDIA driver is not present on that screen.
        BadAlloc - Insufficient resources to fulfill the request.
        
    See NVCtrl.h (distributed in the src/libXNVCtrl/ directory of
    the nvidia-settings source package) for a list of possible string
    attributes.



6.  ASSIGNING ATTRIBUTE VALUES

    An integer attribute can be assigned a value with:

        void XNVCTRLSetAttribute (Display *dpy,
                                  int screen,
                                  unsigned int display_mask,
                                  unsigned int attribute,
                                  int value);

    This function sets the attribute to the given value.  This function
    does not have a return value.  Note that, because it does not
    return a value, XNVCTRLSetAttribute() only queues the request in
    the X command stream.  The command will not actually be sent to
    the server until an X command that flushes the X command stream
    (such as XFlush(), or any API command that queries a value from the
    server) is called.

    The arguments are:

        dpy - The connection to the X server.
        screen - the X screen to query.
        display_mask - if the attribute requires a display device,
                       then this indicates the display device to set;
                       this field is ignored if the attribute is not
                       display device specific.  You can determine
                       if an attribute is display device specific by
                       querying the valid values and checking for the
                       ATTRIBUTE_TYPE_DISPLAY bit in the permissions
                       field.
        attribute - the attribute to set.
        value - the value the attribute should be set to.

    See NVCtrl.h (distributed in the src/libXNVCtrl/ directory of
    the nvidia-settings source package) for a list of possible integer
    attributes.

    This function can cause the following X protocol errors:

        BadMatch - The NVIDIA driver is not present on that screen.
        BadValue - The screen does not exist, or an invalid value is
                   specified, or the attribute does not exist on the
                   specified X screen, or the attribute requires a
                   display device and display_mask does not uniquely
                   identify a display device.

    Before calling XNVCTRLSetAttribute(), an NV-CONTROL client should
    use XNVCTRLQueryAttribute() or XNVCTRLQueryValidAttributeValues()
    to determine if the attribute exists on the specified X screen;
    if the attribute does not exist and XNVCTRLSetAttribute()
    is called for that attribute, then a BadValue X protocol error will
    be triggered.



7.  SELECTING EVENT NOTIFICATION

    NV-CONTROL clients can enable NV-CONTROL events with:

        Bool XNVCtrlSelectNotify (Display *dpy,
                                  int screen,
                                  int type,
                                  Bool onoff);

    This function returns True if the extension exists, or False if the
    extension does not exist.  The arguments are:

        dpy - The connection to the X server.
        screen - the X screen on which to enable events.
        type - the type of event to enable; currently, the only NV-CONTROL
               event type is ATTRIBUTE_CHANGED_EVENT.
        onoff - whether to enable (True) or disable (False) receiving
                this event type.

    This function can cause the following X protocol errors:

        BadValue - The screen does not exist.
        BadMatch - The NVIDIA driver is not present on that screen.

    When an NV-CONTROL client changes an integer attribute value, all
    other NV-CONTROL clients with ATTRIBUTE_CHANGED_EVENT notificaion
    enabled will receive an XEvent where XEvent.type is equal to:

        event_base + ATTRIBUTE_CHANGED_EVENT

    where event_base is the event base returned by
    XNVCTRLQueryExtension().  The XEvent can then be cast as an
    XNVCtrlAttributeChangedEvent structure:

        typedef struct {
            int type;
            unsigned long serial;
            Bool send_event;  /* always FALSE, we don't allow send_events */
            Display *display;
            Time time;
            int screen;
            unsigned int display_mask;
            unsigned int attribute;
            int value;
        } XNVCtrlAttributeChangedEvent;

    The screen, display_mask, attribute, and value fields correspond to
    the arguments passed to XNVCTRLSetAttribute().



8. NV-CONTROL EXTENSION HISTORY

    1.0 - 1.5   NVIDIA Internal development versions
    1.6         Initial public version