.TH "caca_dither" 3caca "Wed Mar 10 2021" "Version 0.99.beta19" "libcaca" \" -*- nroff -*-
.ad l
.nh
.SH NAME
caca_dither \- libcaca bitmap dithering
.SH SYNOPSIS
.br
.PP
.SS "Modules"

.in +1c
.ti -1c
.RI "\fBlibcaca character font handling\fP"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "__extern \fBcaca_dither_t\fP * \fBcaca_create_dither\fP (int, int, int, int, uint32_t, uint32_t, uint32_t, uint32_t)"
.br
.RI "Create an internal dither object\&. "
.ti -1c
.RI "__extern int \fBcaca_set_dither_palette\fP (\fBcaca_dither_t\fP *, uint32_t r[], uint32_t g[], uint32_t b[], uint32_t a[])"
.br
.RI "Set the palette of an 8bpp dither object\&. "
.ti -1c
.RI "__extern int \fBcaca_set_dither_brightness\fP (\fBcaca_dither_t\fP *, float)"
.br
.RI "Set the brightness of a dither object\&. "
.ti -1c
.RI "__extern float \fBcaca_get_dither_brightness\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "Get the brightness of a dither object\&. "
.ti -1c
.RI "__extern int \fBcaca_set_dither_gamma\fP (\fBcaca_dither_t\fP *, float)"
.br
.RI "Set the gamma of a dither object\&. "
.ti -1c
.RI "__extern float \fBcaca_get_dither_gamma\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "Get the gamma of a dither object\&. "
.ti -1c
.RI "__extern int \fBcaca_set_dither_contrast\fP (\fBcaca_dither_t\fP *, float)"
.br
.RI "Set the contrast of a dither object\&. "
.ti -1c
.RI "__extern float \fBcaca_get_dither_contrast\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "Get the contrast of a dither object\&. "
.ti -1c
.RI "__extern int \fBcaca_set_dither_antialias\fP (\fBcaca_dither_t\fP *, char const *)"
.br
.RI "Set dither antialiasing\&. "
.ti -1c
.RI "__extern char const  *const  * \fBcaca_get_dither_antialias_list\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "Get available antialiasing methods\&. "
.ti -1c
.RI "__extern char const  * \fBcaca_get_dither_antialias\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "Get current antialiasing method\&. "
.ti -1c
.RI "__extern int \fBcaca_set_dither_color\fP (\fBcaca_dither_t\fP *, char const *)"
.br
.RI "Choose colours used for dithering\&. "
.ti -1c
.RI "__extern char const  *const  * \fBcaca_get_dither_color_list\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "Get available colour modes\&. "
.ti -1c
.RI "__extern char const  * \fBcaca_get_dither_color\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "Get current colour mode\&. "
.ti -1c
.RI "__extern int \fBcaca_set_dither_charset\fP (\fBcaca_dither_t\fP *, char const *)"
.br
.RI "Choose characters used for dithering\&. "
.ti -1c
.RI "__extern char const  *const  * \fBcaca_get_dither_charset_list\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "Get available dither character sets\&. "
.ti -1c
.RI "__extern char const  * \fBcaca_get_dither_charset\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "Get current character set\&. "
.ti -1c
.RI "__extern int \fBcaca_set_dither_algorithm\fP (\fBcaca_dither_t\fP *, char const *)"
.br
.RI "Set dithering algorithm\&. "
.ti -1c
.RI "__extern char const  *const  * \fBcaca_get_dither_algorithm_list\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "Get dithering algorithms\&. "
.ti -1c
.RI "__extern char const  * \fBcaca_get_dither_algorithm\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "Get current dithering algorithm\&. "
.ti -1c
.RI "__extern int \fBcaca_dither_bitmap\fP (\fBcaca_canvas_t\fP *, int, int, int, int, \fBcaca_dither_t\fP const *, void const *)"
.br
.RI "Dither a bitmap on the canvas\&. "
.ti -1c
.RI "__extern int \fBcaca_free_dither\fP (\fBcaca_dither_t\fP *)"
.br
.RI "Free the memory associated with a dither\&. "
.in -1c
.SH "Detailed Description"
.PP 
These functions provide high level routines for dither allocation and rendering\&. 
.SH "Function Documentation"
.PP 
.SS "__extern \fBcaca_dither_t\fP* caca_create_dither (int bpp, int w, int h, int pitch, uint32_t rmask, uint32_t gmask, uint32_t bmask, uint32_t amask)"
Create a dither structure from its coordinates (depth, width, height and pitch) and pixel mask values\&. If the depth is 8 bits per pixel, the mask values are ignored and the colour palette should be set using the \fBcaca_set_dither_palette()\fP function\&. For depths greater than 8 bits per pixel, a zero alpha mask causes the alpha values to be ignored\&.
.PP
If an error occurs, NULL is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Requested width, height, pitch or bits per pixel value was invalid\&.
.IP "\(bu" 2
\fCENOMEM\fP Not enough memory to allocate dither structure\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fIbpp\fP Bitmap depth in bits per pixel\&. 
.br
\fIw\fP Bitmap width in pixels\&. 
.br
\fIh\fP Bitmap height in pixels\&. 
.br
\fIpitch\fP Bitmap pitch in bytes\&. 
.br
\fIrmask\fP Bitmask for red values\&. 
.br
\fIgmask\fP Bitmask for green values\&. 
.br
\fIbmask\fP Bitmask for blue values\&. 
.br
\fIamask\fP Bitmask for alpha values\&. 
.RE
.PP
\fBReturns\fP
.RS 4
Dither object upon success, NULL if an error occurred\&. 
.RE
.PP

