diff options
Diffstat (limited to 'doc/NV-CONTROL-API.txt')
| -rw-r--r-- | doc/NV-CONTROL-API.txt | 385 |
1 files changed, 385 insertions, 0 deletions
diff --git a/doc/NV-CONTROL-API.txt b/doc/NV-CONTROL-API.txt new file mode 100644 index 0000000..f8f43af --- /dev/null +++ b/doc/NV-CONTROL-API.txt @@ -0,0 +1,385 @@ + + 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 + |