path: root/info/libgamma.texinfo

\input texinfo   @c -*-texinfo-*-

@c %**start of header
@setfilename libgamma.info
@settitle blueshift
@afourpaper
@documentencoding UTF-8
@documentlanguage en
@finalout
@c %**end of header


@dircategory Library
@direntry
* libgamma: (libgamma).            Display server abstraction layer for gamma ramp adjustments
@end direntry


@copying
Copyright @copyright{} 2014 Mattias Andrée

@quotation
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''.
@end quotation
@end copying

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

@ifnottex
@node Top
@top libgamma -- Display server abstraction layer for gamma ramp adjustments
@insertcopying
@end ifnottex

@titlepage
@title libgamma
@subtitle Display server abstraction layer for gamma ramp adjustments
@author by Mattias Andrée (maandree)

@page
@c @center `'
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents



@menu
* Overview::                        Brief overview of @command{libgamma}.
* Jargon::                          The jargon of @command{libgamma}.
* Compiling::                       Configuring, compiling and installing @command{libgamma}.
* Linking::                         Linking your software to @command{libgamma}.
* API::                             @command{libgamma}'s advanced programming interface.
* GNU Free Documentation License::  Copying and sharing this manual.
@end menu



@node Overview
@chapter Overview

@command{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.

@command{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
@command{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
@command{libgamma}, currently, receive testing
on any of the BSD:s, it is only tested on GNU/Linux.

Furthermore @command{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.



@node Jargon
@chapter Jargon

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

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

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

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

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

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

@item monitor
The physical medium used to display
text and graphics.

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

@item 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.)

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

@item 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.

@item encoder
Translation layer between CRTC:s and connectors.

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

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

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

@end table



@node Compiling
@chapter Compiling

The build @command{libgamma} you will need
to run @command{./configure} before you
run @command{make}. @file{./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 @command{libgamma}. They can either be
selected explicitly and independently or by
operating system.

@table @option
@item --enable-dummy
Enables the dummy adjustment method.

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

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

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

@item --enable-w32gdi
@itemx --windows
Enables the Windows GDI adjustment method.

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

@item --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.

@item --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.

@end table

You may prefix anything to `bsd', for example
@option{--freebsd} or @option{--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 @command{libgamma} and developers
who use @command{libgamma} for their software may
also want to use @option{--debug} which enables
extra checks to produce better error reports.
Additionally @option{--debug} adds the @option{-Og -g}
flags to the C compiler rather than @option{-Ofast}.
Developers can also use the developer options
instead of @option{--debug}, the adjustment and
operating systems.

@table @option
@item --linux=developer
@itemx --developer
Enables all adjustment methods, with compatibility
layers for Windows GDI and Quartz/CoreGraphics.
Also enables @option{--debug}.

@item --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 @option{--debug}.

@item --windows=developer
Enables the dummy adjustment method and the
Windows GDI adjustment method.
Also enables @option{--debug}.

@item --mac-os-x=developer
Enables the dummy adjustment method and the
Quartz/CoreGraphics adjustment method.
Also enables @option{--debug}.
@end table

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

@table @option
@item default
Builds the library, the test and the info manual.

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

@item lib
Builds the library.

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

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

@item info
Builds the info manual.

@item pdf
Builds the PDF manual.

@item dvi
Builds the DVI manual.

@item ps
Builds the PostScript manual.

@end table

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

To install @command{libgamma} once
it is compiled run @command{make install}
and then @command{make uninstall} once
you want to uninstall the library.
When running @command{make install}
include the option @option{DESTDIR="$@{pkgdir@}"},
where @file{$@{pkgdir@}} is the directory
you want the files to be installed to
instead of @file{/}, this could for example
be @file{/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.

@table @option
@item PREFIX
The package path prefix, if you want to install
to another root, set @option{DESTDIR} to that root.
Defaults to @file{/usr}.

@item LIB
The library path excluding prefix.
Defaults to @file{/lib}.

@item INCLUDE
The library header path excluding prefix.
Defaults to @file{/include}.

@item DATA
The resource path excluding prefix.
Defaults to @file{/share}.

@item LIBDIR
The library path including prefix.
Defaults to @file{$(PREFIX)$(LIB)}.

@item INCLUDEDIR
The library header including prefix
Defaults to @file{$(PREFIX)$(INCLUDE)}.

@item DATADIR
The resource path including prefix.
Defaults to @file{$(PREFIX)$(DATA)}.

@item DOCDIR
The generic documentation path including prefix.
Defaults to @file{$(DATADIR)/doc}.

@item INFODIR
The info manual documentation path including prefix.
Defaults to @file{$(DATADIR)/info}.

@item LICENSEDIR
The license base path including prefix.
Defaults to @file{$(DATADIR)/licenses}
@end table

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

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

@table @option
@item install
Macro for @option{install-base} and @option{install-info}.
Installs everything but only the manual in the info format.
@command{install-info} will not be execute the install the
manual to the @file{dir} file for @command{info}.

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

@item install-base
Macro for @option{install-lib}, @option{install-include} and
@option{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.

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

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

@item install-copyright
Macro for @option{install-copying}, and @option{install-license}.
Installs the copyright file and the license file.

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

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

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

@item install-info
Installs the info manual.
@command{install-info} will not be execute the install the
manual to the @file{dir} file for @command{info}.

@item install-pdf
Installs the PDF manual.

@item install-ps
Installs the PostScript manual.

@item install-dvi
Installs the DVI manual.
@end table



@node Linking
@chapter Linking

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

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



@node API
@chapter API

@menu
* Adjustment methods::              Selecting adjustment method.
* CRTC information::                Retrieving information about CRTC:s.
* Errors::                          Error codes and how to handle errors.
@end menu

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

Once @file{libgamma.h} is included your program will
have access the @command{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
@command{libgamma}. This allows you to get a notification
if you program is not up to date with new error codes
in @command{libgamma}. To do this, @file{libgamma.h}
provides the C preprocessor definition @code{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 @code{LIBGAMMA_ERROR_MIN} is on your
system. To do this, use the @command{cpp} program, it
should be included with your C compiler.

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

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

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

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 @code{GAMMA_METHOD_MAX} or
@code{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. @command{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
@code{LIBGAMMA_CONNECTOR_TYPE_COUNT},
@code{LIBGAMMA_SUBPIXEL_ORDER_COUNT} and
@code{LIBGAMMA_CRTC_INFO_COUNT}.



@node Adjustment methods
@section Adjustment methods

@command{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.

@table @code
£>for method in $(libgamma-method-extract --list --method); do
@item £{method}
£>libgamma-method-extract --method $method | texise
£>done
@end table



@node CRTC information
@section CRTC information

CRTC information.

@table @code
£>for info in $(libgamma-method-extract --list --info); do
@item £{info}
£>libgamma-method-extract --info $info | texise
£>done
@end table

Subpixel order.

@table @code
£>for order in $(libgamma-method-extract --list --subpixel); do
@item £{order}
£>libgamma-method-extract --subpixel $order | texise
£>done
@end table

Connector type.

@table @code
£>for type in $(libgamma-method-extract --list --connector); do
@item £{type}
£>libgamma-method-extract --connector $type | texise
£>done
@end table

Fields.

@table @code
£>for info in $(libgamma-method-extract --list --info-t); do
@item £{info} [£(libgamma-method-extract --type --info-t $info)]
£>libgamma-method-extract --info-t $info | texise
£>done
@end table




@node Errors
@section Errors

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

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

@command{libgamma} defines the following error codes
that its functions may return:
@table @code
£>for err in $(libgamma-error-extract --list); do
@item £{err}
£>libgamma-error-extract $err | texise
£>done
@end table

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

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


@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl.texinfo

@bye