From 97e404b5a1af5968495672351e8c2adca0ba4790 Mon Sep 17 00:00:00 2001
From: Mattias Andrée <maandree@operamail.com>
Date: Mon, 2 Jun 2014 23:24:54 +0200
Subject: info: monitors
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Signed-off-by: Mattias Andrée <maandree@operamail.com>
---
info/libgamma.texinfo | 109 +++++++++++++++++++++++++++++++++++++++++++++++---
1 file changed, 103 insertions(+), 6 deletions(-)
(limited to 'info/libgamma.texinfo')
diff --git a/info/libgamma.texinfo b/info/libgamma.texinfo
index 79cc979..e5ece45 100644
--- a/info/libgamma.texinfo
+++ b/info/libgamma.texinfo
@@ -556,6 +556,75 @@ values.
£>done
@end table
+You can test whether an adjustment method
+is available with the function
+@code{libgamma_is_method_available}. It
+takes the adjustment method's identifer
+as its only argument, and returns an
+@code{int}. The returned value is non-zero
+if and only if the adjustment exists and
+is available.
+
+A more flexible more but advanced function,
+that you probably want to use instead, is
+@code{libgamma_list_methods}. It lists all
+List available adjustment methods by their
+order of preference based on the environment,
+and can filter its output. This function
+takes three arguments:
+
+@table @asis
+@item @code{} [@code{int*}]
+Output array of adjustment method
+identifiers. It should be able to hold
+@code{LIBGAMMA_METHOD_COUNT} elements.
+
+@item @code{} [@code{size_t}]
+The number of elements that fits in
+@code{methods}, it should be
+@code{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.
+
+@item @code{} [@code{int}]
+Describes what adjustment methods to
+include. There are five valid values
+for this parameter, all other values
+invoke undefined behaviour.
+
+@table @code
+@item 0
+Adjustment methods that the environment
+suggests will work, excluding fake
+Adjustment methods.
+
+@item 1
+Adjustment methods that the environment
+suggests will work, including fake
+Adjustment methods.
+
+@item 2
+All real non-fake adjustment methods.
+
+@item 3
+All real adjustment methods.
+
+@item 4
+All adjustment methods.
+@end table
+@end table
+
+@code{libgamma_list_methods} returns an
+@code{size_t} with the value of how many
+adjustment method that should have been
+stored in the parameter @code{methods}
+if were @code{buf_size}. This value is
+how many value that have been stored
+in @code{methods} if @code{buf_size}
+is large enough.
+
@node Monitors
@@ -592,9 +661,9 @@ the data structure @code{libgamma_site_state_t}
@footnote{@code{struct libgamma_site_state}}.
This structure contains the following variables:
-@table @code
+@table @asis
£>for site in $(libgamma-method-extract --list --site-t); do
-@item £{site}
+@item @code{£{site}} [@code{£(libgamma-method-extract --type --site-t $site)}]
£>libgamma-method-extract --site-t $site | texise | sed -e 's/"/``/1' | sed -e 's/"/'\'\''/'
£>done
@end table
@@ -624,6 +693,25 @@ There you should not free it yourself, and it
must not be a string constant or allocated on
the stack. Note however that it will not be
@code{free}:d if this function fails.
+
+The name of the default site can be fetched
+with the function @code{libgamma_method_default_site}.
+It takes the value of @code{method} as its only
+argument and returns the default site's name.
+The returned value may be @code{NULL}, and
+the value should not be @code{free}:d. Because
+it should not be @code{free}:d you should
+duplicate it with @code{strdup} if it is not
+@code{NULL}. This value is @code{NULL} if
+the default site cannot be determined or if
+the adjustment method only supports one site.
+
+The function @code{libgamma_method_default_site_variable}
+works identically is @code{libgamma_method_default_site}
+except it returns the name of the environment
+variable that is read by @code{libgamma_method_default_site}
+to determine the default site for the adjustment
+method.
@end table
To release all resources held by a site state,
@@ -649,7 +737,7 @@ This structure contains the following variables:
@table @code
£>for part in $(libgamma-method-extract --list --part-t); do
-@item £{part}
+@item @code{£{part}} [@code{£(libgamma-method-extract --type --part-t $part)}]
£>libgamma-method-extract --part-t $part | texise
£>done
@end table
@@ -694,11 +782,11 @@ performs a @code{free} call for the state.
The state and identity of the partition is track
by the data structure @code{libgamma_crtc_state_t}
@footnote{@code{struct libgamma_crtc_state}}.
-This structure contains the following variables;
+This structure contains the following variables:
@table @code
£>for crtc in $(libgamma-method-extract --list --crtc-t); do
-@item £{crtc}
+@item @code{£{crtc}} [@code{£(libgamma-method-extract --type --crtc-t crtc)}]
£>libgamma-method-extract --crtc-t $crtc | texise
£>done
@end table
@@ -722,7 +810,16 @@ partition that the CRTC belongs to.
@item @code{crtc} [@code{size_t}]
The the index of the CRTC within
-the partition.
+the partition. Be aware that adjustment
+methods do not necessarily order than
+CRTC:s in the same way. For example,
+display environment may order the
+CRTC:s so that the primary monitors
+has the CRTC with index 0; but cannot
+be done if there is no concept of
+primary monitors, such as the case
+of the Linux TTY and the Linux Direct
+Rendering Manager adjustment method.
@end table
To release all resources held by a CRTC state,
--
cgit v1.2.3-70-g09d2