info: functions

Signed-off-by: Mattias Andrée <maandree@member.fsf.org>

3 files changed, 252 insertions, 2 deletions

diff --git a/Makefile.in b/Makefile.in
index 7e33613..64288e6 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -51,7 +51,8 @@ _TEXINFO_DIRLEVELS = 2
 _INFOPARTS = 0
 _HAVE_TEXINFO_MANUAL = yes
 _HTML_FILES = Free-Software-Needs-Free-Documentation.html  GNU-Free-Documentation-License.html  \
-              GNU-General-Public-License.html  index.html  Overview.html  CLUT-Manipulation.html
+              GNU-General-Public-License.html  index.html  Overview.html  CLUT-Manipulation.html  \
+              Colour-Spaces.html
 
 # Used by mk/man.mk
 #_MAN_PAGE_SECTIONS = 0 3 7
@@ -66,7 +67,7 @@ _COPYING = COPYING
 ___EVERYTHING_INFO = autohaltd titlepage-data content hardcopy-copying  \
                      appx/fdl appx/free-software-needs-free-documentation appx/gpl  \
                      reusable/macros reusable/paper reusable/titlepage  \
-                     chap/overview chap/clut-manipulation.texinfo
+                     chap/overview chap/clut-manipulation.texinfo chap/colour-spaces.texinfo
 _EVERYTHING = $(__EVERYTHING_ALL_COMMON) DEPENDENCIES INSTALL NEWS  \
               $(foreach F,$(___EVERYTHING_INFO),doc/info/$(F).texinfo)  clut.h
 
