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. | |
| __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.
| width | The desired canvas width | |
| height | The desired canvas height |
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.
| cv | A libcucul canvas. | |
| callback | An optional callback function pointer. | |
| p | The argument to be passed to callback. |
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.
| cv | A libcucul canvas. | |
| callback | The callback argument previously passed to cucul_manage_canvas(). | |
| p | The p argument previously passed to cucul_manage_canvas(). |
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.
| cv | A libcucul canvas. | |
| width | The desired canvas width. | |
| height | The desired canvas height. |
| __extern int cucul_get_canvas_width | ( | cucul_canvas_t const * | cv | ) |
Return the current canvas' width, in character cells.
This function never fails.
| cv | A libcucul canvas. |
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.
| cv | A libcucul canvas. |
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.
| cv | A libcucul canvas. |
| __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.
| cv | A libcucul canvas. |
| __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.
| cv | A libcucul canvas. |
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.
| min | The lower bound of the integer range. | |
| max | The upper bound of the integer range. |
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.