diff options
Diffstat (limited to 'libglitter_redistribute_energy_double.3')
| -rw-r--r-- | libglitter_redistribute_energy_double.3 | 170 |
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) |