@node CLUT Manipulation
@chapter CLUT Manipulation

@command{libclut} has a number of function-like macros
for manipulating colour lookup tables. These have
3 common initial parameters, that describe the
colour lookup table that shall be manipulated.
@table @code
@item clut
Pointer to the gamma ramps. This must be a pointer
to an instance of a @code{struct} that must at least
have the array members @code{red}, @code{green}, and
@code{blue}, whose elements shall be of the type
specified by the parameter @code{type}. The @code{struct}
must also have the scalar members @code{red_size},
@code{green_size}, and @code{blue_size}, and shall be
of the type @code{size_t}; they shall specify the
number of stops (elements) in the arrays @code{.red},
@code{.green}, and @code{.blue}, respectively, which
shall be the gamma ramp for the ``red''@footnote{Acutally
orange.}, green, and blue channels respectively.
@item max
The maximum value on each stop in the ramps.
@item type
The data type used for each stop in the ramps.
@end table
@noindent
Additionally, these macros do not allow that arguments
have side-effects.@footnote{Some macros currently allow
side-effects on some parameters, but this may change
in the future.} None, if the macros have a return value.

@table @code
@item libclut_rgb_contrast(clut, max, type, r, g, b)
Apply contrast correction on the colour curves using sRGB.

In this context, contrast is a measure of difference between
the whitepoint and blackpoint, if the difference is 0 than
they are both grey.

Parameters:
@table @code
@item r
The contrast parameter for the red curve.
@item g
The contrast parameter for the green curve.
@item b
The contrast parameter for the blue curve.
@end table


@item libclut_cie_contrast(clut, max, type, r, g, b)
Apply contrast correction on the colour curves using CIE xyY.

In this context, contrast is a measure of difference between
the whitepoint and blackpoint, if the difference is 0 than
they are both grey.

Requires linking with @option{-lclut}.

Parameters:
@table @code
@item r
The contrast parameter for the red curve.
@item g
The contrast parameter for the green curve.
@item b
The contrast parameter for the blue curve.
@end table


@item libclut_rgb_brightness(clut, max, type, r, g, b)
Apply brightness correction on the colour curves using sRGB.

In this context, brightness is a measure of the whiteness
of the whitepoint.

Parameters:
@table @code
@item r
The brightness parameter for the red curve.
@item g
The brightness parameter for the green curve.
@item b
The brightness parameter for the blue curve.
@end table


@item libclut_cie_brightness(clut, max, type, r, g, b)
Apply brightness correction on the colour curves using CIE xyY.

In this context, brightness is a measure of the whiteness
of the whitepoint.

Requires linking with @option{-lclut}.

Parameters:
@table @code
@item r
The brightness parameter for the red curve.
@item g
The brightness parameter for the green curve.
@item b
The brightness parameter for the blue curve.
@end table


@item libclut_linearise(clut, max, type, r, g, b)
Convert the curves from formatted in standard RGB to linear RGB.

Requires linking with @option{-lclut}, or @option{-lm} if
@code{libclut_model_standard_to_linear1} is not undefined.

Parameters:
@table @code
@item r
Whether to convert the red colour curve.
@item g
Whether to convert the green colour curve.
@item b
Whether to convert the blue colour curve.
@end table


@item libclut_standardise(clut, max, type, r, g, b)
Convert the curves from formatted in linear RGB to standard RGB.

Requires linking with @option{-lclut}, or @option{-lm} if
@code{libclut_model_linear_to_standard1} is not undefined.

Parameters:
@table @code
@item r
Whether to convert the red colour curve.
@item g
Whether to convert the green colour curve.
@item b
Whether to convert the blue colour curve.
@end table


@item libclut_gamma(clut, max, type, r, g, b)
Apply gamma correction on the colour curves.

Requires linking with @option{-lm}.

Parameters:
@table @code
@item r
The gamma parameter for the red curve.
@item g
The gamma parameter for the green curve.
@item b
The gamma parameter for the blue curve.
@end table


@item libclut_negative(clut, max, type, r, g, b)
Reverse the colour curves (negative image with gamma preservation.)

