path: root/src/libXNVCtrl/NVCtrlLib.h

/*
 * Copyright (c) 2008 NVIDIA, Corporation
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice (including the next
 * paragraph) shall be included in all copies or substantial portions of the
 * Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

#ifndef __NVCTRLLIB_H
#define __NVCTRLLIB_H

#include "NVCtrl.h"

#if defined __cplusplus
extern "C" {
#endif 

/*
 *  XNVCTRLQueryExtension -
 *
 *  Returns True if the extension exists, returns False otherwise.
 *  event_basep and error_basep are the extension event and error
 *  bases.  Currently, no extension specific errors or events are
 *  defined.
 */

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


/*
 *  XNVCTRLQueryVersion -
 *
 *  Returns True if the extension exists, returns False otherwise.
 *  major and minor are the extension's major and minor version
 *  numbers.
 */

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


/*
 *  XNVCTRLIsNvScreen
 *
 *  Returns True is the specified screen is controlled by the NVIDIA
 *  driver.  Returns False otherwise.
 */

Bool XNVCTRLIsNvScreen (
    Display *dpy,
    int screen
);


/*
 *  XNVCTRLQueryTargetCount -
 *
 *  Returns True if the target type exists.  Returns False otherwise.
 *  If XNVCTRLQueryTargetCount returns True, value will contain the
 *  count of existing targets on the server of the specified target
 *  type.
 *
 *  Please see "Attribute Targets" in NVCtrl.h for the list of valid
 *  target types.
 *
 *  Possible errors:
 *     BadValue - The target doesn't exist.
 */

Bool XNVCTRLQueryTargetCount (
    Display *dpy,
    int target_type,
    int *value
);


/*
 *  XNVCTRLSetAttribute -
 *
 *  Sets the attribute to the given value.  The attributes and their
 *  possible values are listed in NVCtrl.h.
 *
 *  Not all attributes require the display_mask parameter; see
 *  NVCtrl.h for details.
 *
 *  Calling this function is equivalent to calling XNVCTRLSetTargetAttribute()
 *  with the target_type set to NV_CTRL_TARGET_TYPE_X_SCREEN and
 *  target_id set to 'screen'.
 *
 *  Possible errors:
 *     BadValue - The screen or attribute doesn't exist.
 *     BadMatch - The NVIDIA driver is not present on that screen.
 */

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


/*
 *  XNVCTRLSetTargetAttribute -
 *
 *  Sets the attribute to the given value.  The attributes and their
 *  possible values are listed in NVCtrl.h.
 *
 *  Not all attributes require the display_mask parameter; see
 *  NVCtrl.h for details.
 *
 *  Possible errors:
 *     BadValue - The target or attribute doesn't exist.
 *     BadMatch - The NVIDIA driver is not present on that target.
 */

void XNVCTRLSetTargetAttribute (
    Display *dpy,
    int target_type,
    int target_id,
    unsigned int display_mask,
    unsigned int attribute,
    int value
);


/*
 *  XNVCTRLSetAttributeAndGetStatus -
 *
 * Same as XNVCTRLSetAttribute().
 * In addition, XNVCTRLSetAttributeAndGetStatus() returns 
 * True if the operation succeeds, False otherwise.
 *
 */

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


/*
 *  XNVCTRLSetTargetAttributeAndGetStatus -
 *
 * Same as XNVCTRLSetTargetAttribute().
 * In addition, XNVCTRLSetTargetAttributeAndGetStatus() returns 
 * True if the operation succeeds, False otherwise.
 *
 */

Bool XNVCTRLSetTargetAttributeAndGetStatus (
    Display *dpy,
    int target_type,
    int target_id,
    unsigned int display_mask,
    unsigned int attribute,
    int value
);


/*
 *  XNVCTRLQueryAttribute -
 *
 *  Returns True if the attribute exists.  Returns False otherwise.
 *  If XNVCTRLQueryAttribute returns True, value will contain the
 *  value of the specified attribute.
 *
 *  Not all attributes require the display_mask parameter; see
 *  NVCtrl.h for details.
 *
 *  Calling this function is equivalent to calling
 *  XNVCTRLQueryTargetAttribute() with the target_type set to
 *  NV_CTRL_TARGET_TYPE_X_SCREEN and target_id set to 'screen'.
 *
 *  Possible errors:
 *     BadValue - The screen doesn't exist.
 *     BadMatch - The NVIDIA driver is not present on that screen.
 */

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


/*
 * XNVCTRLQueryTargetAttribute -
 *
 *  Returns True if the attribute exists.  Returns False otherwise.
 *  If XNVCTRLQueryTargetAttribute returns True, value will contain the
 *  value of the specified attribute.
 *
 *  Not all attributes require the display_mask parameter; see
 *  NVCtrl.h for details.
 *
 *  Possible errors:
 *     BadValue - The target doesn't exist.
 *     BadMatch - The NVIDIA driver does not control the target.
 */

