libcaca documentation

# libcucul bitmap dithering

## Functions
cucul_dither_t * | cucul_create_dither (unsigned int, unsigned int, unsigned int, unsigned int, unsigned long int, unsigned long int, unsigned long int, unsigned long int)
| Create an internal dither object.
int | cucul_set_dither_palette (cucul_dither_t *, unsigned int r[], unsigned int g[], unsigned int b[], unsigned int a[])
| Set the palette of an 8bpp dither object.
int | cucul_set_dither_brightness (cucul_dither_t *, float)
| Set the brightness of a dither object.
int | cucul_set_dither_gamma (cucul_dither_t *, float)
| Set the gamma of a dither object.
int | cucul_set_dither_contrast (cucul_dither_t *, float)
| Set the contrast of a dither object.
int | cucul_set_dither_invert (cucul_dither_t *, int)
| Invert colors of dither.
int | cucul_set_dither_antialias (cucul_dither_t *, char const *)
| Set dither antialiasing.
char const *const * | cucul_get_dither_antialias_list (cucul_dither_t const *)
| Get available antialiasing methods.
int | cucul_set_dither_color (cucul_dither_t *, char const *)
| Choose colours used for dithering.
char const *const * | cucul_get_dither_color_list (cucul_dither_t const *)
| Get available colour modes.
int | cucul_set_dither_charset (cucul_dither_t *, char const *)
| Choose characters used for dithering.
char const *const * | cucul_get_dither_charset_list (cucul_dither_t const *)
| Get available dither character sets.
int | cucul_set_dither_mode (cucul_dither_t *, char const *)
| Set dithering method.
char const *const * | cucul_get_dither_mode_list (cucul_dither_t const *)
| Get dithering methods.
int | cucul_dither_bitmap (cucul_canvas_t *, int, int, int, int, cucul_dither_t const *, void *)
| Dither a bitmap on the canvas.
int | cucul_free_dither (cucul_dither_t *)
| Free the memory associated with a dither.

## Detailed Description

These functions provide high level routines for dither allocation and rendering.

## Function Documentation

cucul_dither_t* cucul_create_dither | ( | unsigned int | bpp,
|  | unsigned int | w,
|  | unsigned int | h,
|  | unsigned int | pitch,
|  | unsigned long int | rmask,
|  | unsigned long int | gmask,
|  | unsigned long int | bmask,
|  | unsigned long int | 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 cucul_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.

int cucul_set_dither_palette | ( | cucul_dither_t * | d,
|  | unsigned int | red[],
|  | unsigned int | green[],
|  | unsigned int | blue[],
|  | unsigned int | 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.

int cucul_set_dither_brightness | ( | cucul_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.

int cucul_set_dither_gamma | ( | cucul_dither_t * | d,
|  | float | gamma |
| ) |  |  |

Set the gamma of dither.

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.

int cucul_set_dither_contrast | ( | cucul_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.

int cucul_set_dither_invert | ( | cucul_dither_t * | d,
|  | int | value |
| ) |  |  |

Invert colors of dither.

This function never fails.

Parameters:

  | d | Dither object.
  | value | 0 for normal behaviour, 1 for invert

Returns:
  This function always returns 0.

int cucul_set_dither_antialias | ( | cucul_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.

char const* const* cucul_get_dither_antialias_list | ( | cucul_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 cucul_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.

int cucul_set_dither_color | ( | cucul_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.

char const* const* cucul_get_dither_color_list | ( | cucul_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 cucul_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.

int cucul_set_dither_charset | ( | cucul_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.

char const* const* cucul_get_dither_charset_list | ( | cucul_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 cucul_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.

int cucul_set_dither_mode | ( | cucul_dither_t * | d,
|  | char const * | str |
| ) |  |  |

Tell the renderer which dithering method 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 method that needs to be used for the dithering.

Returns:
  0 in case of success, -1 if an error occurred.

char const* const* cucul_get_dither_mode_list | ( | cucul_dither_t const * | d | ) |

Return a list of available dithering methods for a given dither. The list is a NULL-terminated array of strings, interleaving a string containing the internal value for the dithering method, to be used with cucul_set_dither_dithering(), and a string containing the natural language description for that dithering method.

This function never fails.

Parameters:

  | d | Dither object.

Returns:
  An array of strings.

int cucul_dither_bitmap | ( | cucul_canvas_t * | cv,
|  | int | x,
|  | int | y,
|  | int | w,
|  | int | h,
|  | cucul_dither_t const * | d,
|  | void * | 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 libcucul 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.

int cucul_free_dither | ( | cucul_dither_t * | d | ) |

Free the memory allocated by cucul_create_dither().

This function never fails.

Parameters:

  | d | Dither object.

Returns:
  This function always returns 0.