Add README

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

1 files changed, 65 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..55e002c
--- /dev/null
+++ b/README
@@ -0,0 +1,65 @@
+NAME
+	libglitter - Subpixel-rendering library
+
+DESCRIPTION
+	libglitter is a C library for subpixel-rendered text from
+	an greyscale-antialiased text image. 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.
+
+	To use libglitter you first need to output's pixel density,
+	then you apply hinting to the text you want to render using
+	this information. The next step is to get the output's
+	subpixel arrangement and scaling factor, then assuming that
+	the output's subpixel arrangement i subpixel-rendering
+	compatible and that the native resolution is used, you
+	multiply the output's DPI:s so that you get the number of
+	subpixels per inch instead of number of pixels per inch
+	(some subpixels may have be counted multiple times depending
+	on the subpixel arrangement) and you create a greyscale
+	raster of the text for these new DPIs. 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 libglitter_split_uint64_raster(3)
+	or libglitter_split_uint32_raster(3), alternatively you
+	create one raster for each colour channel directly. Then you
+	use libglitter_compose_double(3), libglitter_compose_float(3),
+	libglitter_compose_uint64(3), libglitter_compose_uint32(3),
+	libglitter_compose_uint16(3), or libglitter_compose_uint8(3)
+	to create the subpixel-antialiased image of the text; you
+	may have to first call libglitter_reorder_rasters(3) to
+	put the rasters in the expected order.
+
+	An optional next step is to use lessen the intensity of the
+	subpixel-antialiasing with libglitter_desaturate_double(3),
+	libglitter_desaturate_float(3), libglitter_per_channel_-
+	desaturate_double(3), or libglitter_per_channel_desaturate_-
+	float(3).
+
+	Then, if the application cannot output directly to the
+	output's colour space, the application can use
+	libglitter_get_colour_space_conversion_matrix_double(3)
+	and libglitter_colour_space_convert_rasters_double(3) or
+	libglitter_get_colour_space_conversion_matrix_float(3)
+	and libglitter_colour_space_convert_rasters_float(3) to
+	convert a colour space the application can output in.
+	It is however out of the scope of libglitter to get the
+	output's colour space and the conversion matrix to any
+	other colour space than sRGB or CIE XYZ.
+
+	The finally step of the rendering process is out of scope
+	for 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.
+
+	The application may also desire to call 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.
+
+SEE ALSO
+	libfonts(7)