Parameters:
@table @code
@item r
Whether to reverse the red colour curve.
@item g
Whether to reverse the green colour curve.
@item b
Whether to reverse the blue colour curve.
@end table


@item libclut_rgb_invert(clut, max, type, r, g, b)
Invert the colour curves (negative image with gamma
invertion), using sRGB.

Parameters:
@table @code
@item r
Whether to invert the red colour curve.
@item g
Whether to invert the green colour curve.
@item b
Whether to invert the blue colour curve.
@end table


@item libclut_cie_invert(clut, max, type, r, g, b)
Invert the colour curves (negative image with gamma
invertion), using CIE xyY.

Requires linking with @option{-lclut}.

Parameters:
@table @code
@item r
Whether to invert the red colour curve.
@item g
Whether to invert the green colour curve.
@item b
Whether to invert the blue colour curve.
@end table


@item libclut_sigmoid(clut, max, type, rp, gp, bp)
Apply S-curve correction on the colour curves.
This is intended for fine tuning LCD monitors,
4.5 is good value start start testing at.
You would probably like to use @code{rgb_limits}
before this to adjust the blackpoint as that is
the only way to adjust the blackpoint on many LCD
monitors.

Requires linking with @option{-lm}.

Parameters:
@table @code
@item rp
Pointer to the sigmoid parameter for the red curve.
@code{NULL} for no adjustment.
@item gp
Pointer to the sigmoid parameter for the green curve.
@code{NULL} for no adjustment.
@item bp
Pointer to the sigmoid parameter for the blue curve.
@code{NULL} for no adjustment.
@end table


@item libclut_rgb_limits(clut, max, type, rmin, rmax, gmin, gmax, bmin, bmax)
Changes the blackpoint and the whitepoint, using sRGB.

Parameters:
@table @code
@item rmin
The red component value of the blackpoint.
That is, the brightness on the red channel.
@item rmax
The red component value of the whitepoint.
That is, the contrast on the red channel.
@item gmin
The green component value of the blackpoint.
That is, the brightness on the green channel.
@item gmax
The green component value of the whitepoint.
That is, the contrast on the green channel.
@item bmin
The blue component value of the blackpoint.
That is, the brightness on the blue channel.
@item bmax
The blue component value of the whitepoint.
That is, the contrast on the blue channel.
@end table


@item libclut_cie_limits(clut, max, type, rmin, rmax, gmin, gmax, bmin, bmax)
Changes the blackpoint and the whitepoint, using CIE xyY.

Requires linking with @option{-lclut}.

Parameters:
@table @code
@item rmin
The red component value of the blackpoint.
That is, the brightness on the red channel.
@item rmax
The red component value of the whitepoint.
That is, the contrast on the red channel.
@item gmin
The green component value of the blackpoint.
That is, the brightness on the green channel.
@item gmax
The green component value of the whitepoint.
That is, the contrast on the green channel.
@item bmin
The blue component value of the blackpoint.
That is, the brightness on the blue channel.
@item bmax
The blue component value of the whitepoint.
That is, the contrast on the blue channel.
@end table


@item libclut_manipulate(clut, max, type, r, g, b)
Manipulate the colour curves using a function on the
sRGB colour space.

Parameters:
@table @code
@item r
Function to manipulate the red colour curve. It
shall map from old stop values to new stop values.
This should either be @code{NULL} for no manipulation,
or a function that maps from @code{double} to
@code{double}. 0 % and 100 % is encoded as 0 and 1,
respectively, in both input and ouput. Its signature
should be @code{double (*)(double)}.
@item g
Function to manipulate the green colour curve. It
shall map from old stop values to new stop values.
This should either be @code{NULL} for no manipulation,
or a function that maps from @code{double} to
@code{double}. 0 % and 100 % is encoded as 0 and 1,
respectively, in both input and ouput. Its signature
should be @code{double (*)(double)}.
@item b
Function to manipulate the blue colour curve. It
shall map from old stop values to new stop values.
This should either be @code{NULL} for no manipulation,
or a function that maps from @code{double} to
@code{double}. 0 % and 100 % is encoded as 0 and 1,
respectively, in both input and ouput. Its signature
should be @code{double (*)(double)}.
@end table


