caca_attributes(3caca)

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

💅 NAME 💅

okay so bestie, this is caca_attributes(3caca) from libcaca — and it’s literally all about libcaca attribute conversions. periodt. 💖

✨ SYNOPSIS ✨

🎀 Topics 🎀

  • libcaca character set conversions — that’s the topic this page belongs to, iykyk.

🫶 Functions 🫶

  • __extern uint32_t caca_get_attr (caca_canvas_t const *, int, int) — grabs the text attribute at the given coordinates. ur fave little coordinate detective 🔍
  • __extern int caca_set_attr (caca_canvas_t *, uint32_t) — sets the default character attribute. main character energy for the default vibe ✨
  • __extern int caca_unset_attr (caca_canvas_t *, uint32_t) — unsets flags in the default character attribute. not me removing those flags 🙈
  • __extern int caca_toggle_attr (caca_canvas_t *, uint32_t) — toggles flags in the default character attribute. flip it, switch it, slay it 💅
  • __extern int caca_put_attr (caca_canvas_t *, int, int, uint32_t) — sets the character attribute at the given coordinates. very “put it right there” of it 🎯
  • __extern int caca_set_color_ansi (caca_canvas_t *, uint8_t, uint8_t) — sets the default colour pair for text, the ANSI version. retro-ish but make it cute 🌈
  • __extern int caca_set_color_argb (caca_canvas_t *, uint16_t, uint16_t) — sets the default colour pair for text, the truecolor version. highkey fancy 💎
  • __extern uint8_t caca_attr_to_ansi (uint32_t) — gets DOS ANSI information from an attribute. blast from the past fr fr 👾
  • __extern uint8_t caca_attr_to_ansi_fg (uint32_t) — gets ANSI foreground information from an attribute. front and center 🍓
  • __extern uint8_t caca_attr_to_ansi_bg (uint32_t) — gets ANSI background information from an attribute. back it up, bestie 🦋
  • __extern uint16_t caca_attr_to_rgb12_fg (uint32_t) — gets 12-bit RGB foreground information from an attribute. twelve bits of front-row realness ⭐
  • __extern uint16_t caca_attr_to_rgb12_bg (uint32_t) — gets 12-bit RGB background information from an attribute. twelve bits of behind-the-scenes magic 🌸
  • __extern void caca_attr_to_argb64 (uint32_t, uint8_t[8]) — gets 64-bit ARGB information from an attribute. big ARGB energy, no cap 👑

🌸 Detailed Description 🌸

okay so the whole point: these functions perform conversions between attribute values. that’s the assignment, and they ate. 💖✨

🌈 FUNCTION DOCUMENTATION 🌈

okay bestie, this is the part where we meet every function one by one. grab a snack, there's a bunch 💅

✨ caca_get_attr ✨

__extern uint32_t caca_get_attr (caca_canvas_t const * cv, int x, int y)

Get the internal libcaca attribute value of the character at the given coordinates. The attribute value has 32 significant bits, organised as follows from MSB to LSB:

  • 3 bits for the background alpha
  • 4 bits for the background red component
  • 4 bits for the background green component
  • 3 bits for the background blue component
  • 3 bits for the foreground alpha
  • 4 bits for the foreground red component
  • 4 bits for the foreground green component
  • 3 bits for the foreground blue component
  • 4 bits for the bold, italics, underline and blink flags

If the coordinates are outside the canvas boundaries, the current attribute is returned.

This function never fails. no cap, it literally cannot fail 😌

Parameters

  • cv — A handle to the libcaca canvas.
  • x — X coordinate.
  • y — Y coordinate.

Returns

The requested attribute.

Referenced by caca_conio_textbackground(), caca_conio_textcolor(), caca_dither_bitmap(), caca_flush_figlet(), and caca_put_figchar().

🎀 caca_set_attr 🎀

__extern int caca_set_attr (caca_canvas_t * cv, uint32_t attr)

Set the default character attribute for drawing. Attributes define foreground and background colour, transparency, bold, italics and underline styles, as well as blink. String functions such as caca_printf() and graphical primitive functions such as caca_draw_line() will use this attribute.

The value of attr is either:

  • a 32-bit integer as returned by caca_get_attr(), in which case it also contains colour information,
  • a combination (bitwise OR) of style values (CACA_UNDERLINE, CACA_BLINK, CACA_BOLD and CACA_ITALICS), in which case setting the attribute does not modify the current colour information.

To retrieve the current attribute value, use caca_get_attr(-1,-1). yes, negative coords, it's giving "out of bounds means gimme the current one" energy 💀

This function never fails.

