--- name: "caca_attributes" 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_attributes" --- # caca\_attributes(3caca) libcaca attribute conversions ## NAME caca\_attributes - libcaca attribute conversions ## SYNOPSIS ### Topics **libcaca character set conversions**\ ### Functions \_\_extern uint32\_t **caca\_get\_attr** (**caca\_canvas\_t** const \*, int, int)\ Get the text attribute at the given coordinates. \_\_extern int **caca\_set\_attr** (**caca\_canvas\_t** \*, uint32\_t)\ Set the default character attribute. \_\_extern int **caca\_unset\_attr** (**caca\_canvas\_t** \*, uint32\_t)\ Unset flags in the default character attribute. \_\_extern int **caca\_toggle\_attr** (**caca\_canvas\_t** \*, uint32\_t)\ Toggle flags in the default character attribute. \_\_extern int **caca\_put\_attr** (**caca\_canvas\_t** \*, int, int, uint32\_t)\ Set the character attribute at the given coordinates. \_\_extern int **caca\_set\_color\_ansi** (**caca\_canvas\_t** \*, uint8\_t, uint8\_t)\ Set the default colour pair for text (ANSI version). \_\_extern int **caca\_set\_color\_argb** (**caca\_canvas\_t** \*, uint16\_t, uint16\_t)\ Set the default colour pair for text (truecolor version). \_\_extern uint8\_t **caca\_attr\_to\_ansi** (uint32\_t)\ Get DOS ANSI information from attribute. \_\_extern uint8\_t **caca\_attr\_to\_ansi\_fg** (uint32\_t)\ Get ANSI foreground information from attribute. \_\_extern uint8\_t **caca\_attr\_to\_ansi\_bg** (uint32\_t)\ Get ANSI background information from attribute. \_\_extern uint16\_t **caca\_attr\_to\_rgb12\_fg** (uint32\_t)\ Get 12-bit RGB foreground information from attribute. \_\_extern uint16\_t **caca\_attr\_to\_rgb12\_bg** (uint32\_t)\ Get 12-bit RGB background information from attribute. \_\_extern void **caca\_attr\_to\_argb64** (uint32\_t, uint8\_t\[8\])\ Get 64-bit ARGB information from attribute. ## Detailed Description These functions perform conversions between attribute values. ## Function Documentation ### \_\_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. **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()**. ### \_\_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). 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()**. ### \_\_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. ### \_\_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. ### \_\_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. 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()**. ### \_\_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. **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()**. ### \_\_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). 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. ### \_\_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. 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**. ### \_\_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()**. ### \_\_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()**. ### \_\_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**. ### \_\_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**. ### \_\_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.