Bool XNVCTRLQueryTargetAttribute (
    Display *dpy,
    int target_Type,
    int target_id,
    unsigned int display_mask,
    unsigned int attribute,
    int *value
);


/*
 * XNVCTRLQueryTargetAttribute64 -
 *
 *  Returns True if the attribute exists.  Returns False otherwise.
 *  If XNVCTRLQueryTargetAttribute returns True, value will contain the
 *  value of the specified attribute.
 *
 *  Not all attributes require the display_mask parameter; see
 *  NVCtrl.h for details.
 *
 *  Note: this function behaves like XNVCTRLQueryTargetAttribute(),
 *  but supports 64-bit integer attributes.
 *
 *  Possible errors:
 *     BadValue - The target doesn't exist.
 *     BadMatch - The NVIDIA driver does not control the target.
 */

Bool XNVCTRLQueryTargetAttribute64 (
    Display *dpy,
    int target_Type,
    int target_id,
    unsigned int display_mask,
    unsigned int attribute,
    int64_t *value
);


/*
 *  XNVCTRLQueryStringAttribute -
 *
 *  Returns True if the attribute exists.  Returns False otherwise.
 *  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 when done.
 *
 *  Calling this function is equivalent to calling
 *  XNVCTRLQueryTargetStringAttribute() with the target_type set to
 *  NV_CTRL_TARGET_TYPE_X_SCREEN and target_id set to 'screen'.
 *
 *  Possible errors:
 *     BadValue - The screen doesn't exist.
 *     BadMatch - The NVIDIA driver is not present on that screen.
 *     BadAlloc - Insufficient resources to fulfill the request.
 */

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


/*
 *  XNVCTRLQueryTargetStringAttribute -
 *
 *  Returns True if the attribute exists.  Returns False otherwise.
 *  If XNVCTRLQueryTargetStringAttribute returns True, *ptr will point
 *  to an allocated string containing the string attribute requested.
 *  It is the caller's responsibility to free the string when done.
 *
 *  Possible errors:
 *     BadValue - The target doesn't exist.
 *     BadMatch - The NVIDIA driver does not control the target.
 *     BadAlloc - Insufficient resources to fulfill the request.
 */

Bool XNVCTRLQueryTargetStringAttribute (
    Display *dpy,
    int target_type,
    int target_id,
    unsigned int display_mask,
    unsigned int attribute,
    char **ptr
);


/*
 *  XNVCTRLSetStringAttribute -
 *
 *  Returns True if the operation succeded.  Returns False otherwise.
 *
 *  Possible X errors:
 *     BadValue - The screen doesn't exist.
 *     BadMatch - The NVIDIA driver is not present on that screen.
 *     BadAlloc - Insufficient resources to fulfill the request.
 */
 
Bool XNVCTRLSetStringAttribute (
    Display *dpy,
    int screen,
    unsigned int display_mask,
    unsigned int attribute,
    char *ptr
);


/*
 *  XNVCTRLSetTargetStringAttribute -
 *
 *  Returns True if the operation succeded.  Returns False otherwise.
 *
 *  Possible X errors:
 *     BadValue - The screen doesn't exist.
 *     BadMatch - The NVIDIA driver is not present on that screen.
 *     BadAlloc - Insufficient resources to fulfill the request.
 */
 
Bool XNVCTRLSetTargetStringAttribute (
    Display *dpy,
    int target_type,
    int target_id,
    unsigned int display_mask,
    unsigned int attribute,
    char *ptr
);


/*
 * XNVCTRLQueryValidAttributeValues -
 *
 * Returns True if the attribute exists.  Returns False otherwise.  If
 * XNVCTRLQueryValidAttributeValues returns True, values will indicate
 * the valid values for the specified attribute; see the description
 * of NVCTRLAttributeValidValues in NVCtrl.h.
 *
 *  Calling this function is equivalent to calling
 *  XNVCTRLQueryValidTargetAttributeValues() with the target_type set to
 *  NV_CTRL_TARGET_TYPE_X_SCREEN and target_id set to 'screen'.
 */

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



/*
 * XNVCTRLQueryValidTargetAttributeValues -
 *
 * Returns True if the attribute exists.  Returns False otherwise.  If
 * XNVCTRLQueryValidTargetAttributeValues returns True, values will indicate
 * the valid values for the specified attribute.
 */

Bool XNVCTRLQueryValidTargetAttributeValues (
    Display *dpy,
    int target_type,
    int target_id,
    unsigned int display_mask,
    unsigned int attribute,                                 
    NVCTRLAttributeValidValuesRec *values
);


