--- name: "libcaca" section: "3caca" platform: "linux" package: "libcaca" version: "0.99.beta20-7" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/libcaca" --- # libcaca(3caca) libcaca basic functions ## NAME libcaca - libcaca basic functions ## SYNOPSIS ### Topics **libcaca canvas drawing**\ ### Functions \_\_extern **caca\_canvas\_t** \* **caca\_create\_canvas** (int, int)\ Initialise a *libcaca* canvas. \_\_extern int **caca\_manage\_canvas** (**caca\_canvas\_t** \*, int(\*)(void \*), void \*)\ Manage a canvas. \_\_extern int **caca\_unmanage\_canvas** (**caca\_canvas\_t** \*, int(\*)(void \*), void \*)\ unmanage a canvas. \_\_extern int **caca\_set\_canvas\_size** (**caca\_canvas\_t** \*, int, int)\ Resize a canvas. \_\_extern int **caca\_get\_canvas\_width** (**caca\_canvas\_t** const \*)\ Get the canvas width. \_\_extern int **caca\_get\_canvas\_height** (**caca\_canvas\_t** const \*)\ Get the canvas height. \_\_extern uint32\_t const \* **caca\_get\_canvas\_chars** (**caca\_canvas\_t** const \*)\ Get the canvas character array. \_\_extern uint32\_t const \* **caca\_get\_canvas\_attrs** (**caca\_canvas\_t** const \*)\ Get the canvas attribute array. \_\_extern int **caca\_free\_canvas** (**caca\_canvas\_t** \*)\ Free a *libcaca* canvas. \_\_extern int **caca\_rand** (int, int)\ \_\_extern char const \* **caca\_get\_version** (void)\ Return the *libcaca* version. ## Detailed Description These functions provide the basic *libcaca* routines for library initialisation, system information retrieval and configuration. ## Function Documentation ### \_\_extern caca\_canvas\_t \* caca\_create\_canvas (int width, int height) Initialise internal *libcaca* structures and the backend that will be used for subsequent graphical operations. It must be the first *libcaca* function to be called in a function. **caca\_free\_canvas()** should be called at the end of the program to free all allocated resources. Both the cursor and the canvas' handle are initialised at the top-left corner. If an error occurs, NULL is returned and **errno** is set accordingly: - • EINVAL Specified width or height is invalid. - • EOVERFLOW Specified width and height overflowed. - • ENOMEM Not enough memory for the requested canvas size. **Parameters** *width* The desired canvas width \ *height* The desired canvas height **Returns** A libcaca canvas handle upon success, NULL if an error occurred. References **CACA\_DEFAULT**, **caca\_set\_color\_ansi()**, and **CACA\_TRANSPARENT**. Referenced by **caca\_conio\_movetext()**, **caca\_create\_display\_with\_driver()**, **caca\_export\_area\_to\_memory()**, **caca\_import\_area\_from\_file()**, **caca\_import\_area\_from\_memory()**, and **caca\_set\_canvas\_boundaries()**. ### \_\_extern int caca\_manage\_canvas (caca\_canvas\_t \* cv, int(\* callback )(void \*), void \* p) Lock a canvas to prevent it from being resized. If non-NULL, the *callback* function pointer will be called upon each *caca\_set\_canvas\_size* call and if the returned value is zero, the canvas resize request will be denied. This function is only useful for display drivers such as the *libcaca* library. If an error occurs, -1 is returned and **errno** is set accordingly: - • EBUSY The canvas is already being managed. **Parameters** *cv* A libcaca canvas. \ *callback* An optional callback function pointer. \ *p* The argument to be passed to *callback*. **Returns** 0 in case of success, -1 if an error occurred. Referenced by **caca\_create\_display\_with\_driver()**. ### \_\_extern int caca\_unmanage\_canvas (caca\_canvas\_t \* cv, int(\* callback )(void \*), void \* p) unlock a canvas previously locked by **caca\_manage\_canvas()**. for safety reasons, the callback and callback data arguments must be the same as for the **caca\_manage\_canvas()** call. this function is only useful for display drivers such as the *libcaca* library. if an error occurs, -1 is returned and **errno** is set accordingly: - • einval the canvas is not managed, or the callback arguments do not match. **Parameters** *cv* a libcaca canvas. \ *callback* the *callback* argument previously passed to **caca\_manage\_canvas()**. \ *p* the *p* argument previously passed to **caca\_manage\_canvas()**. **Returns** 0 in case of success, -1 if an error occurred. Referenced by **caca\_create\_display\_with\_driver()**, and **caca\_free\_display()**. ### \_\_extern int caca\_set\_canvas\_size (caca\_canvas\_t \* cv, int width, int height) Set the canvas' width and height, in character cells. The contents of the canvas are preserved to the extent of the new canvas size. Newly allocated character cells at the right and/or at the bottom of the canvas are filled with spaces. If as a result of the resize the cursor coordinates fall outside the new canvas boundaries, they are readjusted. For instance, if the current X cursor coordinate is 11 and the requested width is 10, the new X cursor coordinate will be 10. It is an error to try to resize the canvas if an output driver has been attached to the canvas using **caca\_create\_display()**. You need to remove the output driver using **caca\_free\_display()** before you can change the canvas size again. However, the caca output driver can cause a canvas resize through user interaction. See the **caca\_event()** documentation for more about this. If an error occurs, -1 is returned and **errno** is set accordingly: - • EINVAL Specified width or height is invalid. - • EOVERFLOW Specified width and height overflowed. - • EBUSY The canvas is in use by a display driver and cannot be resized. - • ENOMEM Not enough memory for the requested canvas size. If this happens, the canvas handle becomes invalid and should not be used. **Parameters** *cv* A libcaca canvas. \ *width* The desired canvas width. \ *height* The desired canvas height. **Returns** 0 in case of success, -1 if an error occurred. Referenced by **caca\_canvas\_set\_figfont()**, **caca\_flush\_figlet()**, and **caca\_put\_figchar()**. ### \_\_extern int caca\_get\_canvas\_width (caca\_canvas\_t const \* cv) Return the current canvas' width, in character cells. This function never fails. **Parameters** *cv* A libcaca canvas. **Returns** The canvas width. Referenced by **caca\_conio\_clreol()**, **caca\_conio\_movetext()**, and **caca\_get\_mouse\_x()**. ### \_\_extern int caca\_get\_canvas\_height (caca\_canvas\_t const \* cv) Returns the current canvas' height, in character cells. This function never fails. **Parameters** *cv* A libcaca canvas. **Returns** The canvas height. Referenced by **caca\_flush\_figlet()**, and **caca\_get\_mouse\_y()**. ### \_\_extern uint32\_t const \* caca\_get\_canvas\_chars (caca\_canvas\_t const \* cv) Return the current canvas' internal character array. The array elements consist in native endian 32-bit Unicode values as returned by **caca\_get\_char()**. This function is probably only useful for *libcaca* 's internal display drivers. This function never fails. **Parameters** *cv* A libcaca canvas. **Returns** The canvas character array. ### \_\_extern uint32\_t const \* caca\_get\_canvas\_attrs (caca\_canvas\_t const \* cv) Returns the current canvas' internal attribute array. The array elements consist in native endian 32-bit attribute values as returned by **caca\_get\_attr()**. This function is probably only useful for *libcaca* 's internal display drivers. This function never fails. **Parameters** *cv* A libcaca canvas. **Returns** The canvas attribute array. ### \_\_extern int caca\_free\_canvas (caca\_canvas\_t \* cv) Free all resources allocated by **caca\_create\_canvas()**. The canvas pointer becomes invalid and must no longer be used unless a new call to **caca\_create\_canvas()** is made. If an error occurs, -1 is returned and **errno** is set accordingly: - • EBUSY The canvas is in use by a display driver and cannot be freed. **Parameters** *cv* A libcaca canvas. **Returns** 0 in case of success, -1 if an error occurred. References **caca\_canvas\_set\_figfont()**. Referenced by **caca\_canvas\_set\_figfont()**, **caca\_create\_display\_with\_driver()**, **caca\_export\_area\_to\_memory()**, **caca\_free\_display()**, **caca\_import\_area\_from\_file()**, and **caca\_import\_area\_from\_memory()**. ### \_\_extern char const \* caca\_get\_version (void ) Return a read-only string with the *libcaca* version information. This function never fails. **Returns** The *libcaca* version information. ## Author Generated automatically by Doxygen for libcaca from the source code.