Parameters

  • cv — A handle to the libcaca canvas.
  • attr — The requested attribute value.

Returns

This function always returns 0.

Referenced by caca_dither_bitmap(), and caca_put_figchar().

🦋 caca_unset_attr 🦋

__extern int caca_unset_attr (caca_canvas_t * cv, uint32_t attr)

Unset flags in the default character attribute for drawing. Attributes define foreground and background colour, transparency, bold, italics and underline styles, as well as blink. String functions such as caca_printf() and graphical primitive functions such as caca_draw_line() will use this attribute.

The value of attr is a combination (bitwise OR) of style values (CACA_UNDERLINE, CACA_BLINK, CACA_BOLD and CACA_ITALICS). Unsetting these attributes does not modify the current colour information.

To retrieve the current attribute value, use caca_get_attr(-1,-1).

This function never fails.

Parameters

  • cv — A handle to the libcaca canvas.
  • attr — The requested attribute values to unset.

Returns

This function always returns 0.

🌸 caca_toggle_attr 🌸

__extern int caca_toggle_attr (caca_canvas_t * cv, uint32_t attr)

Toggle flags in the default character attribute for drawing. Attributes define foreground and background colour, transparency, bold, italics and underline styles, as well as blink. String functions such as caca_printf() and graphical primitive functions such as caca_draw_line() will use this attribute.

The value of attr is a combination (bitwise OR) of style values (CACA_UNDERLINE, CACA_BLINK, CACA_BOLD and CACA_ITALICS). Toggling these attributes does not modify the current colour information.

To retrieve the current attribute value, use caca_get_attr(-1,-1).

This function never fails.

Parameters

  • cv — A handle to the libcaca canvas.
  • attr — The requested attribute values to toggle.

Returns

This function always returns 0.

🧚 caca_put_attr 🧚

__extern int caca_put_attr (caca_canvas_t * cv, int x, int y, uint32_t attr)

Set the character attribute, without changing the character's value. If the character at the given coordinates is a fullwidth character, both cells' attributes are replaced. both cells!! the whole wide boi gets the glow-up 😭💖

The value of attr is either:

  • a 32-bit integer as returned by caca_get_attr(), in which case it also contains colour information,
  • a combination (bitwise OR) of style values (CACA_UNDERLINE, CACA_BLINK, CACA_BOLD and CACA_ITALICS), in which case setting the attribute does not modify the current colour information.

This function never fails.

Parameters

  • cv — A handle to the libcaca canvas.
  • x — X coordinate.
  • y — Y coordinate.
  • attr — The requested attribute value.

Returns

This function always returns 0.

References caca_add_dirty_rect(), and CACA_MAGIC_FULLWIDTH.

Referenced by caca_flush_figlet(), and caca_put_figchar().

💜 caca_set_color_ansi 💜

__extern int caca_set_color_ansi (caca_canvas_t * cv, uint8_t fg, uint8_t bg)

Set the default ANSI colour pair for text drawing. String functions such as caca_printf() and graphical primitive functions such as caca_draw_line() will use these attributes.

Color values are those defined in caca.h, such as CACA_RED or CACA_TRANSPARENT.

If an error occurs, -1 is returned and errno is set accordingly:

  • EINVAL — At least one of the colour values is invalid.
heads up bestie: this one can fail — unlike its glowier siblings above. bad colour value = -1 and errno gets a note 🫶

Parameters

  • cv — A handle to the libcaca canvas.
  • fg — The requested ANSI foreground colour.
  • bg — The requested ANSI background colour.

Returns

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

Referenced by caca_conio_textbackground(), caca_conio_textcolor(), caca_create_canvas(), and caca_dither_bitmap().

🍓 caca_set_color_argb 🍓

__extern int caca_set_color_argb (caca_canvas_t * cv, uint16_t fg, uint16_t bg)

Set the default ARGB colour pair for text drawing. String functions such as caca_printf() and graphical primitive functions such as caca_draw_line() will use these attributes.

Colors are 16-bit ARGB values, each component being coded on 4 bits. For instance, 0xf088 is solid dark cyan (A=15 R=0 G=8 B=8), and 0x8fff is white with 50% alpha (A=8 R=15 G=15 B=15). little hex math moment, ate fr 🔥

This function never fails.

Parameters

  • cv — A handle to the libcaca canvas.
  • fg — The requested ARGB foreground colour.
  • bg — The requested ARGB background colour.

Returns

This function always returns 0.

⭐ caca_attr_to_ansi ⭐

__extern uint8_t caca_attr_to_ansi (uint32_t attr)

Get the ANSI colour pair for a given attribute. The returned value is an 8-bit value whose higher 4 bits are the background colour and lower 4 bits are the foreground colour.

