libcaca documentation

Functions
libcaca bitmap dithering

## 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.