libcucul basic functions(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).