£>set -u £>cd src/extract £>export PATH=".:../../info:$PATH"

libgamma -- Display server abstraction layer for gamma ramp adjustments
***********************************************************************

Copyright © 2014 Mattias Andrée

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.

Overview
********

libgamma is a C library that aims to abstract away the display server when adjusting the colours curves for monitors via gamma ramps, and to be cross-platform.

libgamma have support for the X RandR (Resize and Rotate) extension, the X VidMode extension and under Linux the Direct Rendering Manager which lets software work with graphics outside of graphical environments. Additionally libgamma have support for Windows Graphics Device Interface (Windows GDI) under Linux and Quartz using CoreGraphics under OS X. However Windows GDI and Quartz/CoreGraphics do not receive first-party testing on their target platforms but do receive first-party testing using a compatibility layer that translates the calls to RandR calls. Neither does libgamma, currently, receive testing on any of the BSD:s, it is only tested on GNU/Linux.

Furthermore libgamma provides a dummy method that can be used to ignore adjustments and can be controlled from a another program to pretend like the environment has changed. This can be used test how well your software handles such events. It can also be configured at runtime to use another adjustment method such as RandR.

Jargon
******

libgamma uses a small jargon, parts of which is loaned from X.org, and some is commonly used jargon.

adjustment method [libgamma]
     A combination of the display server and a protocol used to tell to the display server.

display server [X.org]
     The program used to display graphical elements to the monitors. In libgamma we also call the non-graphical environment a display server.

display [X.org]
site [libgamma]
     An instance of a display server. Non-graphical environment are only covered by `site'.

screen [X.org]
     A group of CRTC:s within a display.

CRTC
cathode ray tube controller
     Controller for the output on monitor. Mapping from CRTC:s to encoders is an injection.

monitor
     The physical medium used to display text and graphics.

partition [libgamma]
     Umbrella term for `screen' and `graphics card'.

page [libgamma]
     The desktop workspace or virtual terminal that is displayed on a CRTC. (This jargon is not currently used, but is reserved for future features.)

output [X.org]
     A connector and its encoder.

connector
     Physical port on the graphics card where a monitor can be plugged in. If and only if the connector is disabled it does not have a port and does not have a CRTC.

encoder
     Translation layer between CRTC:s and connectors.

gamma ramp
colour curve
     A lookup table that translates an encoded value for a subpixel into its output value.

subpixel
colour channel
     One of the three colours that makes up a pixel: red, green or blue.

gamma ramp size
gamma stops
     The number of possible values on the encoding axis of a gamma ramp.

Compiling
*********

The build libgamma you will need to run ./configure before you run make. ./configure is not a configuration script from the GNU build system, rather it is just a simple shell script. Each adjustment method needs selected, if none are selected no adjustment method will be compiled into libgamma. They can either be selected explicitly and independently or by operating system.

--enable-dummy
     Enables the dummy adjustment method.

--enable-randr
--linux
--bsd
     Enables the X RandR extension adjustment method.

--enable-vidmode
--linux
--bsd
     Enables the X VidMode extension adjustment method.

--enable-drm
--linux
     Enables the Direct Rendering Manager adjustment method.

--enable-w32gdi
--windows
     Enables the Windows GDI adjustment method.

--enable-quartz
--mac-os-x
     Enables the Quartz/CoreGraphics adjustment method.

--enable-w32gdi=fake
     Enables the Windows GDI adjustment method using compatibility layer to either RandR or ``/dev/null'' depending on whether RandR is enabled or not.

--enable-quartz=fake
     Enables the Quartz/CoreGraphics adjustment method using a compatibility layer to either RandR or ``/dev/null'' depending on whether RandR is enabled or not.

