Add man pages + some minor fixes

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 89 insertions, 0 deletions

diff --git a/libglitter.7 b/libglitter.7
new file mode 100644
index 0000000..a446eeb
--- /dev/null
+++ b/libglitter.7
@@ -0,0 +1,89 @@
+.TH LIBGLITTER 7 LIBGLITTER
+.SH NAME
+libglitter - Subpixel-rendering library
+.SH DESCRIPTION
+.B libglitter
+is a C library for subpixel-rendered text from an
+greyscale-antialiased text image.
+.B libglitter
+is designed to be
+used in conjunction with other font libraries: it can neither
+rasterise glyphs nor does it know about the montor's subpixel
+layout or rendering configurations.
+.PP
+To use
+.B libglitter
+you first apply hinting to the text so that
+the glyph outlines aligns with the output's pixel-grid as
+closely as possible. The next step is to get the output's
+subpixel arrangement and scaling factor, then assuming that
+the output's subpixel arrangement is subpixel-rendering
+compatible and that its native resolution is used, you
+rasterise the text using greyscale-antialiasing into a raster
+sized according to the output's horizontal and vertical
+subpixel densities (rather than pixel densities as normally
+done with greyscale-antialiasing; some subpixels may have be
+counted multiple times depending on the subpixel arrangement).
+After this you create an uninitialised colour raster for text
+and the output's pixel density, and split it into one raster
+per colour channel using
+.BR libglitter_split_uint64_raster (3)
+or
+.BR libglitter_split_uint32_raster (3),
+this is when
+.B libglitter
+is first used in this process; alternatively you create one
+raster for each colour channel directly. Then you use
+.BR libglitter_compose_double (3),
+.BR libglitter_compose_float (3),
+.BR libglitter_compose_uint64 (3),
+.BR libglitter_compose_uint32 (3),
+.BR libglitter_compose_uint16 (3),
+or
+.BR libglitter_compose_uint8 (3)
+to create the subpixel-antialiased image of the text; you may
+have to first call
+.BR libglitter_reorder_rasters (3)
+to put the rasters in the expected order.
+.PP
+An optional next step is to use lessen the intensity of the
+subpixel-antialiasing with
+.BR libglitter_desaturate_double (3),
+.BR libglitter_desaturate_float (3),
+.BR libglitter_per_channel_desaturate_double (3),
+or
+.BR libglitter_per_channel_desaturate_float (3).
+.PP
+Then, if the application cannot output directly to the
+output's colour model, the application can use
+.BR libglitter_get_colour_model_conversion_matrix_double (3)
+and
+.BR libglitter_colour_model_convert_rasters_double (3)
+or
+.BR libglitter_get_colour_model_conversion_matrix_float (3)
+and
+.BR libglitter_colour_model_convert_rasters_float (3)
+to convert a colour model the application can output in. It is
+however out of the scope of
+.B libglitter
+to get the output's
+colour model and the conversion matrix to any other colour
+model than sRGB or CIE XYZ.
+.PP
+The finally step of the rendering process is out of scope for
+.BR libglitter ,
+but is to ensure that all floating-point values
+(if floating-point rasters are used) are withing [0, 1] and
+convert the rasters, which only contain ink-on intensities,
+into the desired colour's with the output's transfer function
+applied.
+.PP
+The application may also desire to call
+.BR libglitter_enable_acceleration (3)
+at the beginning of its execution to enable
+any implemented and supported hardware acceleration. This
+may however be an expensive process, and may not be
+desirable for all applications.
+.PP
+.SH SEE ALSO
+.BR libfonts (7)