/*
 * XNVCTRLQueryValidTargetStringAttributeValues -
 *
 * Returns True if the attribute exists.  Returns False otherwise.  If
 * XNVCTRLQueryValidTargetStringAttributeValues returns True, values will
 * indicate the valid values for the specified attribute.
 */

 Bool XNVCTRLQueryValidTargetStringAttributeValues (
    Display *dpy,
    int target_type,
    int target_id,
    unsigned int display_mask,
    unsigned int attribute,
    NVCTRLAttributeValidValuesRec *values
);


/*
 * XNVCTRLQueryAttributePermissions -
 *
 * Returns True if the attribute exists.  Returns False otherwise.  If
 * XNVCTRLQueryAttributePermissions returns True, permissions will
 * indicate the permission flags for the attribute.  It excludes read
 * and write permissions.
 */

Bool XNVCTRLQueryAttributePermissions (
    Display *dpy,
    unsigned int attribute,
    NVCTRLAttributePermissionsRec *permissions
);


/*
 * XNVCTRLQueryStringAttributePermissions -
 *
 * Returns True if the attribute exists.  Returns False otherwise.  If
 * XNVCTRLQueryStringAttributePermissions returns True, permissions will
 * indicate the permission flags for the attribute.
 */

 Bool XNVCTRLQueryStringAttributePermissions (
    Display *dpy,
    unsigned int attribute,
    NVCTRLAttributePermissionsRec *permissions
);


/*
 * XNVCTRLQueryBinaryDataAttributePermissions -
 *
 * Returns True if the attribute exists.  Returns False otherwise.  If
 * XNVCTRLQueryBinaryDataAttributePermissions returns True, permissions
 * will indicate the permission flags for the attribute.
 */

 Bool XNVCTRLQueryBinaryDataAttributePermissions (
    Display *dpy,
    unsigned int attribute,
    NVCTRLAttributePermissionsRec *permissions
);


/*
 * XNVCTRLQueryStringOperationAttributePermissions -
 *
 * Returns True if the attribute exists.  Returns False otherwise.  If
 * XNVCTRLQueryStringOperationAttributePermissions returns True,
 * permissions will indicate the permission flags for the attribute.
 */

 Bool XNVCTRLQueryStringOperationAttributePermissions (
    Display *dpy,
    unsigned int attribute,
    NVCTRLAttributePermissionsRec *permissions
);


/*
 *  XNVCTRLSetGvoColorConversion -
 *
 *  Sets the color conversion matrix, offset, and scale that should be
 *  used for GVO (Graphic to Video Out).
 *
 *  The Color Space Conversion data is ordered like this:
 *
 *   colorMatrix[0][0] // r.Y
 *   colorMatrix[0][1] // g.Y
 *   colorMatrix[0][2] // b.Y
 *
 *   colorMatrix[1][0] // r.Cr
 *   colorMatrix[1][1] // g.Cr
 *   colorMatrix[1][2] // b.Cr
 *
 *   colorMatrix[2][0] // r.Cb
 *   colorMatrix[2][1] // g.Cb
 *   colorMatrix[2][2] // b.Cb
 *
 *   colorOffset[0]    // Y
 *   colorOffset[1]    // Cr
 *   colorOffset[2]    // Cb
 *
 *   colorScale[0]     // Y
 *   colorScale[1]     // Cr
 *   colorScale[2]     // Cb
 *
 *  where the data is used according to the following formulae:
 *
 *   Y  =  colorOffset[0] + colorScale[0] *
 *           (R * colorMatrix[0][0] +
 *            G * colorMatrix[0][1] +
 *            B * colorMatrix[0][2]);
 *
 *   Cr =  colorOffset[1] + colorScale[1] *
 *           (R * colorMatrix[1][0] +
 *            G * colorMatrix[1][1] +
 *            B * colorMatrix[1][2]);
 *
 *   Cb =  colorOffset[2] + colorScale[2] *
 *           (R * colorMatrix[2][0] +
 *            G * colorMatrix[2][1] +
 *            B * colorMatrix[2][2]);
 *
 *  Possible errors:
 *     BadMatch - The NVIDIA driver is not present on that screen.
 *     BadImplementation - GVO is not available on that screen.
 */

void XNVCTRLSetGvoColorConversion (
    Display *dpy,
    int screen,
    float colorMatrix[3][3],
    float colorOffset[3],
    float colorScale[3]
);



/*
 *  XNVCTRLQueryGvoColorConversion -
 *
 *  Retrieves the color conversion matrix and color offset
 *  that are currently being used for GVO (Graphic to Video Out).
 *
 *  The values are ordered within the arrays according to the comments
 *  for XNVCTRLSetGvoColorConversion().
 *
 *  Possible errors:
 *     BadMatch - The NVIDIA driver is not present on that screen.
 *     BadImplementation - GVO is not available on that screen.
 */

