diff options
Diffstat (limited to 'libgamma.h')
| -rw-r--r-- | libgamma.h | 2474 |
1 files changed, 2474 insertions, 0 deletions
diff --git a/libgamma.h b/libgamma.h new file mode 100644 index 0000000..d798f33 --- /dev/null +++ b/libgamma.h @@ -0,0 +1,2474 @@ +/* See LICENSE file for copyright and license details. */ +#ifndef LIBGAMMA_H +#define LIBGAMMA_H + +#include <sys/types.h> +#include <stddef.h> +#include <stdint.h> +#include <stdlib.h> + + +#ifndef __GNUC__ +# define LIBGAMMA_GCC_ONLY__(X) X +#else +# define LIBGAMMA_GCC_ONLY__(X) +#endif + + + +/** + * `errno` has be set with a standard error number + * to indicate the what has gone wrong + */ +#define LIBGAMMA_ERRNO_SET (-1) + +/** + * The selected adjustment method does not exist + * or has been excluded at compile-time + */ +#define LIBGAMMA_NO_SUCH_ADJUSTMENT_METHOD (-2) /* TODO use separate error code if disable at compile-time */ + +/** + * The selected site does not exist + */ +#define LIBGAMMA_NO_SUCH_SITE (-3) + +/** + * The selected partition does not exist + */ +#define LIBGAMMA_NO_SUCH_PARTITION (-4) + +/** + * The selected CRTC does not exist + */ +#define LIBGAMMA_NO_SUCH_CRTC (-5) + +/** + * Counter overflowed when counting the number + * of available items + */ +#define LIBGAMMA_IMPOSSIBLE_AMOUNT (-6) + +/** + * The selected connector is disabled, it does + * not have a CRTC + */ +#define LIBGAMMA_CONNECTOR_DISABLED (-7) + +/** + * The selected CRTC could not be opened, + * reason unknown + */ +#define LIBGAMMA_OPEN_CRTC_FAILED (-8) + +/** + * The CRTC information field is not supported + * by the adjustment method + */ +#define LIBGAMMA_CRTC_INFO_NOT_SUPPORTED (-9) + +/** + * Failed to read the current gamma ramps for + * the selected CRTC, reason unknown + */ +#define LIBGAMMA_GAMMA_RAMP_READ_FAILED (-10) + +/** + * Failed to write the current gamma ramps for + * the selected CRTC, reason unknown + */ +#define LIBGAMMA_GAMMA_RAMP_WRITE_FAILED (-11) + +/** + * The specified ramp sizes does not match the + * ramps sizes returned by the adjustment methods + * in response to the query/command + */ +#define LIBGAMMA_GAMMA_RAMP_SIZE_CHANGED (-12) + +/** + * The specified ramp sizes are not identical + * which is required by the adjustment method + * + * (Only returned in debug mode) + */ +#define LIBGAMMA_MIXED_GAMMA_RAMP_SIZE (-13) + +/** + * The specified ramp sizes are not supported + * by the adjustment method + * + * (Only returned in debug mode) + */ +#define LIBGAMMA_WRONG_GAMMA_RAMP_SIZE (-14) + +/** + * The adjustment method reported that the gamma + * ramps size is 1, or perhaps even zero or negative + */ +#define LIBGAMMA_SINGLETON_GAMMA_RAMP (-15) + +/** + * The adjustment method failed to list + * available CRTC:s, reason unknown + */ +#define LIBGAMMA_LIST_CRTCS_FAILED (-16) + +/** + * Failed to acquire mode resources from the + * adjustment method + */ +#define LIBGAMMA_ACQUIRING_MODE_RESOURCES_FAILED (-17) + +/** + * The adjustment method reported that a negative + * number of partitions exists in the site + */ +#define LIBGAMMA_NEGATIVE_PARTITION_COUNT (-18) + +/** + * The adjustment method reported that a negative + * number of CRTC:s exists in the partition + */ +#define LIBGAMMA_NEGATIVE_CRTC_COUNT (-19) + +/** + * Device cannot be access becauses of + * insufficient permissions + */ +#define LIBGAMMA_DEVICE_RESTRICTED (-20) + +/** + * Device cannot be access, reason unknown + */ +#define LIBGAMMA_DEVICE_ACCESS_FAILED (-21) + +/** + * Device cannot be access, membership of the + * `libgamma_group_gid` (named by `libgamma_group_name` + * (can be `NULL`, if so `errno` may have been set + * to tell why)) is required + */ +#define LIBGAMMA_DEVICE_REQUIRE_GROUP (-22) + +/** + * The graphics card appear to have been removed + */ +#define LIBGAMMA_GRAPHICS_CARD_REMOVED (-23) + +/** + * The state of the requested information is unknown + */ +#define LIBGAMMA_STATE_UNKNOWN (-24) + +/** + * Failed to determine which connector the + * CRTC belongs to + */ +#define LIBGAMMA_CONNECTOR_UNKNOWN (-25) + +/** + * The detected connector type is not listed + * in this library and has to be updated + */ +#define LIBGAMMA_CONNECTOR_TYPE_NOT_RECOGNISED (-26) + +/** + * The detected subpixel order is not listed + * in this library and has to be updated + */ +#define LIBGAMMA_SUBPIXEL_ORDER_NOT_RECOGNISED (-27) + +/** + * The length of the EDID does not match that + * of any supported EDID structure revision + */ +#define LIBGAMMA_EDID_LENGTH_UNSUPPORTED (-28) + +/** + * The magic number in the EDID does not match + * that of any supported EDID structure revision + */ +#define LIBGAMMA_EDID_WRONG_MAGIC_NUMBER (-29) + +/** + * The EDID structure revision used by the + * monitor is not supported + */ +#define LIBGAMMA_EDID_REVISION_UNSUPPORTED (-30) + +/** + * The gamma characteristics field in the EDID + * is left unspecified + * + * (This could be considered a non-error) + */ +#define LIBGAMMA_GAMMA_NOT_SPECIFIED (-31) + +/** + * The checksum in the EDID is incorrect, all + * request information has been provided + * by you cannot count on it + */ +#define LIBGAMMA_EDID_CHECKSUM_ERROR (-32) + +/** + * Both of the errors `LIBGAMMA_GAMMA_NOT_SPECIFIED` + * and `LIBGAMMA_EDID_CHECKSUM_ERROR` have occurred + */ +#define LIBGAMMA_GAMMA_NOT_SPECIFIED_AND_EDID_CHECKSUM_ERROR (-33) + +/** + * Failed to query the gamma ramps size from the + * adjustment method, reason unknown + */ +#define LIBGAMMA_GAMMA_RAMPS_SIZE_QUERY_FAILED (-34) + +/** + * The selected partition could not be opened, + * reason unknown + */ +#define LIBGAMMA_OPEN_PARTITION_FAILED (-35) + +/** + * The selected site could not be opened, + * reason unknown + */ +#define LIBGAMMA_OPEN_SITE_FAILED (-36) + +/** + * Failed to query the adjustment method for + * its protocol version, reason unknown + */ +#define LIBGAMMA_PROTOCOL_VERSION_QUERY_FAILED (-37) + +/** + * The adjustment method's version of its + * protocol is not supported + */ +#define LIBGAMMA_PROTOCOL_VERSION_NOT_SUPPORTED (-38) + +/** + * The adjustment method failed to list + * available partitions, reason unknown + */ +#define LIBGAMMA_LIST_PARTITIONS_FAILED (-39) + +/** + * Partition exists by index, but the partition + * at that index does not exist + */ +#define LIBGAMMA_NULL_PARTITION (-40) + +/** + * There is not monitor connected to the + * connector of the selected CRTC + */ +#define LIBGAMMA_NOT_CONNECTED (-41) + +/** + * Data extraction from a reply from the + * adjustment method failed, reason unknown + */ +#define LIBGAMMA_REPLY_VALUE_EXTRACTION_FAILED (-42) + +/** + * No EDID property was found on the output + */ +#define LIBGAMMA_EDID_NOT_FOUND (-43) + +/** + * Failed to list properties on the output, + * reason unknown + */ +#define LIBGAMMA_LIST_PROPERTIES_FAILED (-44) + +/** + * Failed to query a property's value from + * the output, reason unknown + */ +#define LIBGAMMA_PROPERTY_VALUE_QUERY_FAILED (-45) + +/** + * A request for information on an output + * failed, reason unknown + */ +#define LIBGAMMA_OUTPUT_INFORMATION_QUERY_FAILED (-46) + +/* DEVELOPERS: Remember to update LIBGAMMA_ERROR_MIN below and LIST_ERRORS in common.h when adding errors */ + +/** + * The number of the libgamma error with the + * lowest number in the version of the library + * that the program is compiled against + */ +#define LIBGAMMA_ERROR_MIN (-46) + +/** + * The number of the libgamma error with the + * lowest number in the version of the library + * that the program is linked against + */ +extern const int libgamma_error_min; + + + +/** + * The identifier for the dummy adjustment method + * + * This method can be configured and is useful for + * testing your program's ability to handle errors + */ +#define LIBGAMMA_METHOD_DUMMY 0 + +/** + * The identifier for the adjustment method with + * uses the RandR protocol under the X display server + */ +#define LIBGAMMA_METHOD_X_RANDR 1 + +/** + * The identifier for the adjustment method with + * uses the VidMode protocol under the X display server + * + * This is an older alternative to RandR that can + * work on some drivers that are not supported by RandR, + * however it can only control the primary CRTC per + * screen (partition) + */ +#define LIBGAMMA_METHOD_X_VIDMODE 2 + +/** + * The identifier for the Direct Rendering Manager + * adjustment method that is available in Linux + * (built in to the Linux kernel with a userland + * library for access) and is a part of the + * Direct Rendering Infrastructure. + * + * This adjustment method will work when you are + * in non-graphical mode; however a display server + * cannot be started while this is running, but it + * can be started while a display server is running + */ +#define LIBGAMMA_METHOD_LINUX_DRM 3 + +/** + * The identifier for the Graphics Device Interface + * adjustment method that is available in Windows + * + * This method is not well tested; it can be compiled + * to be available under X.org using a translation layer + */ +#define LIBGAMMA_METHOD_W32_GDI 4 + +/** + * The identifier for the CoreGraphics adjustment + * method that is available in Mac OS X that can + * adjust gamma ramps under the Quartz display server + * + * This method is not well tested; it can be compiled + * to be available under X.org using a translation layer + */ +#define LIBGAMMA_METHOD_QUARTZ_CORE_GRAPHICS 5 + +/* DEVELOPERS: Remember to update LIBGAMMA_METHOD_COUNT below and LIST_METHODS in common.h when adding methods */ + +/** + * The number adjustment methods provided by the + * version this library the program is compiled + * against + * + * This number includes both compile-time enabled + * and compile-time disabled adjustment methods + */ +#define LIBGAMMA_METHOD_COUNT 6 + +/** + * The number adjustment methods provided by the + * version this library the program is linked + * against + * + * This number includes both compile-time enabled + * and compile-time disabled adjustment methods + */ +extern const int libgamma_method_count; + + + +/** + * Types for connectors + */ +typedef enum libgamma_connector_type { + /** + * The adjustment method does not know the connector's type + * + * (This could be considered an error) + */ + LIBGAMMA_CONNECTOR_TYPE_Unknown = 0, + + /** + * Video Graphics Array (VGA) + */ + LIBGAMMA_CONNECTOR_TYPE_VGA, + + /** + * Digital Visual Interface, unknown type + */ + LIBGAMMA_CONNECTOR_TYPE_DVI, + + /** + * Digital Visual Interface, integrated (DVI-I) + */ + LIBGAMMA_CONNECTOR_TYPE_DVII, + + /** + * Digital Visual Interface, digital only (DVI-D) + */ + LIBGAMMA_CONNECTOR_TYPE_DVID, + + /** + * Digital Visual Interface, analogue only (DVI-A) + */ + LIBGAMMA_CONNECTOR_TYPE_DVIA, + + /** + * Composite video + */ + LIBGAMMA_CONNECTOR_TYPE_Composite, + + /** + * Separate Video (S-video) + */ + LIBGAMMA_CONNECTOR_TYPE_SVIDEO, + + /** + * Low-voltage differential signaling (LVDS) + */ + LIBGAMMA_CONNECTOR_TYPE_LVDS, + + /** + * Component video, usually separate cables for each channel + */ + LIBGAMMA_CONNECTOR_TYPE_Component, + + /** + * 9 pin DIN (Deutsches Institut für Normung) connector + */ + LIBGAMMA_CONNECTOR_TYPE_9PinDIN, + + /** + * DisplayPort + */ + LIBGAMMA_CONNECTOR_TYPE_DisplayPort, + + /** + * High-Definition Multimedia Interface (HDMI), unknown type + */ + LIBGAMMA_CONNECTOR_TYPE_HDMI, + + /** + * High-Definition Multimedia Interface, type A (HDMI-A) + */ + LIBGAMMA_CONNECTOR_TYPE_HDMIA, + + /** + * High-Definition Multimedia Interface, type B (HDMI-B) + */ + LIBGAMMA_CONNECTOR_TYPE_HDMIB, + + /** + * Television, unknown connector + */ + LIBGAMMA_CONNECTOR_TYPE_TV, + + /** + * Embedded DisplayPort (eDP) + */ + LIBGAMMA_CONNECTOR_TYPE_eDP, + + /** + * A virtual connector + */ + LIBGAMMA_CONNECTOR_TYPE_VIRTUAL, + + /** + * Display Serial Interface (DSI) + */ + LIBGAMMA_CONNECTOR_TYPE_DSI, + + /** + * LFP connector + * + * (What is this?) + */ + LIBGAMMA_CONNECTOR_TYPE_LFP + + /* DEVELOPERS: Remember to update LIBGAMMA_CONNECTOR_TYPE_COUNT below + * and LIST_CONNECTOR_TYPES in common.h when adding methods */ + +} libgamma_connector_type_t; + +/** + * The number of values defined in `libgamma_connector_type_t` + * in the version of the library the program is compiled against + */ +#define LIBGAMMA_CONNECTOR_TYPE_COUNT 20 + +/** + * The number of values defined in `libgamma_connector_type_t` + * in the version of the library the program is linked against + */ +extern const int libgamma_connector_type_count; + + + +/** + * Orders for subpixels + * + * Currently the possible values are very biased + * to LCD, Plasma and monochrome monitors + */ +typedef enum libgamma_subpixel_order { + /** + * The adjustment method does not know the order of the subpixels + * + * (This could be considered an error) + */ + LIBGAMMA_SUBPIXEL_ORDER_UNKNOWN = 0, + + /** + * There are no subpixels in the monitor + */ + LIBGAMMA_SUBPIXEL_ORDER_NONE, + + /** + * The subpixels are ordered red, green and then blue, from left to right + */ + LIBGAMMA_SUBPIXEL_ORDER_HORIZONTAL_RGB, + + /** + * The subpixels are ordered blue, green and then red, from left to right + */ + LIBGAMMA_SUBPIXEL_ORDER_HORIZONTAL_BGR, + + /** + * The subpixels are ordered red, green and then blue, from the top down + */ + LIBGAMMA_SUBPIXEL_ORDER_VERTICAL_RGB, + + /** + * The subpixels are ordered blue, green and then red, from the top down + */ + LIBGAMMA_SUBPIXEL_ORDER_VERTICAL_BGR + + /* DEVELOPERS: Remember to update LIBGAMMA_SUBPIXEL_ORDER_COUNT below + * and LIST_SUBPIXEL_ORDERS in common.h when adding methods */ + +} libgamma_subpixel_order_t; + +/** + * The number of values defined in `libgamma_subpixel_order_t` + * in the version of the library the program is compiled against + */ +#define LIBGAMMA_SUBPIXEL_ORDER_COUNT 6 + +/** + * The number of values defined in `libgamma_subpixel_order_t` + * in the version of the library the program is linked against + */ +extern const int libgamma_subpixel_order_count; + + + +/** + * Answer enum to a decision problem + */ +typedef enum libgamma_decision { + /** + * The answer is negative + */ + LIBGAMMA_NO = 0, + + /** + * The answer is unknown + */ + LIBGAMMA_MAYBE = 1, + + /** + * The answer is positive + */ + LIBGAMMA_YES = 2 + +} libgamma_decision_t; + + + +/** + * Capabilities of adjustment methods + */ +typedef struct libgamma_method_capabilities { + /** + * OR of the CRTC information fields in `libgamma_crtc_information_t` + * that may (but can fail) be read successfully + */ + int32_t crtc_information; + + /** + * Whether the default site is known, if true the site is integrated + * to the system or can be determined using environment variables + */ + unsigned default_site_known : 1; + + /** + * Whether the adjustment method supports multiple sites rather + * than just the default site + */ + unsigned multiple_sites : 1; + + /** + * Whether the adjustment method supports multiple partitions + * per site + */ + unsigned multiple_partitions : 1; + + /** + * Whether the adjustment method supports multiple CRTC:s + * per partition per site + */ + unsigned multiple_crtcs : 1; + + /** + * Whether the partition to graphics card is a bijection + */ + unsigned partitions_are_graphics_cards : 1; + + /** + * Whether the adjustment method supports `libgamma_site_restore` + */ + unsigned site_restore : 1; + + /** + * Whether the adjustment method supports `libgamma_partition_restore` + */ + unsigned partition_restore : 1; + + /** + * Whether the adjustment method supports `libgamma_crtc_restore` + */ + unsigned crtc_restore : 1; + + /** + * Whether the `red_gamma_size`, `green_gamma_size` and `blue_gamma_size` + * fields in `libgamma_crtc_information_t` will always have the same + * values as each other for the adjustment method + */ + unsigned identical_gamma_sizes : 1; + + /** + * Whether the `red_gamma_size`, `green_gamma_size` and `blue_gamma_size` + * fields in `libgamma_crtc_information_t` will always be filled with the + * same value for the adjustment method + */ + unsigned fixed_gamma_size : 1; + + /** + * Whether the `gamma_depth` field in `libgamma_crtc_information_t` + * will always be filled with the same value for the adjustment method + */ + unsigned fixed_gamma_depth : 1; + + /** + * Whether the adjustment method will actually perform adjustments + */ + unsigned real : 1; + + /** + * Whether the adjustment method is implement using a translation layer + */ + unsigned fake : 1; + + /** + * Whether adjustments are undone when the process disconnects from + * the display server + */ + unsigned auto_restore : 1; + +} libgamma_method_capabilities_t; + + +/** + * Site state + * + * On operating systems that integrate a graphical environment + * there is usually just one site. However, one systems with + * pluggable graphics, like Unix-like systems such as GNU/Linux + * and the BSD:s, there can usually be any (feasible) number of + * sites. In X.org parlance they are called displays. + */ +typedef struct libgamma_site_state { + /** + * Adjustment method implementation specific data + * + * You as a user of this library should not touch this + */ + void *data; + + /** + * This field specifies, for the methods if this library, + * which adjustment method (display server and protocol) + * is used to adjust the gamma ramps + */ + int method; + + /** + * The site identifier. It can either be `NULL` or a string. + * `NULL` indicates the default site. On systems like the + * Unix-like systems, where the graphics are pluggable, this + * is usually resolved by an environment variable, such as + * "DISPLAY" for X.org. + */ + char *site; + + /** + * The number of partitions that is available on this site. + * Probably the majority of display server only one partition + * per site. However, X.org can, and traditional used to have + * on multi-headed environments, multiple partitions per site. + * In X.org partitions are called 'screens'. It is not to be + * confused with monitor. A screen is a collection of monitors, + * and the mapping from monitors to screens is a surjection. + * On hardware-level adjustment methods, such as Direct + * Rendering Manager, a partition is a graphics card. + */ + size_t partitions_available; + +} libgamma_site_state_t; + + +/** + * Partition state + * + * Probably the majority of display server only one partition + * per site. However, X.org can, and traditional used to have + * on multi-headed environments, multiple partitions per site. + * In X.org partitions are called 'screens'. It is not to be + * confused with monitor. A screen is a collection of monitors, + * and the mapping from monitors to screens is a surjection. + * On hardware-level adjustment methods, such as Direct + * Rendering Manager, a partition is a graphics card. + */ +typedef struct libgamma_partition_state { + /** + * Adjustment method implementation specific data + * + * You as a user of this library should not touch this + */ + void *data; + + /** + * The site this partition belongs to + */ + libgamma_site_state_t *site; + + /** + * The index of the partition + */ + size_t partition; + + /** + * The number of CRTC:s that are available + * under this partition + * + * Note that the CRTC:s are not necessarily + * online + */ + size_t crtcs_available; + +} libgamma_partition_state_t; + + +/** + * Cathode ray tube controller state + * + * The CRTC controls the gamma ramps for the + * monitor that is plugged in to the connector + * that the CRTC belongs to + */ +typedef struct libgamma_crtc_state { + /** + * Adjustment method implementation specific data + * + * You as a user of this library should not touch this + */ + void *data; + + /** + * The partition this CRTC belongs to + */ + libgamma_partition_state_t *partition; + + /** + * The index of the CRTC within its partition + */ + size_t crtc; + +} libgamma_crtc_state_t; + + +/** + * Cathode ray tube controller information data structure + */ +typedef struct libgamma_crtc_information { + +/** + * For a `libgamma_crtc_information_t` fill in the values for + * `edid` and `edid_length` and report errors to `edid_error` + */ +#define LIBGAMMA_CRTC_INFO_EDID (1 << 0) + + /** + * The Extended Display Identification Data associated with + * the attached monitor. + * + * This is raw byte array that is usually 128 bytes long. + * It is not NUL-terminate, rather its length is stored in + * `edid_length`. + */ + unsigned char *edid; + + /** + * The length of `edid` + */ + size_t edid_length; + + /** + * Zero on success, positive it holds the value `errno` had + * when the reading failed, otherwise (negative) the value + * of an error identifier provided by this library + */ + int edid_error; + + +/** + * For a `libgamma_crtc_information_t` fill in the value + * for `width_mm` and report errors to `width_mm_error` + */ +#define LIBGAMMA_CRTC_INFO_WIDTH_MM (1 << 1) + + /** + * The phyical width, in millimetres, of the viewport of the + * attached monitor, as reported by the adjustment method + * + * This value may be incorrect, which is a known issue with + * the X server where it is the result of the X server + * attempting the estimate the size on its own + * + * Zero means that its is not applicable, which is the case + * for projectors + */ + size_t width_mm; + + /** + * Zero on success, positive it holds the value `errno` had + * when the reading failed, otherwise (negative) the value + * of an error identifier provided by this library + */ + int width_mm_error; + + +/** + * For a `libgamma_crtc_information_t` fill in the value + * for `height_mm` and report errors to `height_mm_error` + */ +#define LIBGAMMA_CRTC_INFO_HEIGHT_MM (1 << 2) + + /** + * The phyical height, in millimetres, of the viewport of the + * attached monitor, as reported by the adjustment method + * + * This value may be incorrect, which is a known issue with + * the X server where it is the result of the X server + * attempting the estimate the size on its own + * + * Zero means that its is not applicable, which is the case + * for projectors + */ + size_t height_mm; + + /** + * Zero on success, positive it holds the value `errno` had + * when the reading failed, otherwise (negative) the value + * of an error identifier provided by this library + */ + int height_mm_error; + + +/** + * For a `libgamma_crtc_information_t` fill in the value for + * `width_mm_edid` and report errors to `width_mm_edid_error` + */ +#define LIBGAMMA_CRTC_INFO_WIDTH_MM_EDID (1 << 3) + + /** + * The phyical width, in millimetres, of the viewport of the + * attached monitor, as reported by it the monitor's Extended + * Display Information Data + * + * This value can only contain whole centimetres, which means + * that the result is always zero modulus ten. However, this + * could change with revisions of the EDID structure. + * + * Zero means that its is not applicable, which is the case + * for projectors. + */ + size_t width_mm_edid; + + /** + * Zero on success, positive it holds the value `errno` had + * when the reading failed, otherwise (negative) the value + * of an error identifier provided by this library + */ + int width_mm_edid_error; + + +/** + * For a `libgamma_crtc_information_t` fill in the value for + * `height_mm_edid` and report errors to `height_mm_edid_error` + */ +#define LIBGAMMA_CRTC_INFO_HEIGHT_MM_EDID (1 << 4) + + /** + * The phyical height, in millimetres, of the viewport of the + * attached monitor, as reported by it the monitor's Extended + * Display Information Data + * + * This value can only contain whole centimetres, which means + * that the result is always zero modulus ten. However, this + * could change with revisions of the EDID structure. + * + * Zero means that its is not applicable, which is the case + * for projectors + */ + size_t height_mm_edid; + + /** + * Zero on success, positive it holds the value `errno` had + * when the reading failed, otherwise (negative) the value + * of an error identifier provided by this library + */ + int height_mm_edid_error; + + +/** + * For a `libgamma_crtc_information_t` fill in the values for + * `red_gamma_size`, `green_gamma_size`, and `blue_gamma_size`, + * and report errors to `gamma_size_error` + */ +#define LIBGAMMA_CRTC_INFO_GAMMA_SIZE (1 << 5) + + /** + * The size of the encoding axis of the red gamma ramp + */ + size_t red_gamma_size; + + /** + * The size of the encoding axis of the green gamma ramp + */ + size_t green_gamma_size; + + /** + * The size of the encoding axis of the blue gamma ramp + */ + size_t blue_gamma_size; + + /** + * Zero on success, positive it holds the value `errno` had + * when the reading failed, otherwise (negative) the value + * of an error identifier provided by this library + */ + int gamma_size_error; + + +/** + * For a `libgamma_crtc_information_t` fill in the value for + * `gamma_depth` and report errors to `gamma_depth_error` + */ +#define LIBGAMMA_CRTC_INFO_GAMMA_DEPTH (1 << 6) + + /** + * The bit-depth of the value axes of gamma ramps, + * -1 for single precision floating point, and -2 for + * double precision floating point + */ + signed gamma_depth; + + /** + * Zero on success, positive it holds the value `errno` had + * when the reading failed, otherwise (negative) the value + * of an error identifier provided by this library + */ + int gamma_depth_error; + + +/** + * For a `libgamma_crtc_information_t` fill in the value for + * `gamma_support` and report errors to `gamma_support_error` + */ +#define LIBGAMMA_CRTC_INFO_GAMMA_SUPPORT (1 << 7) + + /** + * `LIBGAMMA_NO` indicates that the CRTC does not support + * gamma ramp adjustments. `LIBGAMMA_MAYBE` indicates that + * the CRTC may or may not support gamma ramp adjustments, + * meaning that the display server really does not know, but + * the protocol is available. `LIBGAMMA_NO` indicates that + * the CRTC does support gamma ramp adjustments. + */ + libgamma_decision_t gamma_support; + + /** + * Zero on success, positive it holds the value `errno` had + * when the reading failed, otherwise (negative) the value + * of an error identifier provided by this library + */ + int gamma_support_error; + + +/** + * For a `libgamma_crtc_information_t` fill in the value for + * `subpixel_order` and report errors to `subpixel_order_error` + */ +#define LIBGAMMA_CRTC_INFO_SUBPIXEL_ORDER (1 << 8) + + /** + * The layout of the subpixels + * + * You cannot count on this value — especially for CRT:s — + * but it is provided anyway as a means of distinguishing + * monitors + */ + libgamma_subpixel_order_t subpixel_order; + + /** + * Zero on success, positive it holds the value `errno` had + * when the reading failed, otherwise (negative) the value + * of an error identifier provided by this library + */ + int subpixel_order_error; + + +/** + * For a `libgamma_crtc_information_t` fill in the + * value for `active` and report errors to `active_error` + */ +#define LIBGAMMA_CRTC_INFO_ACTIVE (1 << 9) + + /** + * Whether there is a monitor connected to the CRTC + */ + int active; + + /** + * Zero on success, positive it holds the value `errno` had + * when the reading failed, otherwise (negative) the value + * of an error identifier provided by this library + */ + int active_error; + + +/** + * For a `libgamma_crtc_information_t` fill in the value for + * `connector_name` and report errors to `connector_name_error` + */ +#define LIBGAMMA_CRTC_INFO_CONNECTOR_NAME (1 << 10) + + /** + * The name of the connector as designated by the display + * server or as give by this library in case the display + * server lacks this feature. + */ + char *connector_name; + + /** + * Zero on success, positive it holds the value `errno` had + * when the reading failed, otherwise (negative) the value + * of an error identifier provided by this library + */ + int connector_name_error; + + +/** + * For a `libgamma_crtc_information_t` fill in the value for + * `connector_type` and report errors to `connector_type_error` + */ +#define LIBGAMMA_CRTC_INFO_CONNECTOR_TYPE (1 << 11) + + /** + * The type of the connector that is associated with the CRTC + */ + libgamma_connector_type_t connector_type; + + /** + * Zero on success, positive it holds the value `errno` had + * when the reading failed, otherwise (negative) the value + * of an error identifier provided by this library + */ + int connector_type_error; + + +/** + * For a `libgamma_crtc_information_t` fill in the + * values for `gamma_red`, `gamma_green`, and `gamma_blue` + * and report errors to `gamma_error` + */ +#define LIBGAMMA_CRTC_INFO_GAMMA (1 << 12) + + /** + * The gamma characteristics of the monitor as reported + * in its Extended Display Information Data. The value + * holds the value for the red channel. + * + * If you do not have and more accurate measurement of the + * gamma for the monitor this could be used to give a rought + * gamma correction; simply divide the value with 2.2 and use + * the result for the red channel in the gamma correction + */ + float gamma_red; + + /** + * The gamma characteristics of the monitor as reported + * in its Extended Display Information Data. The value + * holds the value for the green channel. + * + * If you do not have and more accurate measurement of the + * gamma for the monitor this could be used to give a rought + * gamma correction; simply divide the value with 2.2 and use + * the result for the green channel in the gamma correction + */ + float gamma_green; + + /** + * The gamma characteristics of the monitor as reported + * in its Extended Display Information Data. The value + * holds the value for the blue channel. + * + * If you do not have and more accurate measurement of the + * gamma for the monitor this could be used to give a rought + * gamma correction; simply divide the value with 2.2 and use + * the result for the blue channel in the gamma correction + */ + float gamma_blue; + + /** + * Zero on success, positive it holds the value `errno` had + * when the reading failed, otherwise (negative) the value + * of an error identifier provided by this library + */ + int gamma_error; + + /* DEVELOPERS: Remember to update LIBGAMMA_CRTC_INFO_COUNT below and maybe + * also some of the list of LIBGAMMA_CRTC_INFO_* macros below */ + +} libgamma_crtc_information_t; + +/** + * The number of `LIBGAMMA_CRTC_INFO_*` values defined in + * the version of the library the program is compiled against + * + * This exclude the combining macros defined below this macro + */ +#define LIBGAMMA_CRTC_INFO_COUNT 13 + +/** + * The number of `LIBGAMMA_CRTC_INFO_*` values defined in + * the version of the library the program is linked against + */ +extern const int libgamma_crtc_info_count; + +/** + * Macro for both `libgamma_crtc_information_t` fields + * that can specify the size of the monitor's viewport + * as specified in the monitor's Extended Display + * Information Data + */ +#define LIBGAMMA_CRTC_INFO_MACRO_EDID_VIEWPORT (LIBGAMMA_CRTC_INFO_WIDTH_MM_EDID | LIBGAMMA_CRTC_INFO_HEIGHT_MM_EDID) + +/** + * Macro for all `libgamma_crtc_information_t` fields + * that can be filled if the adjustment method have + * support for reading the monitors' Extended Display + * Information Data + */ +#define LIBGAMMA_CRTC_INFO_MACRO_EDID (LIBGAMMA_CRTC_INFO_EDID | LIBGAMMA_CRTC_INFO_MACRO_EDID_VIEWPORT | LIBGAMMA_CRTC_INFO_GAMMA) + +/** + * Macro for both `libgamma_crtc_information_t` fields + * that can specify the size of the monitor's viewport + * as provided by the adjustment method without this + * library having to parse the monitor's Extended Display + * Information Data + */ +#define LIBGAMMA_CRTC_INFO_MACRO_VIEWPORT (LIBGAMMA_CRTC_INFO_WIDTH_MM | LIBGAMMA_CRTC_INFO_HEIGHT_MM) + +/** + * Macro for the `libgamma_crtc_information_t` fields + * that specifies the CRTC's gamma ramp sizes and gamma + * ramp depth + */ +#define LIBGAMMA_CRTC_INFO_MACRO_RAMP (LIBGAMMA_CRTC_INFO_GAMMA_SIZE | LIBGAMMA_CRTC_INFO_GAMMA_DEPTH) + +/** + * Macro for the `libgamma_crtc_information_t` fields + * that specifies the CRTC's connector type and the + * partition unique name of the connector + */ +#define LIBGAMMA_CRTC_INFO_MACRO_CONNECTOR (LIBGAMMA_CRTC_INFO_CONNECTOR_NAME | LIBGAMMA_CRTC_INFO_CONNECTOR_TYPE) + +/** + * Macro for the `libgamma_crtc_information_t` fields + * that required there is a monitor attached to the + * connector, and that status itself + */ +#define LIBGAMMA_CRTC_INFO_MACRO_ACTIVE (LIBGAMMA_CRTC_INFO_MACRO_EDID | LIBGAMMA_CRTC_INFO_MACRO_VIEWPORT |\ + LIBGAMMA_CRTC_INFO_SUBPIXEL_ORDER | LIBGAMMA_CRTC_INFO_ACTIVE) + + + +/** + * Gamma ramp structure for 8-bit gamma ramps + */ +typedef struct libgamma_gamma_ramps8 { + /** + * The size of `red` + */ + size_t red_size; + + /** + * The size of `green` + */ + size_t green_size; + + /** + * The size of `blue` + */ + size_t blue_size; + + /** + * The gamma ramp for the red channel + */ + uint8_t *red; + + /** + * The gamma ramp for the green channel + */ + uint8_t *green; + + /** + * The gamma ramp for the blue channel + */ + uint8_t *blue; + +} libgamma_gamma_ramps8_t; + + +/** + * Gamma ramp structure for 16-bit gamma ramps + */ +typedef struct libgamma_gamma_ramps16 +{ + /** + * The size of `red` + */ + size_t red_size; + + /** + * The size of `green` + */ + size_t green_size; + + /** + * The size of `blue` + */ + size_t blue_size; + + /** + * The gamma ramp for the red channel + */ + uint16_t *red; + + /** + * The gamma ramp for the green channel + */ + uint16_t *green; + + /** + * The gamma ramp for the blue channel + */ + uint16_t *blue; + +} libgamma_gamma_ramps16_t; + + +/** + * Gamma ramp structure for 32-bit gamma ramps + */ +typedef struct libgamma_gamma_ramps32 +{ + /** + * The size of `red` + */ + size_t red_size; + + /** + * The size of `green` + */ + size_t green_size; + + /** + * The size of `blue` + */ + size_t blue_size; + + /** + * The gamma ramp for the red channel + */ + uint32_t *red; + + /** + * The gamma ramp for the green channel + */ + uint32_t *green; + + /** + * The gamma ramp for the blue channel + */ + uint32_t *blue; + +} libgamma_gamma_ramps32_t; + + +/** + * Gamma ramp structure for 64-bit gamma ramps + */ +typedef struct libgamma_gamma_ramps64 +{ + /** + * The size of `red` + */ + size_t red_size; + + /** + * The size of `green` + */ + size_t green_size; + + /** + * The size of `blue` + */ + size_t blue_size; + + /** + * The gamma ramp for the red channel + */ + uint64_t *red; + + /** + * The gamma ramp for the green channel + */ + uint64_t *green; + + /** + * The gamma ramp for the blue channel + */ + uint64_t *blue; + +} libgamma_gamma_ramps64_t; + + +/** + * Gamma ramp structure for `float` gamma ramps + */ +typedef struct libgamma_gamma_rampsf +{ + /** + * The size of `red` + */ + size_t red_size; + + /** + * The size of `green` + */ + size_t green_size; + + /** + * The size of `blue` + */ + size_t blue_size; + + /** + * The gamma ramp for the red channel + */ + float *red; + + /** + * The gamma ramp for the green channel + */ + float *green; + + /** + * The gamma ramp for the blue channel + */ + float *blue; + +} libgamma_gamma_rampsf_t; + + +/** + * Gamma ramp structure for `double` gamma ramps + */ +typedef struct libgamma_gamma_rampsd +{ + /** + * The size of `red` + */ + size_t red_size; + + /** + * The size of `green` + */ + size_t green_size; + + /** + * The size of `blue` + */ + size_t blue_size; + + /** + * The gamma ramp for the red channel + */ + double *red; + + /** + * The gamma ramp for the green channel + */ + double *green; + + /** + * The gamma ramp for the blue channel + */ + double *blue; + +} libgamma_gamma_rampsd_t; + + +/** + * Mapping function from [0, 1] float encoding value to [0, 2⁸ − 1] integer output value + * + * @param encoding [0, 1] float encoding value + * @return [0, 2⁸ − 1] integer output value + */ +typedef uint8_t libgamma_gamma_ramps8_fun(float); + +/** + * Mapping function from [0, 1] float encoding value to [0, 2¹⁶ − 1] integer output value + * + * @param encoding [0, 1] float encoding value + * @return [0, 2¹⁶ − 1] integer output value + */ +typedef uint16_t libgamma_gamma_ramps16_fun(float); + +/** + * Mapping function from [0, 1] float encoding value to [0, 2³² − 1] integer output value + * + * @param encoding [0, 1] float encoding value + * @return [0, 2³² − 1] integer output value + */ +typedef uint32_t libgamma_gamma_ramps32_fun(float); + +/** + * Mapping function from [0, 1] float encoding value to [0, 2⁶⁴ − 1] integer output value + * + * @param encoding [0, 1] float encoding value + * @return [0, 2⁶⁴ − 1] integer output value + */ +typedef uint64_t libgamma_gamma_ramps64_fun(float); + +/** + * Mapping function from [0, 1] float encoding value to [0, 1] float output value + * + * @param encoding [0, 1] float encoding value + * @return [0, 1] float output value + */ +typedef float libgamma_gamma_rampsf_fun(float); + +/** + * Mapping function from [0, 1] double precision float encoding + * value to [0, 1] double precision float output value + * + * @param encoding [0, 1] float encoding value + * @return [0, 1] float output value + */ +typedef double libgamma_gamma_rampsd_fun(double); + + + +/** + * Prints an error to stderr in a `perror` fashion + * + * @param name The text to add at the beginning + * @param error_code The error code, may be an `errno` value + */ +void libgamma_perror(const char *, int); + +/** + * Get a description of an error + * + * @param error_code The error code, may be an `errno` value, if + * `LIBGAMMA_ERRNO_SET`, the current value of `errno` + * will be used + * @return The description associated with the error code, + * `NULL` if the error code is not recognised + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__warn_unused_result__))) +const char *libgamma_strerror(int); + +/** + * Get a description of an error + * + * @param error_code The error code, may be an `errno` value, if + * `LIBGAMMA_ERRNO_SET`, the current value of `errno` + * will be used + * @param buf Buffer that shall be used if a description must be generated + * @param bufsize The size of `buf`, 1024 is recommended + * @return The description associated with the error code; + * can only be `NULL` if `buf` is `NULL`. If the buffer + * is insufficient, a truncated but NUL-terminated + * description is returned and `errno` is set to `ERANGE`; + * `errno` is otherwise unmodified + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__warn_unused_result__))) +const char *libgamma_strerror_r(int, char[], size_t); + +/** + * Get the name of the definition associated with a `libgamma` error code + * + * @param value The error code + * @return The name of the definition associated with the error code, + * `NULL` if the error code does not exist + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__warn_unused_result__, __const__))) +const char *libgamma_name_of_error(int); + +/** + * Get the value of a `libgamma` error definition refered to by name + * + * @param name The name of the definition associated with the error code + * @return The error code, zero if the name is `NULL` + * or does not refer to a `libgamma` error + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__warn_unused_result__, __pure__))) +int libgamma_value_of_error(const char *); + +/** + * Get the group that the user needs to be a member + * of if `LIBGAMMA_DEVICE_REQUIRE_GROUP` is returned + * + * @return The group that the user needs to be a member of + * if `LIBGAMMA_DEVICE_REQUIRE_GROUP` is returned + */ +#ifndef __WIN32__ +gid_t libgamma_group_gid_get(void); +#else +short libgamma_group_gid_get(void); +#endif + +/** + * Set the group that the user needs to be a member + * of if `LIBGAMMA_DEVICE_REQUIRE_GROUP` is returned + * + * @param value The group that the user needs to be a member of + * if `LIBGAMMA_DEVICE_REQUIRE_GROUP` is returned + */ +#ifndef __WIN32__ +void libgamma_group_gid_set(gid_t); +#else +void libgamma_group_gid_set(short); +#endif + +/** + * Get the group that the user needs to be a member of + * if `LIBGAMMA_DEVICE_REQUIRE_GROUP` is returned + * + * @return The group that the user needs to be a member of if + * `LIBGAMMA_DEVICE_REQUIRE_GROUP` is returned, `NULL` + * if the name of the group `libgamma_group_gid` cannot + * be determined + */ +const char *libgamma_group_name_get(void); + +/** + * Set the group that the user needs to be a member of + * if `LIBGAMMA_DEVICE_REQUIRE_GROUP` is returned + * + * @param value The group that the user needs to be a member of if + * `LIBGAMMA_DEVICE_REQUIRE_GROUP` is returned, may be `NULL` + */ +void libgamma_group_name_set(const char *); + + + + +/** + * Get the name of an adjustment method, + * for example "randr" for `LIBGAMMA_METHOD_X_RANDR` + * + * @param method The adjustment method + * @return The name adjustment method, `NULL` if not + * recognised (errno is not changed) + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__warn_unused_result__, __const__))) +const char *libgamma_name_of_method(int); + +/** + * Get the name of the constant for an adjustment + * method, for example "LIBGAMMA_METHOD_X_RANDR" + * for `LIBGAMMA_METHOD_X_RANDR` + * + * @param method The adjustment method + * @return The name of the constant for adjustment method, + * `NULL` if not recognised (errno is not changed) + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__warn_unused_result__, __const__))) +const char *libgamma_const_of_method(int); + +/** + * Check whether an adjustment method is available, + * non-existing (invalid) methods will be identified + * as not available under the rationale that the + * library may be out of date + * + * @param method The adjustment method + * @return Whether the adjustment method is available + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__warn_unused_result__, __const__))) +int libgamma_is_method_available(int); + +/** + * Get the value of an adjustment method + * + * @param method The name of the adjustment method, for example + * "randr" or "LIBGAMMA_METHOD_X_RANDR" + * @return The adjustment method; for example `LIBGAMMA_METHOD_X_RANDR` + * for "randr" and "LIBGAMMA_METHOD_X_RANDR" + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__warn_unused_result__, __pure__))) +int libgamma_value_of_method(const char *); + + + +/** + * Get the name of a connector type, + * for example "VGA" for `LIBGAMMA_CONNECTOR_TYPE_VGA` + * + * "Unknown" is returned for `LIBGAMMA_CONNECTOR_TYPE_Unknown`, + * "TV" is returned for `LIBGAMMA_CONNECTOR_TYPE_TV`, + * "Virtual" is returned for `LIBGAMMA_CONNECTOR_TYPE_Virtual` + * + * @param connector The connector type + * @return The name connector type, `NULL` if not + * recognised (errno is not changed) + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__warn_unused_result__, __const__))) +const char *libgamma_name_of_connector_type(int); + +/** + * Get the name of the constant for a connector + * type, for example "LIBGAMMA_CONNECTOR_TYPE_VGA" + * for `LIBGAMMA_CONNECTOR_TYPE_VGA` + * + * @param connector The connector type + * @return The name of the constant for connector type, + * `NULL` if not recognised (errno is not changed) + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__warn_unused_result__, __const__))) +const char *libgamma_const_of_connector_type(int); + +/** + * Get the value of a connector type + * + * @param connector The name of the connector type, for example + * "VGA" or "LIBGAMMA_CONNECTOR_TYPE_VGA" + * @return The connector type; for example `LIBGAMMA_CONNECTOR_TYPE_VGA` + * for "VGA" and "LIBGAMMA_CONNECTOR_TYPE_VGA" + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__warn_unused_result__, __pure__))) +int libgamma_value_of_connector_type(const char *); + + + +/** + * Get the name of a subpixel order, for example + * "Horizontal RGB" for `LIBGAMMA_SUBPIXEL_ORDER_HORIZONTAL_RGB` + * + * "Unknown" is returned for `LIBGAMMA_SUBPIXEL_ORDER_UNKNOWN`, + * "None" is returned for `LIBGAMMA_SUBPIXEL_ORDER_NONE` + * + * @param order The subpixel order + * @return The name subpixel order, `NULL` if not + * recognised (errno is not changed) + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__warn_unused_result__, __const__))) +const char *libgamma_name_of_subpixel_order(int); + +/** + * Get the name of the constant for a subpixel order, + * for example "LIBGAMMA_SUBPIXEL_ORDER_HORIZONTAL_RGB" + * for `LIBGAMMA_SUBPIXEL_ORDER_HORIZONTAL_RGB` + * + * @param order The subpixel order + * @return The name of the constant for subpixel order, + * `NULL` if not recognised (errno is not changed) + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__warn_unused_result__, __const__))) +const char *libgamma_const_of_subpixel_order(int); + +/** + * Get the value of a subpixel order + * + * @param order The name of the subpixel order, for example + * "Horizontal RGB" or "LIBGAMMA_SUBPIXEL_ORDER_HORIZONTAL_RGB" + * @return The subpixel order; for example `LIBGAMMA_SUBPIXEL_ORDER_HORIZONTAL_RGB` + * for "Horizontal RGB" and "LIBGAMMA_SUBPIXEL_ORDER_HORIZONTAL_RGB" + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__warn_unused_result__, __pure__))) +int libgamma_value_of_subpixel_order(const char *); + + + +/** + * Initialise a gamma ramp in the proper way that allows all adjustment + * methods to read from and write to it without causing segmentation violation + * + * The input must have `red_size`, `green_size`, and `blue_size` set to the + * sizes of the gamma ramps that should be allocated + * + * @param this The gamma ramps + * @return Zero on success, -1 on allocation error, `errno` will be set accordingly + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_gamma_ramps8_initialise(libgamma_gamma_ramps8_t *restrict); + +/** + * Release resources that are held by a gamma ramp strcuture that + * has been allocated by `libgamma_gamma_ramps8_initialise` or otherwise + * initialised in the proper manner + * + * @param this The gamma ramps + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +void libgamma_gamma_ramps8_destroy(libgamma_gamma_ramps8_t *restrict); + +/** + * Release resources that are held by a gamma ramp strcuture that + * has been allocated by `libgamma_gamma_ramps8_initialise` or otherwise + * initialised in the proper manner, as well as release the pointer + * to the structure + * + * @param this The gamma ramps + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +void libgamma_gamma_ramps8_free(libgamma_gamma_ramps8_t *restrict); + + +/** + * Initialise a gamma ramp in the proper way that allows all adjustment + * methods to read from and write to it without causing segmentation violation + * + * The input must have `red_size`, `green_size`, and `blue_size` set to the + * sizes of the gamma ramps that should be allocated + * + * @param this The gamma ramps + * @return Zero on success, -1 on allocation error, `errno` will be set accordingly + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_gamma_ramps16_initialise(libgamma_gamma_ramps16_t *restrict); + +/** + * Release resources that are held by a gamma ramp strcuture that + * has been allocated by `libgamma_gamma_ramps16_initialise` or otherwise + * initialised in the proper manner + * + * @param this The gamma ramps + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +void libgamma_gamma_ramps16_destroy(libgamma_gamma_ramps16_t *restrict); + +/** + * Release resources that are held by a gamma ramp strcuture that + * has been allocated by `libgamma_gamma_ramps16_initialise` or otherwise + * initialised in the proper manner, as well as release the pointer + * to the structure + * + * @param this The gamma ramps + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +void libgamma_gamma_ramps16_free(libgamma_gamma_ramps16_t *restrict); + + +/** + * Initialise a gamma ramp in the proper way that allows all adjustment + * methods to read from and write to it without causing segmentation violation + * + * The input must have `red_size`, `green_size`, and `blue_size` set to the + * sizes of the gamma ramps that should be allocated. + * + * @param this The gamma ramps + * @return Zero on success, -1 on allocation error, `errno` will be set accordingly + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_gamma_ramps32_initialise(libgamma_gamma_ramps32_t *restrict); + +/** + * Release resources that are held by a gamma ramp strcuture that + * has been allocated by `libgamma_gamma_ramps32_initialise` or otherwise + * initialised in the proper manner + * + * @param this The gamma ramps + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +void libgamma_gamma_ramps32_destroy(libgamma_gamma_ramps32_t *restrict); + +/** + * Release resources that are held by a gamma ramp strcuture that + * has been allocated by `libgamma_gamma_ramps32_initialise` or otherwise + * initialised in the proper manner, as well as release the pointer + * to the structure + * + * @param this The gamma ramps + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +void libgamma_gamma_ramps32_free(libgamma_gamma_ramps32_t *restrict); + + +/** + * Initialise a gamma ramp in the proper way that allows all adjustment + * methods to read from and write to it without causing segmentation violation. + * + * The input must have `red_size`, `green_size`, and `blue_size` set to the + * sizes of the gamma ramps that should be allocated. + * + * @param this The gamma ramps + * @return Zero on success, -1 on allocation error, `errno` will be set accordingly + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_gamma_ramps64_initialise(libgamma_gamma_ramps64_t *restrict); + +/** + * Release resources that are held by a gamma ramp strcuture that + * has been allocated by `libgamma_gamma_ramps64_initialise` or otherwise + * initialised in the proper manner + * + * @param this The gamma ramps + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +void libgamma_gamma_ramps64_destroy(libgamma_gamma_ramps64_t *restrict); + +/** + * Release resources that are held by a gamma ramp strcuture that + * has been allocated by `libgamma_gamma_ramps64_initialise` or otherwise + * initialised in the proper manner, as well as release the pointer + * to the structure + * + * @param this The gamma ramps + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +void libgamma_gamma_ramps64_free(libgamma_gamma_ramps64_t *restrict); + + +/** + * Initialise a gamma ramp in the proper way that allows all adjustment + * methods to read from and write to it without causing segmentation violation + * + * The input must have `red_size`, `green_size`, and `blue_size` set to the + * sizes of the gamma ramps that should be allocated + * + * @param this The gamma ramps + * @return Zero on success, -1 on allocation error, `errno` will be set accordingly + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_gamma_rampsf_initialise(libgamma_gamma_rampsf_t *restrict); + +/** + * Release resources that are held by a gamma ramp strcuture that + * has been allocated by `libgamma_gamma_rampsf_initialise` or otherwise + * initialised in the proper manner + * + * @param this The gamma ramps + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +void libgamma_gamma_rampsf_destroy(libgamma_gamma_rampsf_t *restrict); + +/** + * Release resources that are held by a gamma ramp strcuture that + * has been allocated by `libgamma_gamma_rampsf_initialise` or otherwise + * initialised in the proper manner, as well as release the pointer + * to the structure + * + * @param this The gamma ramps + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +void libgamma_gamma_rampsf_free(libgamma_gamma_rampsf_t *restrict); + + +/** + * Initialise a gamma ramp in the proper way that allows all adjustment + * methods to read from and write to it without causing segmentation violation + * + * The input must have `red_size`, `green_size`, and `blue_size` set to the + * sizes of the gamma ramps that should be allocated + * + * @param this The gamma ramps + * @return Zero on success, -1 on allocation error, `errno` will be set accordingly + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_gamma_rampsd_initialise(libgamma_gamma_rampsd_t *restrict); + +/** + * Release resources that are held by a gamma ramp strcuture that + * has been allocated by `libgamma_gamma_rampsd_initialise` or otherwise + * initialised in the proper manner + * + * @param this The gamma ramps + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +void libgamma_gamma_rampsd_destroy(libgamma_gamma_rampsd_t *restrict); + +/** + * Release resources that are held by a gamma ramp strcuture that + * has been allocated by `libgamma_gamma_rampsd_initialise` or otherwise + * initialised in the proper manner, as well as release the pointer + * to the structure + * + * @param this The gamma ramps + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +void libgamma_gamma_rampsd_free(libgamma_gamma_rampsd_t *restrict); + + + +/** + * List available adjustment methods by their order of preference based on the environment + * + * @param methods Output array of methods, should be able to hold `LIBGAMMA_METHOD_COUNT` elements + * @param buf_size The number of elements that fits in `methods`, it should be `LIBGAMMA_METHOD_COUNT`, + * This is used to avoid writing outside the output buffer if this library adds new + * adjustment methods without the users of the library recompiling + * @param operation Allowed values: + * 0: Methods that the environment suggests will work, excluding fake + * 1: Methods that the environment suggests will work, including fake + * 2: All real non-fake methods + * 3: All real methods + * 4: All methods + * Other values invoke undefined behaviour + * @return The number of element that have been stored in `methods`, or should + * have been stored if the buffer was large enough + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__warn_unused_result__))) +size_t libgamma_list_methods(int *restrict, size_t, int); + +/** + * Return the capabilities of an adjustment method + * + * @param this The data structure to fill with the method's capabilities + * @param method The adjustment method (display server and protocol) + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +int libgamma_method_capabilities(libgamma_method_capabilities_t *restrict, int); + +/** + * Return the default site for an adjustment method + * + * @param method The adjustment method (display server and protocol) + * @return The default site, `NULL` if it cannot be determined or + * if multiple sites are not supported by the adjustment + * method + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__warn_unused_result__))) +const char *libgamma_method_default_site(int); + +/** + * Return the default variable that determines + * the default site for an adjustment method + * + * @param method The adjustment method (display server and protocol) + * @return The environ variables that is used to determine the + * default site, `NULL` if there is none, that is, if + * the method does not support multiple sites + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__warn_unused_result__))) +const char *libgamma_method_default_site_variable(int); + + + +/** + * Initialise an allocated site state + * + * @param this The site state to initialise + * @param method The adjustment method (display server and protocol) + * @param site The site identifier, unless it is `NULL` it must a + * `free`:able. Once the state is destroyed the library + * will attempt to free it. There you should not free + * it yourself, and it must not be a string constant + * or allocate on the stack. Note however that it will + * not be `free`:d if this function fails. + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__(1)))) +int libgamma_site_initialise(libgamma_site_state_t *restrict, int, char *restrict); + +/** + * Release all resources held by a site state + * + * @param this The site state + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +void libgamma_site_destroy(libgamma_site_state_t *restrict); + +/** + * Release all resources held by a site state + * and free the site state pointer + * + * @param this The site state + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +inline void +libgamma_site_free(libgamma_site_state_t *restrict this__) +{ + libgamma_site_destroy(this__); + free(this__); +} + +/** + * Restore the gamma ramps all CRTC:s within a site to the system settings + * + * @param this The site state + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_site_restore(libgamma_site_state_t *restrict); + + + +/** + * Initialise an allocated partition state + * + * @param this The partition state to initialise + * @param site The site state for the site that the partition belongs to + * @param partition The index of the partition within the site + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_partition_initialise(libgamma_partition_state_t *restrict, libgamma_site_state_t *restrict, size_t); + +/** + * Release all resources held by a partition state + * + * @param this The partition state + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +void libgamma_partition_destroy(libgamma_partition_state_t *restrict); + +/** + * Release all resources held by a partition state + * and free the partition state pointer + * + * @param this The partition state + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +inline void +libgamma_partition_free(libgamma_partition_state_t *restrict this__) +{ + libgamma_partition_destroy(this__); + free(this__); +} + +/** + * Restore the gamma ramps all CRTC:s within a partition to the system settings + * + * @param this The partition state + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_partition_restore(libgamma_partition_state_t *restrict); + + + +/** + * Initialise an allocated CRTC state + * + * @param this The CRTC state to initialise + * @param partition The partition state for the partition that the CRTC belongs to + * @param crtc The index of the CRTC within the partition + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_crtc_initialise(libgamma_crtc_state_t *restrict, libgamma_partition_state_t *restrict, size_t); + +/** + * Release all resources held by a CRTC state + * + * @param this The CRTC state + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +void libgamma_crtc_destroy(libgamma_crtc_state_t *restrict); + +/** + * Release all resources held by a CRTC state + * and free the CRTC state pointer + * + * @param this The CRTC state + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +inline void +libgamma_crtc_free(libgamma_crtc_state_t *restrict this__) +{ + libgamma_crtc_destroy(this__); + free(this__); +} + +/** + * Restore the gamma ramps for a CRTC to the system settings for that CRTC + * + * @param this The CRTC state + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_crtc_restore(libgamma_crtc_state_t *restrict); + + +/** + * Read information about a CRTC + * + * @param this Instance of a data structure to fill with the information about the CRTC + * @param crtc The state of the CRTC whose information should be read + * @param fields OR:ed identifiers for the information about the CRTC that should be read + * @return Zero on success, -1 on error; on error refer to the error reports in `this` + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_get_crtc_information(libgamma_crtc_information_t *restrict, libgamma_crtc_state_t *restrict, int32_t); + +/** + * Release all resources in an information data structure for a CRTC + * + * @param this The CRTC information + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +void libgamma_crtc_information_destroy(libgamma_crtc_information_t *restrict); + +/** + * Release all resources in an information data structure for a CRTC + * and free the data structure pointer + * + * @param this The CRTC information + */ +inline void +libgamma_crtc_information_free(libgamma_crtc_information_t *restrict this__) +{ + libgamma_crtc_information_destroy(this__); + free(this__); +} + + +/** + * Convert a raw representation of an EDID to a lowercase hexadecimal representation + * + * @param edid The EDID in raw representation + * @param length The length of `edid` + * @return The EDID in lowercase hexadecimal representation + * `NULL` on allocation error, `errno` will be set accordingly + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__warn_unused_result__))) +char *libgamma_behex_edid_lowercase(const unsigned char *restrict, size_t); + +/** + * Convert a raw representation of an EDID to an uppercase hexadecimal representation + * + * @param edid The EDID in raw representation + * @param length The length of `edid` + * @return The EDID in uppercase hexadecimal representation, + * NULL` on allocation error, `errno` will be set accordingly + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__warn_unused_result__))) +char *libgamma_behex_edid_uppercase(const unsigned char *restrict, size_t); + +/** + * Convert a raw representation of an EDID to a lowercase hexadecimal representation + * + * @param edid:const unsigned char* The EDID in raw representation + * @param length:size_t The length of `edid` + * @return :char* The EDID in lowercase hexadecimal representation, + * `NULL` on allocation error, `errno` will be set accordingly + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__warn_unused_result__))) +inline char * +libgamma_behex_edid(const unsigned char *restrict edid__, size_t length__) +{ + return libgamma_behex_edid_lowercase(edid__, length__); +} + +/** + * Convert an hexadecimal representation of an EDID to a raw representation + * + * @param edid The EDID in hexadecimal representation + * @return The EDID in raw representation, it will be half the length + * of `edid` (the input value); `NULL` on allocation error or + * if the EDID is malformated, `errno` will be set accordingly + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__warn_unused_result__, __nonnull__))) +unsigned char *libgamma_unhex_edid(const char *restrict); + + + +/** + * Get the current gamma ramps for a CRTC, 8-bit gamma-depth version + * + * @param this The CRTC state + * @param ramps The gamma ramps to fill with the current values + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_crtc_get_gamma_ramps8(libgamma_crtc_state_t *restrict, libgamma_gamma_ramps8_t *restrict); + +/** + * Set the gamma ramps for a CRTC, 8-bit gamma-depth version. + * + * @param this The CRTC state + * @param ramps The gamma ramps to apply + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_crtc_set_gamma_ramps8(libgamma_crtc_state_t *restrict, libgamma_gamma_ramps8_t); + +/** + * Set the gamma ramps for a CRTC, 8-bit gamma-depth function version + * + * Note that this will probably involve the library allocating temporary data + * + * @param this The CRTC state + * @param red_function The function that generates the gamma ramp for the red channel + * @param green_function The function that generates the gamma ramp for the green channel + * @param blue_function The function that generates the gamma ramp for the blue channel + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_crtc_set_gamma_ramps8_f(libgamma_crtc_state_t *restrict, libgamma_gamma_ramps8_fun *, + libgamma_gamma_ramps8_fun *, libgamma_gamma_ramps8_fun *); + + +/** + * Get the current gamma ramps for a CRTC, 16-bit gamma-depth version + * + * @param this The CRTC state + * @param ramps The gamma ramps to fill with the current values + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__, __hot__))) +int libgamma_crtc_get_gamma_ramps16(libgamma_crtc_state_t *restrict, libgamma_gamma_ramps16_t *restrict); + +/** + * Set the gamma ramps for a CRTC, 16-bit gamma-depth version + * + * @param this The CRTC state + * @param ramps The gamma ramps to apply + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__, __hot__))) +int libgamma_crtc_set_gamma_ramps16(libgamma_crtc_state_t *restrict, libgamma_gamma_ramps16_t); + +/** + * Set the gamma ramps for a CRTC, 16-bit gamma-depth function version + * + * Note that this will probably involve the library allocating temporary data + * + * @param this The CRTC state + * @param red_function The function that generates the gamma ramp for the red channel + * @param green_function The function that generates the gamma ramp for the green channel + * @param blue_function The function that generates the gamma ramp for the blue channel + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__, __hot__))) +int libgamma_crtc_set_gamma_ramps16_f(libgamma_crtc_state_t *restrict, libgamma_gamma_ramps16_fun *, + libgamma_gamma_ramps16_fun *, libgamma_gamma_ramps16_fun *); + + +/** + * Get the current gamma ramps for a CRTC, 32-bit gamma-depth version + * + * @param this The CRTC state + * @param ramps The gamma ramps to fill with the current values + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_crtc_get_gamma_ramps32(libgamma_crtc_state_t *restrict, libgamma_gamma_ramps32_t *restrict); + +/** + * Set the gamma ramps for a CRTC, 32-bit gamma-depth version + * + * @param this The CRTC state + * @param ramps The gamma ramps to apply + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_crtc_set_gamma_ramps32(libgamma_crtc_state_t *restrict, libgamma_gamma_ramps32_t); + +/** + * Set the gamma ramps for a CRTC, 32-bit gamma-depth function version + * + * Note that this will probably involve the library allocating temporary data + * + * @param this The CRTC state + * @param red_function The function that generates the gamma ramp for the red channel + * @param green_function The function that generates the gamma ramp for the green channel + * @param blue_function The function that generates the gamma ramp for the blue channel + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_crtc_set_gamma_ramps32_f(libgamma_crtc_state_t *restrict, libgamma_gamma_ramps32_fun *, + libgamma_gamma_ramps32_fun *, libgamma_gamma_ramps32_fun *); + + +/** + * Get the current gamma ramps for a CRTC, 64-bit gamma-depth version + * + * @param this The CRTC state + * @param ramps The gamma ramps to fill with the current values + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_crtc_get_gamma_ramps64(libgamma_crtc_state_t *restrict, libgamma_gamma_ramps64_t *restrict); + +/** + * Set the gamma ramps for a CRTC, 64-bit gamma-depth version + * + * @param this The CRTC state + * @param ramps The gamma ramps to apply + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_crtc_set_gamma_ramps64(libgamma_crtc_state_t *restrict, libgamma_gamma_ramps64_t); + +/** + * Set the gamma ramps for a CRTC, 64-bit gamma-depth function version + * + * Note that this will probably involve the library allocating temporary data + * + * @param this The CRTC state + * @param red_function The function that generates the gamma ramp for the red channel + * @param green_function The function that generates the gamma ramp for the green channel + * @param blue_function The function that generates the gamma ramp for the blue channel + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_crtc_set_gamma_ramps64_f(libgamma_crtc_state_t *restrict, libgamma_gamma_ramps64_fun *, + libgamma_gamma_ramps64_fun *, libgamma_gamma_ramps64_fun *); + + +/** + * Set the gamma ramps for a CRTC, `float` version + * + * @param this The CRTC state + * @param ramps The gamma ramps to apply + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_crtc_set_gamma_rampsf(libgamma_crtc_state_t *restrict, libgamma_gamma_rampsf_t); + +/** + * Get the current gamma ramps for a CRTC, `float` version + * + * @param this The CRTC state + * @param ramps The gamma ramps to fill with the current values + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_crtc_get_gamma_rampsf(libgamma_crtc_state_t *restrict, libgamma_gamma_rampsf_t *restrict); + +/** + * Set the gamma ramps for a CRTC, `float` function version + * + * Note that this will probably involve the library allocating temporary data + * + * @param this The CRTC state + * @param red_function The function that generates the gamma ramp for the red channel + * @param green_function The function that generates the gamma ramp for the green channel + * @param blue_function The function that generates the gamma ramp for the blue channel + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_crtc_set_gamma_rampsf_f(libgamma_crtc_state_t *restrict, libgamma_gamma_rampsf_fun *, + libgamma_gamma_rampsf_fun *, libgamma_gamma_rampsf_fun *); + + +/** + * Get the current gamma ramps for a CRTC, `double` version + * + * @param this The CRTC state + * @param ramps The gamma ramps to fill with the current values + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_crtc_get_gamma_rampsd(libgamma_crtc_state_t *restrict, libgamma_gamma_rampsd_t *restrict); + +/** + * Set the gamma ramps for a CRTC, `double` version + * + * @param this The CRTC state + * @param ramps The gamma ramps to apply + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +int libgamma_crtc_set_gamma_rampsd(libgamma_crtc_state_t *restrict, libgamma_gamma_rampsd_t); + +/** + * Set the gamma ramps for a CRTC, `double` function version + * + * Note that this will probably involve the library allocating temporary data + * + * @param this The CRTC state + * @param red_function The function that generates the gamma ramp for the red channel + * @param green_function The function that generates the gamma ramp for the green channel + * @param blue_function The function that generates the gamma ramp for the blue channel + * @return Zero on success, otherwise (negative) the value of an + * error identifier provided by this library + */ +LIBGAMMA_GCC_ONLY__(__attribute__((__nonnull__))) +int libgamma_crtc_set_gamma_rampsd_f(libgamma_crtc_state_t *restrict, libgamma_gamma_rampsd_fun *, + libgamma_gamma_rampsd_fun *, libgamma_gamma_rampsd_fun *); + + + +#undef LIBGAMMA_GCC_ONLY__ +#endif |