path: root/libglitter.7

.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 (optionally) 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).
At this point, depending on final result, you may (will
probably) want to use
.BR libglitter_redistribute_energy_double (3)
or
.BR libglitter_redistribute_energy_float (3)
to make the text a bit blurrier but reduce colour fringing.
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.
.SH APPLICATION USAGE
Some users are more sensitive to colour while other users
are more sensitive to shape. Subpixel-antialiasing, if done
well, is a good option for users that are more sensitive
to shape. However, for users that are more sensative to
colour, subpixel-antialiasing renders glittering, and reading
subpixel-antialiased text can be headache inducing, especially
if implemented poorly or if the monitor doesn't have high
enough pixel density (for some users just above normal laptop
pixel density can be fine, but for others, not even 4K on a
laptop is good enough). For these users, greyscale-antialiasing
is a much better option. For this reason, applications must
not for subpixel-antialiasing, and should even only used it
if the user explicitly requests it.
.PP
Hinting is another important issue. For aliased text, hinting
is critical to ensure that strokes do not disappear because they
are not wide enough, but also it is important so that a stroke's
width is not doubled because it is a bit wider than a pixel or
not aligned well with the pixel grid. Hinting attempts to align
the font outline with the pixel grid. For greyscale-antialiased
text, hinting as not as important, but it removes blurring and
dim strokes. However some people are more bothered by hinting
artefacts, so hinting should not always be applied. For
subpixel-antialiased text, hinting is not as important as for
aliased text, but it is more much important than on
greyscale-antialiased text. For subpixel-antialiased text,
hinting removes fringing (colours along the edge of a stroke)
and miscoloured strokes, strokes can even disappear: for
example, if the stroke only hits blue subpixels, but should be
rendered as pure red (the primary colour) on black, there will
only be black, as that is what primary red muliplied by primary
blue results in. Applications are discourage for using
subpixel-rendering on non-hinted text unless that user
explicitly says it he wants subpixel-rendered text even it will
look bad (presumably to see how it looks). Subpixel-rendering
may also be a bad idea on coloured text.
.PP
Because subpixel-rendering is entirely dependent on the subpixel
layout, it is inappropriate to use subpixel-rendering unless the
subpixel layout is known, and the text is rendered specifically
for that subpixel layout, or if the resulting raster is scaled
post-rendering, for example if the output native resultion is
3840x2400, but the computer outputs 1920x1200, (and the output
is scaled up by a factor of 2 per dimension). The purpose of
subpixel-rendering is defeated in such situations.
.PP
For best result, the application shall take into consideration
both the output's vertical pixel density and horizontal pixel
density, subpixel order, subpixel layout, output scaling, the
output's colour model's transfer function (gamma compression),
hinting, and text and background colour. If text is rendered with
light on dark colours, but the font is not designed for reverse
type, the application may desire to apply more aggressive hinting.
The application shall also output the text image in the colour's
native colour model: as the primary colours' chromacity may
differ from sRGB, it is possible that when outputing colour it
is intepreted as sRGB, and converting to the output's colour
model, which may change the activation level on the subpixels
as compared to how it was rendered. Applications should also
if possible attempt align strokes to the pixel-grid rather than
the subpixel grid: if you have a monitor with vertical stripes
of subpixels, and draw a white, one pixel wide vertical line
on black, it will look like a white-on-black line, but not so
if you shift the line over one pixel, suddenly it becomes two
inversely coloured lines (this does however depend on the
monitor: there are less common monitors that are actually
designed so that this doesn't happen: they use a different
pixel model).
.PP
Applications should be aware that the user's may use different
monitors and may therefore need to render text differently
depending on which output the text is being displayed on. This
may even include changing the text's pixel size, which can be
very problematic (depending on the context) if the text is
split over two output; however the user probably not reading
the text if it is split over two outputs, so simply basing
the pixel size of one of the monitors or averaging them is
probably good enough in that case.
.SH SEE ALSO
.BR libfonts (7)