---
name: "cucul"
section: "3caca"
platform: "linux"
package: "libcucul-dev"
version: "0.99.beta11.debian-2"
release: "Debian 4.0 (Etch)"
platforms: ["linux"]
url: "https://new.carta.tech/cucul"
---

# cucul(3caca)

## NAME

libcucul basic functions -

### Functions

**cucul\_canvas\_t** \* **cucul\_create\_canvas** (unsigned int, unsigned int)\
 *Initialise a libcucul canvas.*  int **cucul\_set\_canvas\_size** (**cucul\_canvas\_t** \*, unsigned int, unsigned int)\
 *Resize a canvas.*  unsigned int **cucul\_get\_canvas\_width** (**cucul\_canvas\_t** \*)\
 *Get the canvas width.*  unsigned int **cucul\_get\_canvas\_height** (**cucul\_canvas\_t** \*)\
 *Get the canvas height.*  int **cucul\_free\_canvas** (**cucul\_canvas\_t** \*)\
 *Uninitialise libcucul.*  int **cucul\_rand** (int, int)\
 *Generate a random integer within a range.*

## Detailed Description

These functions provide the basic *libcaca* routines for library initialisation, system information retrieval and configuration.

## Function Documentation

### cucul\_canvas\_t\* cucul\_create\_canvas (unsigned int width, unsigned 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:

- •

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

### int cucul\_set\_canvas\_size (cucul\_canvas\_t \* cv, unsigned int width, unsigned 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.

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:

- •

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

### unsigned int cucul\_get\_canvas\_width (cucul\_canvas\_t \* cv)

Return the current canvas' width, in character cells.

This function never fails.

**Parameters:**

*cv* A libcucul canvas

**Returns:**

The canvas width.

### unsigned int cucul\_get\_canvas\_height (cucul\_canvas\_t \* cv)

Returns the current canvas' height, in character cells.

This function never fails.

**Parameters:**

*cv* A libcucul canvas

**Returns:**

The canvas height.

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

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