caca_dither(3caca)

📦
version 0.99.beta20 · 13 versions
, in opensuse-leap 16.0

💅 caca_dither — libcaca bitmap dithering 🎀

okay bestie, this one lives in libcaca (yes, the 3caca manual, part 1 of our little saga 💖) and it's literally the whole dithering situation — creating dither objects, tweaking how they look, and painting bitmaps onto a canvas. no cap, this page is stacked. let's get into it ✨

🌸 NAME 🌸

caca_dither — libcaca bitmap dithering

like, the entire high-level dithering API. this is the moment. 👑

✨ 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 are the high level routines for dither allocation and rendering. allocation, rendering, the whole glow-up. 🫶

🌈 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 — that's depth, width, height and pitch — plus the pixel mask values. iconic little constructor fr fr.

if the depth is 8 bits per pixel, the mask values are literally ignored and you should set the colour palette with the caca_set_dither_palette() function instead. for depths greater than 8 bits per pixel, a zero alpha mask causes the alpha values to be ignored. noted. 📝

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). yes, that's the range, don't come at me. 💅

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. glow up time ✨

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. ever. it's giving reliable main character energy. 👑

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. heads up: a negative value causes colour inversion. lowkey dramatic but okay 👀

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. periodt. 💀

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, bestie. never. 🫶

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. yes, the crunchy pixel stairs. we're fixing those. 🪄

  • "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. so it's like a little menu, internal value then human-readable description, back and forth. 🍓

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. same interleaving situation, just colours this time. 🌈

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.

and that's where part 1 wraps, bestie — more is coming, so don't go anywhere 🧚💖

🌸 caca_get_dither_charset_list()

__extern char const  *const  * caca_get_dither_charset_list (caca_dither_t const * d)

Okay bestie, this one returns the 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 — the one to use with caca_set_dither_charset() — and a string containing the natural language description for that character set. Cute little pair-up, no cap. 🫶

This function never fails. ✨

Parameters

  • d — Dither object.

Returns

  • An array of strings.

🦋 caca_get_dither_charset()

__extern char const  * caca_get_dither_charset (caca_dither_t const * d)

Returns the given dither’s current character set. That’s it, that’s the vibe. 💅

This function never fails. ✨

Parameters

  • d — Dither object.

Returns

  • A static string.

🎀 caca_set_dither_algorithm()

__extern int caca_set_dither_algorithm (caca_dither_t * d, char const * str)

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

🌈 caca_get_dither_algorithm_list()

__extern char const  *const  * caca_get_dither_algorithm_list (caca_dither_t const * d)

Returns 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. Yes, that’s the function name right there in the docs — we keep it exactly as it is, bestie. 🫶

This function never fails. ✨

Parameters

  • d — Dither object.

Returns

  • An array of strings.

👑 caca_get_dither_algorithm()

__extern char const  * caca_get_dither_algorithm (caca_dither_t const * d)

Returns the given dither’s current dithering algorithm. Main character energy for a getter, honestly. 💜

This function never fails. ✨

Parameters

  • d — Dither object.

Returns

  • A static string.

🔥 caca_dither_bitmap()

__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)

Dithers a bitmap at the given coordinates. The dither can be of any size and will be stretched to the text area. Stretch it, slay it, render it. 💅

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().

🧚 caca_free_dither()

__extern int caca_free_dither (caca_dither_t * d)

Frees the memory allocated by caca_create_dither(). Cleanup era, we love to see it. 🎀

This function never fails. ✨

Parameters

  • d — Dither object.

Returns

  • This function always returns 0.

🫶 AUTHOR 🫶

This page was generated automatically by Doxygen for libcaca from the source code. 💖

That’s the whole page, bestie 🦋 — caca_dither(3caca), version 0.99.beta20, dated Wed May 13 2026 09:45:08. Slay and goodbye. ✨💅

📦 where this page comes from