.SS "__extern int caca_set_dither_palette (\fBcaca_dither_t\fP * d, uint32_t red[], uint32_t green[], uint32_t blue[], uint32_t alpha[])"
Set the palette of an 8 bits per pixel bitmap\&. Values should be between 0 and 4095 (0xfff)\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Dither bits per pixel value is not 8, or one of the pixel values was outside the range 0 - 4095\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fId\fP Dither object\&. 
.br
\fIred\fP Array of 256 red values\&. 
.br
\fIgreen\fP Array of 256 green values\&. 
.br
\fIblue\fP Array of 256 blue values\&. 
.br
\fIalpha\fP Array of 256 alpha values\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.SS "__extern int caca_set_dither_brightness (\fBcaca_dither_t\fP * d, float brightness)"
Set the brightness of dither\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Brightness value was out of range\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fId\fP Dither object\&. 
.br
\fIbrightness\fP brightness value\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.SS "__extern float caca_get_dither_brightness (\fBcaca_dither_t\fP const * d)"
Get the brightness of the given dither object\&.
.PP
This function never fails\&.
.PP
\fBParameters\fP
.RS 4
\fId\fP Dither object\&. 
.RE
.PP
\fBReturns\fP
.RS 4
Brightness value\&. 
.RE
.PP

.SS "__extern int caca_set_dither_gamma (\fBcaca_dither_t\fP * d, float gamma)"
Set the gamma of the given dither object\&. A negative value causes colour inversion\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Gamma value was out of range\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fId\fP Dither object\&. 
.br
\fIgamma\fP Gamma value\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.SS "__extern float caca_get_dither_gamma (\fBcaca_dither_t\fP const * d)"
Get the gamma of the given dither object\&.
.PP
This function never fails\&.
.PP
\fBParameters\fP
.RS 4
\fId\fP Dither object\&. 
.RE
.PP
\fBReturns\fP
.RS 4
Gamma value\&. 
.RE
.PP

.SS "__extern int caca_set_dither_contrast (\fBcaca_dither_t\fP * d, float contrast)"
Set the contrast of dither\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Contrast value was out of range\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fId\fP Dither object\&. 
.br
\fIcontrast\fP contrast value\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.SS "__extern float caca_get_dither_contrast (\fBcaca_dither_t\fP const * d)"
Get the contrast of the given dither object\&.
.PP
This function never fails\&.
.PP
\fBParameters\fP
.RS 4
\fId\fP Dither object\&. 
.RE
.PP
\fBReturns\fP
.RS 4
Contrast value\&. 
.RE
.PP