@item libclut_cie_manipulate(clut, max, type, r, g, b)
Manipulate the colour curves using a function on the
CIE xyY colour space.

Requires linking with @option{-lclut}.

Parameters:
@table @code
@item r
Function to manipulate the red colour curve. It
shall map from old stop values to new stop values.
This should either be @code{NULL} for no manipulation,
or a function that maps from @code{double} to
@code{double}. 0 % and 100 % is encoded as 0 and 1,
respectively, in both input and ouput. Its signature
should be @code{double (*)(double)}.
@item g
Function to manipulate the green colour curve. It
shall map from old stop values to new stop values.
This should either be @code{NULL} for no manipulation,
or a function that maps from @code{double} to
@code{double}. 0 % and 100 % is encoded as 0 and 1,
respectively, in both input and ouput. Its signature
should be @code{double (*)(double)}.
@item b
Function to manipulate the blue colour curve. It
shall map from old stop values to new stop values.
This should either be @code{NULL} for no manipulation,
or a function that maps from @code{double} to
@code{double}. 0 % and 100 % is encoded as 0 and 1,
respectively, in both input and ouput. Its signature
should be @code{double (*)(double)}.
@end table


@item libclut_start_over(clut, max, type, r, g, b)
Resets colour curvers to linear mappings.
(Identity mapping if imaginged to map from [0, 1] to [0, 1].)

Parameters:
@table @code
@item r
Whether to reset the red colour curve.
@item g
Whether to reset the green colour curve.
@item b
Whether to reset the blue colour curve.
@end table


@item libclut_clip(clut, max, type, r, g, b)
Clip colour curves to only map to values between the
minimum and maximum. This should be done, before apply
the curves, and before applying changes with limited
domain.

Values below 0 are set to 0, and values above @code{max}
are set to @code{max}.

Parameters:
@table @code
@item r
Whether to clip the red colour curve.
@item g
Whether to clip the green colour curve.
@item b
Whether to clip the blue colour curve.
@end table


@item libclut_lower_resolution(clut, max, type, rx, ry, gx, gy, bx, by)
Emulates low colour resolution.

Parameters:
@table @code
@item rx
The desired emulated red encoding resolution,
0 for unchanged.
@item ry
The desired emulated red output resolution,
0 for unchanged.
@item gx
The desired emulated green encoding resolution,
0 for unchanged.
@item gy
The desired emulated green output resolution,
0 for unchanged.
@item bx
The desired emulated blue encoding resolution,
0 for unchanged.
@item by
The desired emulated blue output resolution,
0 for unchanged.
@end table


@item libclut_apply(clut, max, type, filter, fmax, ftype, r, g, b)
Applies a filter or calibration.

Parameters:
@table @code
@item filter
Same as @code{clut}, but for the filter to apply.
@item fmax
Same as @code{max}, but for the filter to apply.
@item ftype
Same as @code{type}, but for the filter to apply.
(Not actually used.)
@item r
Whether to apply the filter for the red curve.
@item g
Whether to apply the filter for the green curve.
@item b
Whether to apply the filter for the blue curve.
@end table


@item libclut_cie_apply(clut, max, type, filter, fmax, ftype, r, g, b)
Applies a filter or calibration, using CIE xyY.

Requires linking with @option{-lclut}.

Parameters:
@table @code
@item filter
Same as @code{clut}, but for the filter to apply.
@item fmax
Same as @code{max}, but for the filter to apply.
@item ftype
Same as @code{type}, but for the filter to apply.
(Not actually used.)
@item r
Whether to apply the filter for the red curve.
@item g
Whether to apply the filter for the green curve.
@item b
Whether to apply the filter for the blue curve.
@end table


@item libclut_translate(dclut, dmax, dtype, sclut, smax, stype)
Translates a gamma ramp structure to another
gamma ramp structure type.

Parameters:
@table @code
@item dclut
Like @code{clut} described above, for the destination.
@item dmax
Like @code{max} described above, for the destination.
@item dtype
Like @code{type} described above, for the destination.
@item sclut
Like @code{clut} described above, for the source.
@item smax
Like @code{max} described above, for the source.
@item stype
Like @code{type} described above, for the source.
(Not actually used.)
@end table
@end table