--- name: "libcucul" section: "3caca" platform: "linux" package: "libcucul-dev" version: "0.99.beta14-1" release: "Debian 5.0 (Lenny)" platforms: ["linux"] url: "https://new.carta.tech/libcucul" --- # libcucul(3caca) ## NAME libcucul basic functions - ### Functions \_\_extern **cucul\_canvas\_t** \* **cucul\_create\_canvas** (int, int)\ *Initialise a libcucul canvas.* \_\_extern int **cucul\_manage\_canvas** (**cucul\_canvas\_t** \*, int(\*)(void \*), void \*)\ *Manage a canvas.* \_\_extern int **cucul\_unmanage\_canvas** (**cucul\_canvas\_t** \*, int(\*)(void \*), void \*)\ *Unmanage a canvas.* \_\_extern int **cucul\_set\_canvas\_size** (**cucul\_canvas\_t** \*, int, int)\ *Resize a canvas.* \_\_extern int **cucul\_get\_canvas\_width** (**cucul\_canvas\_t** const \*)\ *Get the canvas width.* \_\_extern int **cucul\_get\_canvas\_height** (**cucul\_canvas\_t** const \*)\ *Get the canvas height.* \_\_extern uint8\_t const \* **cucul\_get\_canvas\_chars** (**cucul\_canvas\_t** const \*)\ *Get the canvas character array.* \_\_extern uint8\_t const \* **cucul\_get\_canvas\_attrs** (**cucul\_canvas\_t** const \*)\ *Get the canvas attribute array.* \_\_extern int **cucul\_free\_canvas** (**cucul\_canvas\_t** \*)\ *Uninitialise libcucul.* \_\_extern int **cucul\_rand** (int, int)\ *Generate a random integer within a range.* \_\_extern char const \* **cucul\_get\_version** (void)\ *Return the libcucul version.* ## Detailed Description These functions provide the basic *libcaca* routines for library initialisation, system information retrieval and configuration. ## Function Documentation ### \_\_extern cucul\_canvas\_t\* cucul\_create\_canvas (int width, int height) Initialise internal *libcucul* structures and the backend that will be used for subsequent graphical operations. It must be the first *libcucul* function to be called in a function. **cucul\_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. - • `ENOMEM` Not enough memory for the requested canvas size. **Parameters:** *width* The desired canvas width \ *height* The desired canvas height **Returns:** A libcucul canvas handle upon success, NULL if an error occurred. References CUCUL\_DEFAULT, cucul\_set\_color\_ansi(), and CUCUL\_TRANSPARENT. Referenced by caca\_create\_display\_with\_driver(), and cucul\_set\_canvas\_boundaries(). ### \_\_extern int cucul\_manage\_canvas (cucul\_canvas\_t \* cv, int(\*)(void \*) callback, void \* p) Lock a canvas to prevent it from being resized. If non-NULL, the *callback* function pointer will be called upon each *cucul\_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 libcucul 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 cucul\_unmanage\_canvas (cucul\_canvas\_t \* cv, int(\*)(void \*) callback, void \* p) Unlock a canvas previously locked by **cucul\_manage\_canvas()**. For safety reasons, the callback and callback data arguments must be the same as for the **cucul\_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 libcucul canvas. \ *callback* The *callback* argument previously passed to **cucul\_manage\_canvas()**. \ *p* The *p* argument previously passed to **cucul\_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 cucul\_set\_canvas\_size (cucul\_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. - • `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 libcucul canvas. \ *width* The desired canvas width. \ *height* The desired canvas height. **Returns:** 0 in case of success, -1 if an error occurred. ### \_\_extern int cucul\_get\_canvas\_width (cucul\_canvas\_t const \* cv) Return the current canvas' width, in character cells. This function never fails. **Parameters:** *cv* A libcucul canvas. **Returns:** The canvas width. Referenced by caca\_get\_mouse\_x(). ### \_\_extern int cucul\_get\_canvas\_height (cucul\_canvas\_t const \* cv) Returns the current canvas' height, in character cells. This function never fails. **Parameters:** *cv* A libcucul canvas. **Returns:** The canvas height. Referenced by caca\_get\_mouse\_y(). ### \_\_extern uint8\_t const\* cucul\_get\_canvas\_chars (cucul\_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 **cucul\_get\_char()**. This function is only useful for display drivers such as the *libcaca* library. This function never fails. **Parameters:** *cv* A libcucul canvas. **Returns:** The canvas character array. ### \_\_extern uint8\_t const\* cucul\_get\_canvas\_attrs (cucul\_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 **cucul\_get\_attr()**. This function is only useful for display drivers such as the *libcaca* library. This function never fails. **Parameters:** *cv* A libcucul canvas. **Returns:** The canvas attribute array. ### \_\_extern int cucul\_free\_canvas (cucul\_canvas\_t \* cv) Free all resources allocated by **cucul\_create\_canvas()**. After this function has been called, no other *libcucul* functions may be used unless a new call to **cucul\_create\_canvas()** is done. 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 libcucul 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 cucul\_rand (int min, int max) Generate a random integer within the given range. This function never fails. **Parameters:** *min* The lower bound of the integer range. \ *max* The upper bound of the integer range. **Returns:** A random integer comprised between `min` and `max` - 1 (inclusive). ### \_\_extern char const\* cucul\_get\_version (void) Return a read-only string with the *libcucul* version information. This function never fails. **Returns:** The *libcucul* version information.