libcucul basic functions

Functions
cucul_canvas_t *	cucul_create_canvas (unsigned int, unsigned int)
	Initialise a libcucul canvas.
cucul_canvas_t *	cucul_load_canvas (void *, unsigned int)
	Load a memory area into a canvas.
void	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.
void	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 )

This function initialises 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. If one of the desired canvas coordinates is zero, a default canvas size of 80x32 is used instead. Parameters: width  The desired canvas width height  The desired canvas height Returns: A libcucul canvas handle upon success, NULL if an error occurred.

cucul_canvas_t* cucul_load_canvas (  void *  data, unsigned int  size )

This function loads a memory area containing an exported canvas into a new libcucul canvas. Parameters: data  The memory area to be loaded into a canvas. size  The length of the memory area. Returns: A libcucul canvas, or NULL in case of error.

void cucul_set_canvas_size (  cucul_canvas_t *  cv, unsigned int  width, unsigned int  height )

This function sets 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. Parameters: cv  A libcucul canvas width  The desired canvas width height  The desired canvas height

unsigned int cucul_get_canvas_width (  cucul_canvas_t *  cv  )

This function returns the current canvas width, in character cells. Parameters: cv  A libcucul canvas Returns: The canvas width.

unsigned int cucul_get_canvas_height (  cucul_canvas_t *  cv  )

This function returns the current canvas height, in character cells. Parameters: cv  A libcucul canvas Returns: The canvas height.

void cucul_free_canvas (  cucul_canvas_t *  cv  )

This function frees all resources allocated by cucul_create_canvas(). After cucul_free_canvas() has been called, no other libcucul functions may be used unless a new call to cucul_create_canvas() is done. Parameters: cv  A libcucul canvas

int cucul_rand (  int  min, int  max )

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