You may prefix anything to `bsd', for example --freebsd or --openbsd. Any prefix will be discard, but it may be a good idea incase there will be a difference in the future between the platforms.

Developers of libgamma and developers who use libgamma for their software may also want to use --debug which enables extra checks to produce better error reports. Additionally --debug adds the -Og -g flags to the C compiler rather than -Ofast. Developers can also use the developer options instead of --debug, the adjustment and operating systems.

--linux=developer
--developer
     Enables all adjustment methods, with compatibility layers for Windows GDI and Quartz/CoreGraphics. Also enables --debug.

--bsd=developer
     Enables all adjustment methods, except the Linux Direct Rendering Manager adjustment method, with compatibility layers for Windows GDI and Quartz/CoreGraphics. Also enables --debug.

--windows=developer
     Enables the dummy adjustment method and the Windows GDI adjustment method. Also enables --debug.

--mac-os-x=developer
     Enables the dummy adjustment method and the Quartz/CoreGraphics adjustment method. Also enables --debug.

When you have configured libgamma using ./configure you can compile the library with make. Straight up make without additions options should be all you need. But you can also use specify some build rules.

default
     Builds the library, the test and the info manual.

all
     Builds the library, the test and manual to all available formats: info, PDF, DVI, PostScript.

lib
     Builds the library.

test
     Builds the test, which in turns builts the library.

doc
     Builds the manual to all available formats: info, PDF, DVI, PostScript.

info
     Builds the info manual.

pdf
     Builds the PDF manual.

dvi
     Builds the DVI manual.

ps
     Builds the PostScript manual.

You can also use make clean to remove all compiled files, and make distclean to remove all compiled files and the files generated by ./configure.

To install libgamma once it is compiled run make install and then make uninstall once you want to uninstall the library. When running make install include the option DESTDIR="${pkgdir}", where ${pkgdir} is the directory you want the files to be installed to instead of /, this could for example be /mnt where you have mounted another installed operating system or a temporary location used by the package manager. This is also a set of options to specify how the system's file system hierarchy is structured.

PREFIX
     The package path prefix, if you want to install to another root, set DESTDIR to that root. Defaults to /usr.

LIB
     The library path excluding prefix. Defaults to /lib.

INCLUDE
     The library header path excluding prefix. Defaults to /include.

DATA
     The resource path excluding prefix. Defaults to /share.

LIBDIR
     The library path including prefix. Defaults to $(PREFIX)$(LIB).

INCLUDEDIR
     The library header including prefix Defaults to $(PREFIX)$(INCLUDE).

DATADIR
     The resource path including prefix. Defaults to $(PREFIX)$(DATA).

DOCDIR
     The generic documentation path including prefix. Defaults to $(DATADIR)/doc.

INFODIR
     The info manual documentation path including prefix. Defaults to $(DATADIR)/info.

LICENSEDIR
     The license base path including prefix. Defaults to $(DATADIR)/licenses

There is also an option to specify the package name of the library: PKGNAME. This only affects the name and location of files installed into DOCDIR, INFODIR and LICENSEDIR. It does not affect the name of the library.

For more control on what should be installed, subsitute install from make install for one or more of the following rules:

install
     Macro for install-base and install-info. Installs everything but only the manual in the info format. install-info will not be execute the install the manual to the dir file for info.

install-all
     Macro for install-base and install-doc. Installs everything including all available formats of the manual. install-info will not be execute the install the manual to the dir file for info.

install-base
     Macro for install-lib, install-include and install-copyright. Installs the library, the headers files for the library so that you can compile other software that uses the library, and the copyright file and the license file.

install-lib
     Installs the library, but not its header files.

install-include
     Installs the library's header files but not the library itself.

install-copyright
     Macro for install-copying, and install-license. Installs the copyright file and the license file.

install-copying
     Installs the copyright file but not the license file.

install-license
     Installs the license file but not the copyright file.

install-doc
     Macro for install-info, install-pdf, install-ps and install-dvi. Installs the manual in all available formats. install-info will not be execute the install the manual to the dir file for info.

install-info
     Installs the info manual. install-info will not be execute the install the manual to the dir file for info.

install-pdf
     Installs the PDF manual.

install-ps
     Installs the PostScript manual.

install-dvi
     Installs the DVI manual.

Linking
*******

When compiling your program use libgamma, you will not need to do anything for the compiling phase. But for the linking phase, will need to add the option -lgamma. Currently libgamma, does not provide an pkgconfig file.

Keep in mind that libgamma is GNU General Public License version 3 software for your freedom and for the freedom of all.

API
***

To use libgamma add ``#include <libgamma.h>'' to and C file or C header file that requires anything from libgamma. libgamma.h is the only header file from libgamma which should be included directly.

Once libgamma.h is included your program will have access the libgamma's API which includes functions, data structures, error codes, and adjustment method identifers.

It is highly recommened to add a check for new error codes if your program will be using error codes from libgamma. This allows you to get a notification if you program is not up to date with new error codes in libgamma. To do this, libgamma.h provides the C preprocessor definition LIBGAMMA_ERROR_MIN; this is the lowest value of that any error code has, all error codes are negative, a new error code is added it will have a lower value that the ones added before it. The first step in adding this check is to figure out what the value of LIBGAMMA_ERROR_MIN is on your system. To do this, use the cpp program, it should be included with your C compiler.

     cpp <<EOF | tail --lines 1
     #include <libgamma.h>
     LIBGAMMA_ERROR_MIN
     EOF

The next step is to add some C preprocessor directives to one of your C files that includes libgamma.h.

     #if LIBGAMMA_ERROR_MIN < -10
     # warning New error codes have been added to libgamma.
     #endif

In this example, we assume that output of the first step was `-10', which it really was not. So if you use this in your program you should receive a warning until you update the value.

