--- name: "caca_dither" section: "3caca" platform: "linux" package: "libcaca" version: "0.99.beta20-7" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/caca_dither" --- # caca\_dither(3caca) libcaca bitmap dithering ## NAME caca\_dither - libcaca bitmap dithering ## SYNOPSIS ### Topics **libcaca character font handling**\ ### Functions \_\_extern **caca\_dither\_t** \* **caca\_create\_dither** (int, int, int, int, uint32\_t, uint32\_t, uint32\_t, uint32\_t)\ Create an internal dither object. \_\_extern int **caca\_set\_dither\_palette** (**caca\_dither\_t** \*, uint32\_t r\[\], uint32\_t g\[\], uint32\_t b\[\], uint32\_t a\[\])\ Set the palette of an 8bpp dither object. \_\_extern int **caca\_set\_dither\_brightness** (**caca\_dither\_t** \*, float)\ Set the brightness of a dither object. \_\_extern float **caca\_get\_dither\_brightness** (**caca\_dither\_t** const \*)\ Get the brightness of a dither object. \_\_extern int **caca\_set\_dither\_gamma** (**caca\_dither\_t** \*, float)\ Set the gamma of a dither object. \_\_extern float **caca\_get\_dither\_gamma** (**caca\_dither\_t** const \*)\ Get the gamma of a dither object. \_\_extern int **caca\_set\_dither\_contrast** (**caca\_dither\_t** \*, float)\ Set the contrast of a dither object. \_\_extern float **caca\_get\_dither\_contrast** (**caca\_dither\_t** const \*)\ Get the contrast of a dither object. \_\_extern int **caca\_set\_dither\_antialias** (**caca\_dither\_t** \*, char const \*)\ Set dither antialiasing. \_\_extern char const \*const \* **caca\_get\_dither\_antialias\_list** (**caca\_dither\_t** const \*)\ Get available antialiasing methods. \_\_extern char const \* **caca\_get\_dither\_antialias** (**caca\_dither\_t** const \*)\ Get current antialiasing method. \_\_extern int **caca\_set\_dither\_color** (**caca\_dither\_t** \*, char const \*)\ Choose colours used for dithering. \_\_extern char const \*const \* **caca\_get\_dither\_color\_list** (**caca\_dither\_t** const \*)\ Get available colour modes. \_\_extern char const \* **caca\_get\_dither\_color** (**caca\_dither\_t** const \*)\ Get current colour mode. \_\_extern int **caca\_set\_dither\_charset** (**caca\_dither\_t** \*, char const \*)\ Choose characters used for dithering. \_\_extern char const \*const \* **caca\_get\_dither\_charset\_list** (**caca\_dither\_t** const \*)\ Get available dither character sets. \_\_extern char const \* **caca\_get\_dither\_charset** (**caca\_dither\_t** const \*)\ Get current character set. \_\_extern int **caca\_set\_dither\_algorithm** (**caca\_dither\_t** \*, char const \*)\ Set dithering algorithm. \_\_extern char const \*const \* **caca\_get\_dither\_algorithm\_list** (**caca\_dither\_t** const \*)\ Get dithering algorithms. \_\_extern char const \* **caca\_get\_dither\_algorithm** (**caca\_dither\_t** const \*)\ Get current dithering algorithm. \_\_extern int **caca\_dither\_bitmap** (**caca\_canvas\_t** \*, int, int, int, int, **caca\_dither\_t** const \*, void const \*)\ Dither a bitmap on the canvas. \_\_extern int **caca\_free\_dither** (**caca\_dither\_t** \*)\ Free the memory associated with a dither. ## Detailed Description These functions provide high level routines for dither allocation and rendering. ## Function Documentation ### \_\_extern caca\_dither\_t \* 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 **caca\_set\_dither\_palette()** function. For depths greater than 8 bits per pixel, a zero alpha mask causes the alpha values to be ignored. If an error occurs, NULL is returned and **errno** is set accordingly: - • EINVAL Requested width, height, pitch or bits per pixel value was invalid. - • ENOMEM Not enough memory to allocate dither structure. **Parameters** *bpp* Bitmap depth in bits per pixel. \ *w* Bitmap width in pixels. \ *h* Bitmap height in pixels. \ *pitch* Bitmap pitch in bytes. \ *rmask* Bitmask for red values. \ *gmask* Bitmask for green values. \ *bmask* Bitmask for blue values. \ *amask* Bitmask for alpha values. **Returns** Dither object upon success, NULL if an error occurred. ### \_\_extern int caca\_set\_dither\_palette (caca\_dither\_t \* 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). If an error occurs, -1 is returned and **errno** is set accordingly: - • EINVAL Dither bits per pixel value is not 8, or one of the pixel values was outside the range 0 - 4095. **Parameters** *d* Dither object. \ *red* Array of 256 red values. \ *green* Array of 256 green values. \ *blue* Array of 256 blue values. \ *alpha* Array of 256 alpha values. **Returns** 0 in case of success, -1 if an error occurred. ### \_\_extern int caca\_set\_dither\_brightness (caca\_dither\_t \* d, float brightness) Set the brightness of dither. If an error occurs, -1 is returned and **errno** is set accordingly: - • EINVAL Brightness value was out of range. **Parameters** *d* Dither object. \ *brightness* brightness value. **Returns** 0 in case of success, -1 if an error occurred. ### \_\_extern float caca\_get\_dither\_brightness (caca\_dither\_t const \* d) Get the brightness of the given dither object. This function never fails. **Parameters** *d* Dither object. **Returns** Brightness value. ### \_\_extern int caca\_set\_dither\_gamma (caca\_dither\_t \* d, float gamma) Set the gamma of the given dither object. A negative value causes colour inversion. If an error occurs, -1 is returned and **errno** is set accordingly: - • EINVAL Gamma value was out of range. **Parameters** *d* Dither object. \ *gamma* Gamma value. **Returns** 0 in case of success, -1 if an error occurred. ### \_\_extern float caca\_get\_dither\_gamma (caca\_dither\_t const \* d) Get the gamma of the given dither object. This function never fails. **Parameters** *d* Dither object. **Returns** Gamma value. ### \_\_extern int caca\_set\_dither\_contrast (caca\_dither\_t \* d, float contrast) Set the contrast of dither. If an error occurs, -1 is returned and **errno** is set accordingly: - • EINVAL Contrast value was out of range. **Parameters** *d* Dither object. \ *contrast* contrast value. **Returns** 0 in case of success, -1 if an error occurred. ### \_\_extern float caca\_get\_dither\_contrast (caca\_dither\_t const \* d) Get the contrast of the given dither object. This function never fails. **Parameters** *d* Dither object. **Returns** Contrast value. ### \_\_extern int caca\_set\_dither\_antialias (caca\_dither\_t \* d, char const \* str) Tell the renderer whether to antialias the dither. Antialiasing smoothens the rendered image and avoids the commonly seen staircase effect. - • "none": no antialiasing. - • "prefilter" or "default": simple prefilter antialiasing. This is the default value. If an error occurs, -1 is returned and **errno** is set accordingly: - • EINVAL Invalid antialiasing mode. **Parameters** *d* Dither object. \ *str* A string describing the antialiasing method that will be used for the dithering. **Returns** 0 in case of success, -1 if an error occurred. ### \_\_extern char const \*const \* caca\_get\_dither\_antialias\_list (caca\_dither\_t 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 **caca\_set\_dither\_antialias()**, and a string containing the natural language description for that antialiasing method. This function never fails. **Parameters** *d* Dither object. **Returns** An array of strings. ### \_\_extern char const \* caca\_get\_dither\_antialias (caca\_dither\_t const \* d) Return the given dither's current antialiasing method. This function never fails. **Parameters** *d* Dither object. **Returns** A static string. ### \_\_extern int caca\_set\_dither\_color (caca\_dither\_t \* d, char const \* str) Tell the renderer which colours should be used to render the bitmap. Valid values for str are: - • "mono": use light gray on a black background. - • "gray": use white and two shades of gray on a black background. - • "8": use the 8 ANSI colours on a black background. - • "16": use the 16 ANSI colours on a black background. - • "fullgray": use black, white and two shades of gray for both the characters and the background. - • "full8": use the 8 ANSI colours for both the characters and the background. - • "full16" or "default": use the 16 ANSI colours for both the characters and the background. This is the default value. If an error occurs, -1 is returned and **errno** is set accordingly: - • EINVAL Invalid colour set. **Parameters** *d* Dither object. \ *str* A string describing the colour set that will be used for the dithering. **Returns** 0 in case of success, -1 if an error occurred. ### \_\_extern char const \*const \* caca\_get\_dither\_color\_list (caca\_dither\_t 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 **caca\_set\_dither\_color()**, and a string containing the natural language description for that colour mode. This function never fails. **Parameters** *d* Dither object. **Returns** An array of strings. ### \_\_extern char const \* caca\_get\_dither\_color (caca\_dither\_t const \* d) Return the given dither's current colour mode. This function never fails. **Parameters** *d* Dither object. **Returns** A static string. ### \_\_extern int caca\_set\_dither\_charset (caca\_dither\_t \* d, char const \* str) Tell the renderer which characters should be used to render the dither. Valid values for str are: - • "ascii" or "default": use only ASCII characters. This is the default value. - • "shades": 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. - • "blocks": use Unicode quarter-cell block combinations. These characters are only found in the Unicode set. If an error occurs, -1 is returned and **errno** is set accordingly: - • EINVAL Invalid character set. **Parameters** *d* Dither object. \ *str* A string describing the characters that need to be used for the dithering. **Returns** 0 in case of success, -1 if an error occurred. ### \_\_extern char const \*const \* caca\_get\_dither\_charset\_list (caca\_dither\_t 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 **caca\_set\_dither\_charset()**, and a string containing the natural language description for that character set. This function never fails. **Parameters** *d* Dither object. **Returns** An array of strings. ### \_\_extern char const \* caca\_get\_dither\_charset (caca\_dither\_t const \* d) Return the given dither's current character set. This function never fails. **Parameters** *d* Dither object. **Returns** A static string. ### \_\_extern int caca\_set\_dither\_algorithm (caca\_dither\_t \* 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 str are: - • "none": no dithering is used, the nearest matching colour is used. - • "ordered2": use a 2x2 Bayer matrix for dithering. - • "ordered4": use a 4x4 Bayer matrix for dithering. - • "ordered8": use a 8x8 Bayer matrix for dithering. - • "random": use random dithering. - • "fstein": use Floyd-Steinberg dithering. This is the default value. If an error occurs, -1 is returned and **errno** is set accordingly: - • EINVAL Unknown dithering mode. **Parameters** *d* Dither object. \ *str* A string describing the algorithm that needs to be used for the dithering. **Returns** 0 in case of success, -1 if an error occurred. ### \_\_extern char const \*const \* caca\_get\_dither\_algorithm\_list (caca\_dither\_t 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. This function never fails. **Parameters** *d* Dither object. **Returns** An array of strings. ### \_\_extern char const \* caca\_get\_dither\_algorithm (caca\_dither\_t const \* d) Return the given dither's current dithering algorithm. This function never fails. **Parameters** *d* Dither object. **Returns** A static string. ### \_\_extern int caca\_dither\_bitmap (caca\_canvas\_t \* cv, int x, int y, int w, int h, caca\_dither\_t 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. This function never fails. **Parameters** *cv* A handle to the libcaca canvas. \ *x* X coordinate of the upper-left corner of the drawing area. \ *y* Y coordinate of the upper-left corner of the drawing area. \ *w* Width of the drawing area. \ *h* Height of the drawing area. \ *d* Dither object to be drawn. \ *pixels* Bitmap's pixels. **Returns** This function always returns 0. References **CACA\_BLACK**, **caca\_get\_attr()**, **caca\_put\_char()**, **caca\_set\_attr()**, and **caca\_set\_color\_ansi()**. ### \_\_extern int caca\_free\_dither (caca\_dither\_t \* d) Free the memory allocated by **caca\_create\_dither()**. This function never fails. **Parameters** *d* Dither object. **Returns** This function always returns 0. ## Author Generated automatically by Doxygen for libcaca from the source code.