.SS "__extern int caca_set_dither_antialias (\fBcaca_dither_t\fP * d, char const * str)"
Tell the renderer whether to antialias the dither\&. Antialiasing smoothens the rendered image and avoids the commonly seen staircase effect\&.
.IP "\(bu" 2
\fC"none"\fP: no antialiasing\&.
.IP "\(bu" 2
\fC"prefilter"\fP or \fC"default"\fP: simple prefilter antialiasing\&. This is the default value\&.
.PP
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Invalid antialiasing mode\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fId\fP Dither object\&. 
.br
\fIstr\fP A string describing the antialiasing method that will be used for the dithering\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.SS "__extern char const* const* caca_get_dither_antialias_list (\fBcaca_dither_t\fP const * d)"
Return a list of available antialiasing methods for a given dither\&. The list is a NULL-terminated array of strings, interleaving a string containing the internal value for the antialiasing method to be used with \fBcaca_set_dither_antialias()\fP, and a string containing the natural language description for that antialiasing method\&.
.PP
This function never fails\&.
.PP
\fBParameters\fP
.RS 4
\fId\fP Dither object\&. 
.RE
.PP
\fBReturns\fP
.RS 4
An array of strings\&. 
.RE
.PP

.SS "__extern char const* caca_get_dither_antialias (\fBcaca_dither_t\fP const * d)"
Return the given dither's current antialiasing method\&.
.PP
This function never fails\&.
.PP
\fBParameters\fP
.RS 4
\fId\fP Dither object\&. 
.RE
.PP
\fBReturns\fP
.RS 4
A static string\&. 
.RE
.PP

.SS "__extern int caca_set_dither_color (\fBcaca_dither_t\fP * d, char const * str)"
Tell the renderer which colours should be used to render the bitmap\&. Valid values for \fCstr\fP are:
.IP "\(bu" 2
\fC"mono"\fP: use light gray on a black background\&.
.IP "\(bu" 2
\fC"gray"\fP: use white and two shades of gray on a black background\&.
.IP "\(bu" 2
\fC"8"\fP: use the 8 ANSI colours on a black background\&.
.IP "\(bu" 2
\fC"16"\fP: use the 16 ANSI colours on a black background\&.
.IP "\(bu" 2
\fC"fullgray"\fP: use black, white and two shades of gray for both the characters and the background\&.
.IP "\(bu" 2
\fC"full8"\fP: use the 8 ANSI colours for both the characters and the background\&.
.IP "\(bu" 2
\fC"full16"\fP or \fC"default"\fP: use the 16 ANSI colours for both the characters and the background\&. This is the default value\&.
.PP
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Invalid colour set\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fId\fP Dither object\&. 
.br
\fIstr\fP A string describing the colour set that will be used for the dithering\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.SS "__extern char const* const* caca_get_dither_color_list (\fBcaca_dither_t\fP const * d)"
Return a list of available colour modes for a given dither\&. The list is a NULL-terminated array of strings, interleaving a string containing the internal value for the colour mode, to be used with \fBcaca_set_dither_color()\fP, and a string containing the natural language description for that colour mode\&.
.PP
This function never fails\&.
.PP
\fBParameters\fP
.RS 4
\fId\fP Dither object\&. 
.RE
.PP
\fBReturns\fP
.RS 4
An array of strings\&. 
.RE
.PP

.SS "__extern char const* caca_get_dither_color (\fBcaca_dither_t\fP const * d)"
Return the given dither's current colour mode\&.
.PP
This function never fails\&.
.PP
\fBParameters\fP
.RS 4
\fId\fP Dither object\&. 
.RE
.PP
\fBReturns\fP
.RS 4
A static string\&. 
.RE
.PP

.SS "__extern int caca_set_dither_charset (\fBcaca_dither_t\fP * d, char const * str)"
Tell the renderer which characters should be used to render the dither\&. Valid values for \fCstr\fP are:
.IP "\(bu" 2
\fC"ascii"\fP or \fC"default"\fP: use only ASCII characters\&. This is the default value\&.
.IP "\(bu" 2
\fC"shades"\fP: use Unicode characters 'U+2591 LIGHT SHADE', 'U+2592
  MEDIUM SHADE' and 'U+2593 DARK SHADE'\&. These characters are also present in the CP437 codepage available on DOS and VGA\&.
.IP "\(bu" 2
\fC"blocks"\fP: use Unicode quarter-cell block combinations\&. These characters are only found in the Unicode set\&.
.PP
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Invalid character set\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fId\fP Dither object\&. 
.br
\fIstr\fP A string describing the characters that need to be used for the dithering\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.SS "__extern char const* const* caca_get_dither_charset_list (\fBcaca_dither_t\fP const * d)"
Return a list of available character sets for a given dither\&. The list is a NULL-terminated array of strings, interleaving a string containing the internal value for the character set, to be used with \fBcaca_set_dither_charset()\fP, and a string containing the natural language description for that character set\&.
.PP
This function never fails\&.
.PP
\fBParameters\fP
.RS 4
\fId\fP Dither object\&. 
.RE
.PP
\fBReturns\fP
.RS 4
An array of strings\&. 
.RE
.PP