diff --git a/doc/info/chap/colour-spaces.texinfo b/doc/info/chap/colour-spaces.texinfo
new file mode 100644
index 0000000..86662c6
--- /dev/null
+++ b/doc/info/chap/colour-spaces.texinfo
@@ -0,0 +1,247 @@
+@node Colour Spaces
+@chapter Colour Spaces
+
+@command{libclut} has a number of functions for converting
+between colour space models. The supported colour space models
+are [0, 1] sRGB, [0, 1] linear RGB, CIE xyY, CIE XYZ, and CIE Lab.
+These functions are implemented as macros, but regular functions
+are available either by putting the name in the function is
+brackets, taking the address of the function, or by undefining
+the macro with the name of the function.
+
+@command{libclut} has two functions intended for internal use.
+If the macro verions are used, their parameter must not have
+any side-effets. Additionally their macro versions require
+linking with @option{-lm}.
+
+@table @code
+@item double libclut_model_linear_to_standard1(double c)
+Convert one component from [0, 1] linear RGB to [0, 1] sRGB.
+@item double libclut_model_standard_to_linear1(double c)
+Convert one component from [0, 1] sRGB to [0, 1] linear RGB.
+@end table
+
+@command{libclut} has ten functions that are intended for the
+user to use, but some are used internally too. These functions'
+parameters may have side-effects. All parameters are of the
+type @code{double}, and they do not have a return value.
+
+@table @code
+@item libclut_model_linear_to_standard(*r. *g, *b)
+Convert [0, 1] linear RGB to [0, 1] sRGB.
+
+The macro variant requires linking with @option{-lm}, if
+the @code{libclut_model_linear_to_standard1} is defined,
+otherwise it requires linking with @option{-lclut}.
+
+Parameters:
+@table @code
+@item r
+Pointer to the linear red component, and output parameter
+for the red component.
+@item g
+Pointer to the linear green component, and output parameter
+for the green component.
+@item b
+Pointer to the linear blue component, and output parameter
+for the blue component.
+@end table
+
+
+@item libclut_model_standard_to_linear(*r, *g, *b)
+Convert [0, 1] sRGB to [0, 1] linear RGB.
+
+The macro variant requires linking with @option{-lm}, if
+the @code{libclut_model_standard_to_linear1} is defined,
+otherwise it requires linking with @option{-lclut}.
+
+Parameters:
+@table @code
+@item r
+Pointer to the red component, and output parameter for the
+linear red component.
+@item g
+Pointer to the green component, and output parameter for the
+linear green component.
+@item b
+Pointer to the blue component, and output parameter for the
+linear blue component.
+@end table
+
+
+@item libclut_model_ciexyy_to_ciexyz(x, y, Y, *X, *Z)
+Convert CIE xyY to CIE XYZ.
+
+Parameters:
+@table @code
+@item x
+The x parameter.
+@item y
+The y parameter.
+@item Y
+The Y parameter. This is also the Y (middle) parameter
+for the CIE XYZ colour.
+@item X
+Output parameter for the X parameter.
+@item Z
+Output parameter for the Z parameter.
+@end table
+
+
+@item libclut_model_ciexyz_to_ciexyy(X, Y, Z, *x, *y)
+Convert CIE XYZ to CIE xyY.
+
+Parameters:
+@table @code
+@item X
+The X parameter.
+@item Y
+The Y parameter. This is also the Y (last) parameter
+for the CIE xyY colour.
+@item Z
+The Z parameter.
+@item x
+Output parameter for the x parameter.
+@item y
+Output parameter for the y parameter.
+@end table
+
+
+@item libclut_model_ciexyz_to_linear(X, Y, Z, *r, *g, *b)
+Convert CIE XYZ to [0, 1] linear RGB.
+
+Parameters:
+@table @code
+@item X
+The X parameter.
+@item Y
+The Y parameter.
+@item Z
+The Z parameter.
+@item r
+Output parameter for the red component.
+@item g
+Output parameter for the green component.
+@item b
+Output parameter for the blue component.
+@end table
+
+
+@item libclut_model_linear_to_ciexyz(r, g, b, *X, *Y, *Z)
+Convert [0, 1] linear RGB to CIE XYZ.
+
+Parameters:
+@table @code
+@item r
+The red component.
+@item g
+The green component.
+@item b
+The blue component.
+@item X
+Output parameter for the X parameter.
+@item Y
+Output parameter for the Y parameter.
+@item Z
+Output parameter for the Z parameter.
+@end table
+
+
+@item libclut_model_srgb_to_ciexyy(r, g, b, *x, *y, *Y)
+Convert [0, 1] linear RGB to CIE xyY.
+
+The macro variant requires linking with @option{-lclut}
+if any of @code{libclut_model_ciexyz_to_ciexyy},
+@code{libclut_model_linear_to_ciexyz}, and
+@code{libclut_model_standard_to_linear} are undefined.
+The macro variant requires linking with @code{-lm} if
+neither @code{libclut_model_standard_to_linear} nor
+@code{libclut_model_standard_to_linear1} are undefined.
+
+Parameters:
+@table @code
+@item r
+The red component.
+@item g
+The green component.
+@item b
+The blue component.
+@item x
+Output parameter for the x parameter.
+@item y
+Output parameter for the y parameter.
+@item Y
+Output parameter for the Y parameter.
+@end table
+
+
+@item libclut_model_ciexyy_to_srgb(x, y, Y, *r, *g, *b)
+Convert CIE xyY to [0, 1] sRGB.
+
+The macro variant requires linking with @option{-lclut}
+if any of @code{libclut_model_ciexyy_to_ciexyz},
+@code{libclut_model_ciexyz_to_linear}, and
+@code{libclut_model_linear_to_standard} are undefined.
+The macro variant requires linking with @option{-lm} if
+neither @code{libclut_model_linear_to_standard} nor
+@code{libclut_model_linear_to_standard1} are undefined.
+
+Parameters:
+@table @code
+@item x
+The x parameter.
+@item y
+The y parameter.
+@item Y
+The Y parameter.
+@item r
+Output parameter for the red component.
+@item g
+Output parameter for the green component.
+@item b
+Output parameter for the blue component.
+@end table
+
+
+@item libclut_model_ciexyz_to_cielab(X, Y, Z, *L, *a, *b)
+Convert from CIE XYZ to CIE L*a*b*.
+
+The macro variant requires linking with @option{-lm}.
+
+Parameters:
+@table @code
+@item X
+The X parameter.
+@item Y
+The Y parameter.
+@item Z
+The Z parameter.
+@item L
+Output parameter for the L* component.
+@item a
+Output parameter for the a* component.
+@item b
+Output parameter for the b* component.
+@end table
+
+
+@item libclut_model_cielab_to_ciexyz(L, a, b, *X, *Y, *Z)
+Convert from CIE L*a*b* to CIE XYZ.
+
+Parameters:
+@table @code
+@item L
+The L* component.
+@item a
+The a* component.
+@item b
+The b* component.
+@item X
+Output parameter for the X parameter.
+@item Y
+Output parameter for the Y parameter.
+@item Z
+Output parameter for the Z parameter.
+@end table
+@end table
+
diff --git a/doc/info/content.texinfo b/doc/info/content.texinfo
index 737e457..bc00f22 100644
--- a/doc/info/content.texinfo
+++ b/doc/info/content.texinfo
@@ -10,6 +10,7 @@
 @menu
 * Overview::                                Brief overview of @command{libclut}.
 * CLUT Manipulation::                       Function-like macros for CLUT manipulation.
+* Colour Spaces::                           Colour space conversion functions.
 
 * Free Software Needs Free Documentation::  Why free documentation is important.
 * GNU General Public License::              Copying and sharing @command{libclut}.
@@ -20,6 +21,7 @@
 
 @include chap/overview.texinfo
 @include chap/clut-manipulation.texinfo
+@include chap/colour-spaces.texinfo
 
 @include appx/free-software-needs-free-documentation.texinfo