libcucul canvas drawing


Functions

int cucul_set_color (cucul_canvas_t *, unsigned char, unsigned char)
 Set the default colour pair.
int cucul_set_truecolor (cucul_canvas_t *, unsigned int, unsigned int)
 Set the default colour pair (truecolor version).
unsigned long int cucul_get_color (cucul_canvas_t *, int, int)
 Get the colour pair at the given coordinates.
char const * cucul_get_color_name (unsigned int)
 Translate a colour index into the colour's name.
int cucul_putchar (cucul_canvas_t *, int, int, unsigned long int)
 Print an ASCII or Unicode character.
unsigned long int cucul_getchar (cucul_canvas_t *, int, int)
 Get the Unicode character at the given coordinates.
int cucul_putstr (cucul_canvas_t *, int, int, char const *)
 Print a string.
int cucul_printf (cucul_canvas_t *, int, int, char const *,...)
 Print a formated string.
int cucul_clear_canvas (cucul_canvas_t *)
 Clear the canvas.
int cucul_blit (cucul_canvas_t *, int, int, cucul_canvas_t const *, cucul_canvas_t const *)
 Blit a canvas onto another one.
int cucul_set_canvas_boundaries (cucul_canvas_t *, int, int, unsigned int, unsigned int)
 Set a canvas' new boundaries.

Detailed Description

These functions provide low-level character printing routines and higher level graphics functions.

Function Documentation

int cucul_set_color cucul_canvas_t cv,
unsigned char  fg,
unsigned char  bg
 

This function sets the default ANSI colour pair. String functions such as caca_printf() and graphical primitive functions such as caca_draw_line() will use these colours.

Color values are those defined in cucul.h, such as CUCUL_COLOR_RED or CUCUL_COLOR_TRANSPARENT.

If an error occurs, -1 is returned and errno is set accordingly:

  • EINVAL At least one of the colour values is invalid.

Parameters:
cv A handle to the libcucul canvas.
fg The requested foreground colour.
bg The requested background colour.
Returns:
0 in case of success, -1 if an error occurred.

int cucul_set_truecolor cucul_canvas_t cv,
unsigned int  fg,
unsigned int  bg
 

This function sets the default colour pair. String functions such as caca_printf() and graphical primitive functions such as caca_draw_line() will use these colours.

Colors are 16-bit ARGB values, each component being coded on 4 bits. For instance, 0xf088 is solid dark cyan (A=15 R=0 G=8 B=8), and 0x8fff is white with 50% alpha (A=8 R=15 G=15 B=15).

If an error occurs, -1 is returned and errno is set accordingly:

  • EINVAL At least one of the colour values is invalid.

Parameters:
cv A handle to the libcucul canvas.
fg The requested foreground colour.
bg The requested background colour.
Returns:
0 in case of success, -1 if an error occurred.

unsigned long int cucul_get_color cucul_canvas_t cv,
int  x,
int  y
 

This function gets the internal libcucul colour pair value of the character at the given coordinates. The colour pair value has 32 significant bits: the lower 16 are for the foreground colour, the higher 16 are for the background.

If the coordinates are outside the canvas boundaries, the current colour pair is returned.

This function never fails.

Parameters:
cv A handle to the libcucul canvas.
x X coordinate.
y Y coordinate.
ch The requested colour pair value.
Returns:
The character always returns 0.

char const* cucul_get_color_name unsigned int  color  ) 
 

This function translates a cucul_color enum into a human-readable description string of the associated colour.

This function never fails.

Parameters:
color The colour value.
Returns:
A static string containing the colour's name, or "unknown" if the colour is unknown.

int cucul_putchar cucul_canvas_t cv,
int  x,
int  y,
unsigned long int  ch
 

This function prints an ASCII or Unicode character at the given coordinates, using the default foreground and background values.

If the coordinates are outside the canvas boundaries, nothing is printed. If the character value is a non-printable character or is outside the UTF-32 range, it is replaced with a space. To print a sequence of bytes forming an UTF-8 character instead of an UTF-32 character, use the cucul_putstr() function instead.

This function never fails.

Parameters:
cv A handle to the libcucul canvas.
x X coordinate.
y Y coordinate.
ch The character to print.
Returns:
This function always returns 0.

unsigned long int cucul_getchar cucul_canvas_t cv,
int  x,
int  y
 

This function gets the ASCII or Unicode value of the character at the given coordinates. If the value is less or equal to 127 (0x7f), the character can be printed as ASCII. Otherise, it must be handled as a UTF-32 value.

If the coordinates are outside the canvas boundaries, a space (0x20) is returned.

This function never fails.

Parameters:
cv A handle to the libcucul canvas.
x X coordinate.
y Y coordinate.
ch The requested character value.
Returns:
The character always returns 0.

int cucul_putstr cucul_canvas_t cv,
int  x,
int  y,
char const *  s
 

This function prints an UTF-8 string at the given coordinates, using the default foreground and background values. The coordinates may be outside the canvas boundaries (eg. a negative Y coordinate) and the string will be cropped accordingly if it is too long.

This function never fails.

Parameters:
cv A handle to the libcucul canvas.
x X coordinate.
y Y coordinate.
s The string to print.
Returns:
This function always returns 0.

int cucul_printf cucul_canvas_t cv,
int  x,
int  y,
char const *  format,
  ...
 

This function formats a string at the given coordinates, using the default foreground and background values. The coordinates may be outside the canvas boundaries (eg. a negative Y coordinate) and the string will be cropped accordingly if it is too long. The syntax of the format string is the same as for the C printf() function.

This function never fails.

Parameters:
cv A handle to the libcucul canvas.
x X coordinate.
y Y coordinate.
format The format string to print.
... Arguments to the format string.
Returns:
This function always returns 0.

int cucul_clear_canvas cucul_canvas_t cv  ) 
 

This function clears the canvas using the current background colour.

This function never fails.

Parameters:
cv The canvas to clear.
Returns:
This function always returns 0.

int cucul_blit cucul_canvas_t dst,
int  x,
int  y,
cucul_canvas_t const *  src,
cucul_canvas_t const *  mask
 

This function blits a canvas onto another one at the given coordinates. An optional mask canvas can be used.

If an error occurs, -1 is returned and errno is set accordingly:

  • EINVAL A mask was specified but the mask size and source canvas size do not match.

Parameters:
dst The destination canvas.
x X coordinate.
y Y coordinate.
src The source canvas.
mask The mask canvas.
Returns:
0 in case of success, -1 if an error occurred.

int cucul_set_canvas_boundaries cucul_canvas_t cv,
int  x,
int  y,
unsigned int  w,
unsigned int  h
 

This function sets new boundaries for a canvas. It can be used to crop a canvas, to expand it or for combinations of both actions.

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 The canvas to crop.
x X coordinate of the top-left corner.
y Y coordinate of the top-left corner.
w The width of the cropped area.
h The height of the cropped area.
Returns:
0 in case of success, -1 if an error occurred.