.SS "__extern char const* caca_get_dither_charset (\fBcaca_dither_t\fP const * d)"
Return the given dither's current character set\&.
.PP
This function never fails\&.
.PP
\fBParameters\fP
.RS 4
\fId\fP Dither object\&. 
.RE
.PP
\fBReturns\fP
.RS 4
A static string\&. 
.RE
.PP

.SS "__extern int caca_set_dither_algorithm (\fBcaca_dither_t\fP * d, char const * str)"
Tell the renderer which dithering algorithm should be used\&. Dithering is necessary because the picture being rendered has usually far more colours than the available palette\&. Valid values for \fCstr\fP are:
.IP "\(bu" 2
\fC"none"\fP: no dithering is used, the nearest matching colour is used\&.
.IP "\(bu" 2
\fC"ordered2"\fP: use a 2x2 Bayer matrix for dithering\&.
.IP "\(bu" 2
\fC"ordered4"\fP: use a 4x4 Bayer matrix for dithering\&.
.IP "\(bu" 2
\fC"ordered8"\fP: use a 8x8 Bayer matrix for dithering\&.
.IP "\(bu" 2
\fC"random"\fP: use random dithering\&.
.IP "\(bu" 2
\fC"fstein"\fP: use Floyd-Steinberg dithering\&. This is the default value\&.
.PP
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Unknown dithering mode\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fId\fP Dither object\&. 
.br
\fIstr\fP A string describing the algorithm that needs to be used for the dithering\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.SS "__extern char const* const* caca_get_dither_algorithm_list (\fBcaca_dither_t\fP const * d)"
Return a list of available dithering algorithms for a given dither\&. The list is a NULL-terminated array of strings, interleaving a string containing the internal value for the dithering algorithm, to be used with caca_set_dither_dithering(), and a string containing the natural language description for that algorithm\&.
.PP
This function never fails\&.
.PP
\fBParameters\fP
.RS 4
\fId\fP Dither object\&. 
.RE
.PP
\fBReturns\fP
.RS 4
An array of strings\&. 
.RE
.PP

.SS "__extern char const* caca_get_dither_algorithm (\fBcaca_dither_t\fP const * d)"
Return the given dither's current dithering algorithm\&.
.PP
This function never fails\&.
.PP
\fBParameters\fP
.RS 4
\fId\fP Dither object\&. 
.RE
.PP
\fBReturns\fP
.RS 4
A static string\&. 
.RE
.PP

.SS "__extern int caca_dither_bitmap (\fBcaca_canvas_t\fP * cv, int x, int y, int w, int h, \fBcaca_dither_t\fP const * d, void const * pixels)"
Dither a bitmap at the given coordinates\&. The dither can be of any size and will be stretched to the text area\&.
.PP
This function never fails\&.
.PP
\fBParameters\fP
.RS 4
\fIcv\fP A handle to the libcaca canvas\&. 
.br
\fIx\fP X coordinate of the upper-left corner of the drawing area\&. 
.br
\fIy\fP Y coordinate of the upper-left corner of the drawing area\&. 
.br
\fIw\fP Width of the drawing area\&. 
.br
\fIh\fP Height of the drawing area\&. 
.br
\fId\fP Dither object to be drawn\&. 
.br
\fIpixels\fP Bitmap's pixels\&. 
.RE
.PP
\fBReturns\fP
.RS 4
This function always returns 0\&. 
.RE
.PP

.PP
References CACA_BLACK, caca_get_attr(), caca_put_char(), caca_set_attr(), and caca_set_color_ansi()\&.
.SS "__extern int caca_free_dither (\fBcaca_dither_t\fP * d)"
Free the memory allocated by \fBcaca_create_dither()\fP\&.
.PP
This function never fails\&.
.PP
\fBParameters\fP
.RS 4
\fId\fP Dither object\&. 
.RE
.PP
\fBReturns\fP
.RS 4
This function always returns 0\&. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for libcaca from the source code\&.