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

@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}.
* 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 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 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

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.



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

@bye