Add libglitter_redistribute_energy_double.3

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

1 files changed, 170 insertions, 0 deletions

diff --git a/libglitter_redistribute_energy_double.3 b/libglitter_redistribute_energy_double.3
new file mode 100644
index 0000000..4aa0897
--- /dev/null
+++ b/libglitter_redistribute_energy_double.3
@@ -0,0 +1,170 @@
+.TH LIBGLITTER_REDISTRIBUTE_ENERGY_* 3 LIBGLITTER
+.SH NAME
+libglitter_redistribute_energy_* - Slight blur a text to significantly reduce colour fringing
+.SH SYNOPSIS
+.LP
+.nf
+#include <libglitter.h>
+
+void libglitter_redistribute_energy_double(double *restrict \fIraster\fP, size_t \fIrowsize\fP,
+                                           size_t \fIwidth\fP, size_t \fIheight\fP,
+                                           size_t \fIhkernelsize\fP, size_t \fIvkernelsize\fP,
+                                           const double *\fIhkernel\fP, const double *\fIvkernel\fP);
+
+void libglitter_redistribute_energy_float(float *restrict \fIraster\fP, size_t \fIrowsize\fP,
+                                          size_t \fIwidth\fP, size_t \fIheight\fP,
+                                          size_t \fIhkernelsize\fP, size_t \fIvkernelsize\fP,
+                                          const float *\fIhkernel\fP, const float *\fIvkernel\fP);
+.fi
+.PP
+Link with
+.IR "-lglitter -lm" .
+.SH DESCRIPTION
+The
+.BR libglitter_redistribute_energy_double ()
+and
+.BR libglitter_redistribute_energy_float ()
+functions up to two 1-dimension convolution kernels (one horizontal
+and one vertical) to a raster. The goal is to slightly blur
+(redistribute energy between adjacent subpixels) the text
+which reduces colour fringing.
+.PP
+The
+.I raster
+argument shall be the an image of the text rendered at
+subpixel-resolution. It will be modified in place. It
+shall be a row-major ordered raster where horizontally
+adjacent cells are adjacent in memory (the shall not
+be any gapes between the cells' memory areas), however
+they may be unused memory between each row. The
+.I width
+parameter specifies how many cells there are, horizontally,
+in the image. The
+.I rowsize
+parameter specifies how many cells a pointer must be offset
+with to mow down a row but stay in the same column: it is
+.I width
+plus the number of unused elements between each row.
+The
+.I height
+parameter specifies how many cells there are, vertically,
+in the image.
+.PP
+The functions apply the horizontal convolution kernel
+.I hkernel
+and the
+vertical convolution kernel
+.I vkernel
+to the raster. The functions may assume that the sub of
+the elements in each kernel is 1. Each kernel shall have
+an odd size. The size is specified via the
+.I hkernelsize
+parameter for
+.I hkernel
+and the
+.I vkernelsize
+parameter for
+.IR vkernel .
+If
+.I hkernelsize
+is 1,
+.I hkernel
+will be ignored and may be
+.IR NULL .
+If
+.I vkernelsize
+is 1,
+.I vkernel
+will be ignored and may be
+.IR NULL .
+The kernels are applied to each cell offset by the half
+of the kernelsize (less 1). However, the function shifts
+the image by
+.I (hkernelsize-1)/2
+cells to the left, and also extends the image by this
+amount both on the left and on the right, and it also
+shifts the image by
+.I (vkernelsize-1)/2
+cells to upwards, and and also extends the image by
+this amount both above and below.
+.PP
+Because the function is extends the image by
+.I (hkernelsize-1)
+cells horizontally and by
+.I (vkernelsize-1)
+cells vertically, the user must provide a raster that
+is prepadded with zeroes. This padding shall be
+.I (hkernelsize-1)
+cells on the left and
+.I (vkernelsize-1)
+cells on the top; nothing on the right or on the buttom.
+But the pointer
+.I raster
+shall point to the first cell after this padding; after
+the function returns however, the new raster starts at
+the first cell in the padding. But additionally, the
+user must pad each edge of the raster with zeroes so
+there is a raster, than can be input to
+.BR libglitter_compose_double (3)
+and
+.BR libglitter_compose_float (3),
+first the first cell in the raster is the first cell of
+the first pixel and which have all cells for all pixels.
+Specifically, the user shall extend the raster further by
+.I (widthmul-(hkernelsize-1)/2%widthmul)%widthmul
+cells on both the left and on the right, and by
+.I (heightmul-(vkernelsize-1)/2%heightmul)%heightmul
+cells on both the top and on the bottom, where
+.I widthmul
+and
+.I heightmul
+are arguments to the
+.BR libglitter_create_render_context (3)
+function.
+.PP
+By default, these functions do not use hardware acceleration,
+they run on the CPU. However the
+.BR libglitter_enable_acceleration (3)
+may be able to enable hardware acceleration for these
+functions. It will require at least the following bits in
+its first argument to enable hardware acceleration:
+.RS
+.TP
+.I LIBGLITTER_FEATURE_REDISTRIBUTE | LIBGLITTER_FEATURE_DOUBLE_TYPE
+for
+.BR libglitter_redistribute_energy_double (),
+or
+.TP
+.I LIBGLITTER_FEATURE_REDISTRIBUTE | LIBGLITTER_FEATURE_FLOAT_TYPE
+for
+.BR libglitter_redistribute_energy_float ().
+.RE
+.SH APPLICATION USAGE
+The value 1 is suggested for
+.I hkernelsize
+if the monitor uses vertically stacked subpixels,
+the value 3 with the
+.I hkernel
+.I {1/3.,1/3.,1/3.}
+is suggested otherwise as a starting point.
+Similarly, the value 1 is suggested for
+.I vkernelsize
+if the monitor uses horizontally stacked subpixels,
+the value 3 with the
+.I vkernel
+.I {1/3.,1/3.,1/3.} 
+is suggested otherwise as a starting point. Because of
+both monitor differences, and more important, user
+differences, experimentation from the user is required
+the find the best convolution kernels, however, it is
+safe to assumes that the suggestions on the singleton
+kernel
+.RI ( {1} )
+is optional when suggested.
+.SH RETURN VALUES
+None.
+.SH ERRORS
+None.
+.SH SEE ALSO
+.BR libglitter (7),
+.BR libglitter_compose_double (3)