Bool XNVCTRLQueryGvoColorConversion (
    Display *dpy,
    int screen,
    float colorMatrix[3][3],
    float colorOffset[3],
    float colorScale[3]
);


/*
 *  XNVCTRLQueryBinaryData -
 *
 *  Returns True if the attribute exists.  Returns False otherwise.
 *  If XNVCTRLQueryBinaryData returns True, *ptr will point to an
 *  allocated block of memory containing the binary data attribute
 *  requested.  It is the caller's responsibility to free the data
 *  when done.  len will list the length of the binary data.
 *
 *  Calling this function is equivalent to calling
 *  XNVCTRLQueryTargetBinaryData() with the target_type set to
 *  NV_CTRL_TARGET_TYPE_X_SCREEN and target_id set to 'screen'.
 *
 *  Possible errors:
 *     BadValue - The screen doesn't exist.
 *     BadMatch - The NVIDIA driver is not present on that screen.
 *     BadAlloc - Insufficient resources to fulfill the request.
 */

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


/*
 * XNVCTRLQueryTargetBinaryData -
 *
 *  Returns True if the attribute exists.  Returns False otherwise.
 *  If XNVCTRLQueryTargetBinaryData returns True, *ptr will point to an
 *  allocated block of memory containing the binary data attribute
 *  requested.  It is the caller's responsibility to free the data
 *  when done.  len will list the length of the binary data.
 *
 *  Possible errors:
 *     BadValue - The target doesn't exist.
 *     BadMatch - The NVIDIA driver does not control the target.
 *     BadAlloc - Insufficient resources to fulfill the request.
 */

Bool XNVCTRLQueryTargetBinaryData (
    Display *dpy,
    int target_type,
    int target_id,
    unsigned int display_mask,
    unsigned int attribute,
    unsigned char **ptr,
    int *len
);


/*
 * XNVCTRLStringOperation -
 *
 * Takes a string as input and returns a Xmalloc'ed string as output.
 * Returns True on success and False on failure.
 */

Bool XNVCTRLStringOperation (
    Display *dpy,
    int target_type,
    int target_id,
    unsigned int display_mask,
    unsigned int attribute,
    char *pIn,
    char **ppOut
);



/*
 * XNVCtrlSelectNotify -
 *
 * This enables/disables receiving of NV-CONTROL events.  The type
 * specifies the type of event to enable (currently, the only
 * type that can be requested per-screen with XNVCtrlSelectNotify()
 * is ATTRIBUTE_CHANGED_EVENT); onoff controls whether receiving this
 * type of event should be enabled (True) or disabled (False).
 *
 * Returns True if successful, or False if the screen is not
 * controlled by the NVIDIA driver.
 */

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


/*
 * XNVCtrlSelectTargetNotify -
 *
 * This enables/disables receiving of NV-CONTROL events that happen on
 * the specified target.  The notify_type specifies the type of event to
 * enable (currently, the only type that can be requested per-target with
 * XNVCtrlSelectTargetNotify() is TARGET_ATTRIBUTE_CHANGED_EVENT); onoff
 * controls whether receiving this type of event should be enabled (True)
 * or disabled (False).
 *
 * Returns True if successful, or False if the target is not
 * controlled by the NVIDIA driver.
 */

Bool XNVCtrlSelectTargetNotify (
    Display *dpy,
    int target_type,
    int target_id,
    int notify_type,
    Bool onoff
);


/*
 * XNVCtrlEvent 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;

typedef union {
    int type;
    XNVCtrlAttributeChangedEvent attribute_changed;
    long pad[24];
} XNVCtrlEvent;


/*
 * XNVCtrlEventTarget structure
 */

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

typedef union {
    int type;
    XNVCtrlAttributeChangedEventTarget attribute_changed;
    long pad[24];
} XNVCtrlEventTarget;


/*
 * XNVCtrlEventTargetAvailability structure
 */

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

typedef union {
    int type;
    XNVCtrlAttributeChangedEventTargetAvailability attribute_changed;
    long pad[24];
} XNVCtrlEventTargetAvailability;


/*
 * XNVCtrlStringEventTarget structure
 */

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

typedef union {
    int type;
    XNVCtrlStringAttributeChangedEventTarget attribute_changed;
    long pad[24];
} XNVCtrlStringEventTarget;



/*
 * XNVCtrlBinaryEventTarget structure
 */

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

typedef union {
    int type;
    XNVCtrlBinaryAttributeChangedEventTarget attribute_changed;
    long pad[24];
} XNVCtrlBinaryEventTarget;

#if defined __cplusplus
} /* extern "C" */
#endif 

#endif /* __NVCTRLLIB_H */