.TH "libcaca bitmap dithering" 3caca "Fri Apr 6 2012" "Version 0.99.beta18" "libcaca" \" -*- nroff -*-
.ad l
.nh
.SH NAME
libcaca bitmap dithering \- 
.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 "\fICreate an internal dither object\&. \fP"
.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 "\fISet the palette of an 8bpp dither object\&. \fP"
.ti -1c
.RI "__extern int \fBcaca_set_dither_brightness\fP (\fBcaca_dither_t\fP *, float)"
.br
.RI "\fISet the brightness of a dither object\&. \fP"
.ti -1c
.RI "__extern float \fBcaca_get_dither_brightness\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "\fIGet the brightness of a dither object\&. \fP"
.ti -1c
.RI "__extern int \fBcaca_set_dither_gamma\fP (\fBcaca_dither_t\fP *, float)"
.br
.RI "\fISet the gamma of a dither object\&. \fP"
.ti -1c
.RI "__extern float \fBcaca_get_dither_gamma\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "\fIGet the gamma of a dither object\&. \fP"
.ti -1c
.RI "__extern int \fBcaca_set_dither_contrast\fP (\fBcaca_dither_t\fP *, float)"
.br
.RI "\fISet the contrast of a dither object\&. \fP"
.ti -1c
.RI "__extern float \fBcaca_get_dither_contrast\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "\fIGet the contrast of a dither object\&. \fP"
.ti -1c
.RI "__extern int \fBcaca_set_dither_antialias\fP (\fBcaca_dither_t\fP *, char const *)"
.br
.RI "\fISet dither antialiasing\&. \fP"
.ti -1c
.RI "__extern char const *const * \fBcaca_get_dither_antialias_list\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "\fIGet available antialiasing methods\&. \fP"
.ti -1c
.RI "__extern char const * \fBcaca_get_dither_antialias\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "\fIGet current antialiasing method\&. \fP"
.ti -1c
.RI "__extern int \fBcaca_set_dither_color\fP (\fBcaca_dither_t\fP *, char const *)"
.br
.RI "\fIChoose colours used for dithering\&. \fP"
.ti -1c
.RI "__extern char const *const * \fBcaca_get_dither_color_list\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "\fIGet available colour modes\&. \fP"
.ti -1c
.RI "__extern char const * \fBcaca_get_dither_color\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "\fIGet current colour mode\&. \fP"
.ti -1c
.RI "__extern int \fBcaca_set_dither_charset\fP (\fBcaca_dither_t\fP *, char const *)"
.br
.RI "\fIChoose characters used for dithering\&. \fP"
.ti -1c
.RI "__extern char const *const * \fBcaca_get_dither_charset_list\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "\fIGet available dither character sets\&. \fP"
.ti -1c
.RI "__extern char const * \fBcaca_get_dither_charset\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "\fIGet current character set\&. \fP"
.ti -1c
.RI "__extern int \fBcaca_set_dither_algorithm\fP (\fBcaca_dither_t\fP *, char const *)"
.br
.RI "\fISet dithering algorithm\&. \fP"
.ti -1c
.RI "__extern char const *const * \fBcaca_get_dither_algorithm_list\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "\fIGet dithering algorithms\&. \fP"
.ti -1c
.RI "__extern char const * \fBcaca_get_dither_algorithm\fP (\fBcaca_dither_t\fP const *)"
.br
.RI "\fIGet current dithering algorithm\&. \fP"
.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 "\fIDither a bitmap on the canvas\&. \fP"
.ti -1c
.RI "__extern int \fBcaca_free_dither\fP (\fBcaca_dither_t\fP *)"
.br
.RI "\fIFree the memory associated with a dither\&. \fP"
.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* \fBcaca_create_dither\fP (intbpp, intw, inth, intpitch, uint32_trmask, uint32_tgmask, uint32_tbmask, uint32_tamask)"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 \fBcaca_set_dither_palette\fP (\fBcaca_dither_t\fP *d, uint32_tred[], uint32_tgreen[], uint32_tblue[], uint32_talpha[])"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 \fBcaca_set_dither_brightness\fP (\fBcaca_dither_t\fP *d, floatbrightness)"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 \fBcaca_get_dither_brightness\fP (\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 \fBcaca_set_dither_gamma\fP (\fBcaca_dither_t\fP *d, floatgamma)"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 \fBcaca_get_dither_gamma\fP (\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 \fBcaca_set_dither_contrast\fP (\fBcaca_dither_t\fP *d, floatcontrast)"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 \fBcaca_get_dither_contrast\fP (\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 \fBcaca_set_dither_antialias\fP (\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* \fBcaca_get_dither_antialias_list\fP (\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* \fBcaca_get_dither_antialias\fP (\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 \fBcaca_set_dither_color\fP (\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* \fBcaca_get_dither_color_list\fP (\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* \fBcaca_get_dither_color\fP (\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 \fBcaca_set_dither_charset\fP (\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* \fBcaca_get_dither_charset_list\fP (\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* \fBcaca_get_dither_charset\fP (\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 \fBcaca_set_dither_algorithm\fP (\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* \fBcaca_get_dither_algorithm_list\fP (\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* \fBcaca_get_dither_algorithm\fP (\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 \fBcaca_dither_bitmap\fP (\fBcaca_canvas_t\fP *cv, intx, inty, intw, inth, \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 \fBcaca_free_dither\fP (\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\&.