In a similar manner, you should all a check to detect when the value of either GAMMA_METHOD_MAX or GAMMA_METHOD_COUNT (the latter will have value of one higher than the earlier) have increased. This will allow you to get a warning for when new adjustment method have been added so you can take appropriate actions if required. libgamma does not only provide display server abstract, it optionally lets you choose any available method you want despite of what display server you are used.

You may also want to add checks for update to LIBGAMMA_CONNECTOR_TYPE_COUNT, LIBGAMMA_SUBPIXEL_ORDER_COUNT and LIBGAMMA_CRTC_INFO_COUNT.

Adjustment methods
==================

libgamma is an abstraction layer that lets you select which display server and protocol --- together called adjustment method --- it should use to work with the monitors' gamma ramps. Supported adjustment method, even if excluded at compile-time are identfier by numerical values.

     £>for method in $(libgamma-method-extract --list --method); do

£method
     £>libgamma-method-extract --method $method | texise £>done

Adjustment method capabilities
==============================

Capabilities.

     £>for cap in $(libgamma-method-extract --list --cap-t); do

£cap [£(libgamma-method-extract --type --cap-t $cap)]
     £>libgamma-method-extract --cap-t $cap | texise £>done

CRTC information
================

CRTC information.

     £>for info in $(libgamma-method-extract --list --info); do

£info
     £>libgamma-method-extract --info $info | texise £>done

Subpixel order.

     £>for order in $(libgamma-method-extract --list --subpixel); do

£order
     £>libgamma-method-extract --subpixel $order | texise £>done

Connector type.

     £>for type in $(libgamma-method-extract --list --connector); do

£type
     £>libgamma-method-extract --connector $type | texise £>done

Fields.

     £>for info in $(libgamma-method-extract --list --info-t); do

£info [£(libgamma-method-extract --type --info-t $info)]
     £>libgamma-method-extract --info-t $info | texise £>done

Errors
======

Many libgamma functions will return libgamma specific error codes rather than setting errno and return -1. However errno may have been set, but should in such case be ignored unless LIBGAMMA_ERRNO_SET has been returned. Other functions do set errno and return -1. Other functions may store the error code. In this case LIBGAMMA_ERRNO_SET cannot be stored but the value that errno had when an error occured can be stored instead of a libgamma specific error codes. errno values are allows positive whereas libgamma specific error codes are allows negative. On success zero is returned or stored.

If LIBGAMMA_DEVICE_REQUIRE_GROUP is returned the ID of the required group is stored in libgamma_group_gid and the name of that group is stored in libgamma_group_name. NULL is stored if the name of the group cannto be determined. libgamma.h give you access to these variables, they are defined as gid_t and const char* types respectively.

libgamma defines the following error codes that its functions may return:

     £>for err in $(libgamma-error-extract --list); do

£err
     £>libgamma-error-extract $err | texise £>done

The function libgamma_name_of_error can be used to return the name of an libgamma error. For example libgamma_name_of_error(LIBGAMMA_ERRNO_SET) will return the string ``LIBGAMMA_ERRNO_SET''. Similarly libgamma_value_of_error("LIBGAMMA_ERRNO_SET") will return the value of LIBGAMMA_ERRNO_SET. The value returned from libgamma_name_of_error shall not be free:d. NULL is returned if the value does nto refer to a libgamma error. libgamma_value_of_error will return zero if the input is NULL or string that is not the name of a libgamma error.

The function libgamma_perror can be used to print an error to stderr in a perror fashion. However libgamma_perror will not translate the libgamma errors into human-readable strings, it will simply print the name of the error. libgamma_perror takes two arguments: a const char* that work like the parameter for perror, and an int with the error code. If the error code is the value of LIBGAMMA_ERRNO_SET perror will be used to print the current error stored in errno. If the error code is non-negative (an errno value`), that value will be stored in errno and perror will be used to print it. Additionally, if the error code is the value of LIBGAMMA_DEVICE_REQUIRE_GROUP the required group will be printed with its numerical value and, if known, its name.

GNU Free Documentation License
******************************

     [file fdl.texinfo not included]