If the attribute has ARGB colours, the nearest colour is used. Special attributes such as CACA_DEFAULT and CACA_TRANSPARENT are not handled and are both replaced with CACA_LIGHTGRAY for the foreground colour and CACA_BLACK for the background colour. ngl that's them getting flattened to grey-on-black, iconic but rude 💀

This function never fails. If the attribute value is outside the expected 32-bit range, higher order bits are simply ignored.

Parameters

  • attr — The requested attribute value.

Returns

The corresponding DOS ANSI value.

References CACA_BLACK, and CACA_LIGHTGRAY.

💖 caca_attr_to_ansi_fg 💖

__extern uint8_t caca_attr_to_ansi_fg (uint32_t attr)

Get the ANSI foreground colour value for a given attribute. The returned value is either one of the CACA_RED, CACA_BLACK etc. predefined colours, or the special value CACA_DEFAULT meaning the media's default foreground value, or the special value CACA_TRANSPARENT.

If the attribute has ARGB colours, the nearest colour is returned.

This function never fails. If the attribute value is outside the expected 32-bit range, higher order bits are simply ignored.

Parameters

  • attr — The requested attribute value.

Returns

The corresponding ANSI foreground value.

Referenced by caca_conio_textbackground().

🎀 caca_attr_to_ansi_bg 🎀

__extern uint8_t caca_attr_to_ansi_bg (uint32_t attr)

Get the ANSI background colour value for a given attribute. The returned value is either one of the CACA_RED, CACA_BLACK etc. predefined colours, or the special value CACA_DEFAULT meaning the media's default background value, or the special value CACA_TRANSPARENT.

If the attribute has ARGB colours, the nearest colour is returned.

This function never fails. If the attribute value is outside the expected 32-bit range, higher order bits are simply ignored.

Parameters

  • attr — The requested attribute value.

Returns

The corresponding ANSI background value.

Referenced by caca_conio_textcolor().

🫶 caca_attr_to_rgb12_fg 🫶

__extern uint16_t caca_attr_to_rgb12_fg (uint32_t attr)

Get the 12-bit foreground colour value for a given attribute. The returned value is a native-endian encoded integer with each red, green and blue values encoded on 8 bits in the following order:

  • 8-11 most significant bits: red
  • 4-7 most significant bits: green
  • least significant bits: blue

This function never fails. If the attribute value is outside the expected 32-bit range, higher order bits are simply ignored.

Parameters

  • attr — The requested attribute value.

Returns

The corresponding 12-bit RGB foreground value.

References CACA_DEFAULT, CACA_LIGHTGRAY, and CACA_TRANSPARENT.

🫶 caca_attr_to_rgb12_bg 🫶

__extern uint16_t caca_attr_to_rgb12_bg (uint32_t attr)

Get the 12-bit background colour value for a given attribute. The returned value is a native-endian encoded integer with each red, green and blue values encoded on 8 bits in the following order:

  • 8-11 most significant bits: red
  • 4-7 most significant bits: green
  • least significant bits: blue

This function never fails. If the attribute value is outside the expected 32-bit range, higher order bits are simply ignored.

Parameters

  • attr — The requested attribute value.

Returns

The corresponding 12-bit RGB background value.

References CACA_BLACK, CACA_DEFAULT, and CACA_TRANSPARENT.

👑 caca_attr_to_argb64 👑

__extern void caca_attr_to_argb64 (uint32_t attr, uint8_t argb[8])

Get the 64-bit colour and alpha values for a given attribute. The values are written as 8-bit integers in the argb array in the following order:

  • argb[0]: background alpha value
  • argb[1]: background red value
  • argb[2]: background green value
  • argb[3]: background blue value
  • argb[4]: foreground alpha value
  • argb[5]: foreground red value
  • argb[6]: foreground green value
  • argb[7]: foreground blue value

This function never fails. If the attribute value is outside the expected 32-bit range, higher order bits are simply ignored.

Parameters

  • attr — The requested attribute value.
  • argb — An array of 8-bit integers.

References CACA_BLACK, CACA_DEFAULT, CACA_LIGHTGRAY, and CACA_TRANSPARENT.

Referenced by caca_render_canvas().

📜 AUTHOR 📜

Generated automatically by Doxygen for libcaca from the source code. so not a human author, it's the robot doing the paperwork, slay 🤖✨

and that's a wrap on caca_attributes(3caca), bestie! 💅 this lil doc set is from libcaca version 0.99.beta20, stamped Wed May 13 2026 09:45:08 — go forth and colour things in, mwah 🎀💖

📦 where this page comes from