libcaca  0.99.beta19
About: libcaca is a graphics library that outputs text instead of pixels, so that it can work on older video cards or text terminals (something like an advanced AAlib library).
  Fossies Dox: libcaca-0.99.beta19.tar.gz  ("inofficial" and yet experimental doxygen-generated source code documentation)  

libcaca canvas drawing

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

Macros

#define CACA_MAGIC_FULLWIDTH   0x000ffffe
 

Functions

int caca_gotoxy (caca_canvas_t *, int, int)
 Set cursor position. More...
 
int caca_wherex (caca_canvas_t const *)
 Get X cursor position. More...
 
int caca_wherey (caca_canvas_t const *)
 Get Y cursor position. More...
 
int caca_put_char (caca_canvas_t *, int, int, uint32_t)
 Print an ASCII or Unicode character. More...
 
uint32_t caca_get_char (caca_canvas_t const *, int, int)
 Get the Unicode character at the given coordinates. More...
 
int caca_put_str (caca_canvas_t *, int, int, char const *)
 Print a string. More...
 
int caca_printf (caca_canvas_t *, int, int, char const *,...)
 Print a formated string. More...
 
int caca_vprintf (caca_canvas_t *, int, int, char const *, va_list)
 Print a formated string (va_list version). More...
 
int caca_clear_canvas (caca_canvas_t *)
 Clear the canvas. More...
 
int caca_set_canvas_handle (caca_canvas_t *, int, int)
 Set cursor handle. More...
 
int caca_get_canvas_handle_x (caca_canvas_t const *)
 Get X handle position. More...
 
int caca_get_canvas_handle_y (caca_canvas_t const *)
 Get Y handle position. More...
 
int caca_blit (caca_canvas_t *, int, int, caca_canvas_t const *, caca_canvas_t const *)
 Blit a canvas onto another one. More...
 
int caca_set_canvas_boundaries (caca_canvas_t *, int, int, int, int)
 Set a canvas' new boundaries. More...
 

Detailed Description

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

Macro Definition Documentation

◆ CACA_MAGIC_FULLWIDTH

#define CACA_MAGIC_FULLWIDTH   0x000ffffe

Used to indicate that the previous character was a fullwidth glyph.

Definition at line 250 of file caca.h.

Function Documentation

◆ caca_blit()

int caca_blit ( caca_canvas_t ,
int  ,
int  ,
caca_canvas_t const *  ,
caca_canvas_t const *   
)

Blit a canvas onto another one.

Blit 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
dstThe destination canvas.
xX coordinate.
yY coordinate.
srcThe source canvas.
maskThe mask canvas.
Returns
0 in case of success, -1 if an error occurred.

< Used to indicate that the previous character was a fullwidth glyph.

< Used to indicate that the previous character was a fullwidth glyph.

< Used to indicate that the previous character was a fullwidth glyph.

< Used to indicate that the previous character was a fullwidth glyph.

Definition at line 455 of file string.c.

References attrs, caca_add_dirty_rect(), CACA_MAGIC_FULLWIDTH, chars, dirty_disabled, frame, frames, caca_frame::handlex, caca_frame::handley, height, seterrno, width, x, and y.

Referenced by Canvas::Blit(), blit(), caca_conio_movetext(), caca_export_area_to_memory(), caca_import_area_from_file(), caca_import_area_from_memory(), caca_put_figchar(), caca_set_canvas_boundaries(), Java_org_zoy_caca_Canvas_blitCanvas(), main(), and refresh_screen().

◆ caca_clear_canvas()

int caca_clear_canvas ( caca_canvas_t )

Clear the canvas.

Clear the canvas using the current foreground and background colours.

This function never fails.

Parameters
cvThe canvas to clear.
Returns
This function always returns 0.

Definition at line 374 of file string.c.

References attrs, caca_add_dirty_rect(), chars, curattr, cv, dirty_disabled, height, and width.

Referenced by caca_conio_clrscr(), Canvas::Clear(), Java_org_zoy_caca_Canvas_clearCanvas(), main(), matrix(), and refresh_screen().

◆ caca_get_canvas_handle_x()

int caca_get_canvas_handle_x ( caca_canvas_t const *  )

Get X handle position.

Retrieve the X coordinate of the canvas' handle.

This function never fails.

Parameters
cvA handle to the libcaca canvas.
Returns
The canvas' handle's X coordinate.

Definition at line 420 of file string.c.

References cv, frame, frames, and caca_frame::handlex.

Referenced by Java_org_zoy_caca_Canvas_getHandleX(), and Java_org_zoy_caca_Canvas_getHandleY().

◆ caca_get_canvas_handle_y()

int caca_get_canvas_handle_y ( caca_canvas_t const *  )

Get Y handle position.

Retrieve the Y coordinate of the canvas' handle.

This function never fails.

Parameters
cvA handle to the libcaca canvas.
Returns
The canvas' handle's Y coordinate.

Definition at line 434 of file string.c.

References cv, frame, frames, and caca_frame::handley.

◆ caca_get_char()

uint32_t caca_get_char ( caca_canvas_t const *  ,
int  ,
int   
)

Get the Unicode character at the given coordinates.

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

A special exception is when CACA_MAGIC_FULLWIDTH is returned. This value is guaranteed not to be a valid Unicode character, and indicates that the character at the left of the requested one is a fullwidth character.

This function never fails.

Parameters
cvA handle to the libcaca canvas.
xX coordinate.
yY coordinate.
Returns
The Unicode character at the given coordinates.

Definition at line 224 of file string.c.

References chars, cv, height, width, x, and y.

Referenced by _import_ansi(), caca_fill_triangle_textured_l(), caca_flush_figlet(), caca_getchar(), caca_put_figchar(), get_char(), Canvas::getChar(), Java_org_zoy_caca_Canvas_getCanvasChar(), and open_charfont().

◆ caca_gotoxy()

int caca_gotoxy ( caca_canvas_t ,
int  ,
int   
)

Set cursor position.

Put the cursor at the given coordinates. Functions making use of the cursor will use the new values. Setting the cursor position outside the canvas is legal but the cursor will not be shown.

This function never fails.

Parameters
cvA handle to the libcaca canvas.
xX cursor coordinate.
yY cursor coordinate.
Returns
This function always returns 0.

Definition at line 58 of file string.c.

References cv, frame, frames, x, caca_frame::x, y, and caca_frame::y.

Referenced by caca_conio_cgets(), caca_conio_clrscr(), caca_conio_cprintf(), caca_conio_cputs(), caca_conio_gotoxy(), caca_conio_printf(), caca_conio_putch(), gotoxy(), and Java_org_zoy_caca_Canvas_setCursorXY().

◆ caca_printf()

int caca_printf ( caca_canvas_t ,
int  ,
int  ,
char const *  ,
  ... 
)

Print a formated string.

Format 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 returns the number of cells printed by the string. It is not the number of characters printed, because fullwidth characters account for two cells.

This function never fails.

Parameters
cvA handle to the libcaca canvas.
xX coordinate.
yY coordinate.
formatThe format string to print.
...Arguments to the format string.
Returns
The number of cells printed.

Definition at line 304 of file string.c.

References caca_vprintf(), cv, x, and y.

◆ caca_put_char()

int caca_put_char ( caca_canvas_t ,
int  ,
int  ,
uint32_t   
)

Print an ASCII or Unicode character.

Print an ASCII or Unicode character at the given coordinates, using the default foreground and background colour values.

If the coordinates are outside the canvas boundaries, nothing is printed. If a fullwidth Unicode character gets overwritten, its remaining visible parts are replaced with spaces. If the canvas' boundaries would split the fullwidth character in two, a space is printed instead.

The behaviour when printing non-printable characters or invalid UTF-32 characters is undefined. To print a sequence of bytes forming an UTF-8 character instead of an UTF-32 character, use the caca_put_str() function.

This function returns the width of the printed character. If it is a fullwidth character, 2 is returned. Otherwise, 1 is returned.

This function never fails.

Parameters
cvA handle to the libcaca canvas.
xX coordinate.
yY coordinate.
chThe character to print.
Returns
The width of the printed character: 2 for a fullwidth character, 1 otherwise.

< Used to indicate that the previous character was a fullwidth glyph.

< Used to indicate that the previous character was a fullwidth glyph.

< Used to indicate that the previous character was a fullwidth glyph.

< Used to indicate that the previous character was a fullwidth glyph.

< Used to indicate that the previous character was a fullwidth glyph.

Definition at line 120 of file string.c.

References attrs, caca_add_dirty_rect(), CACA_MAGIC_FULLWIDTH, caca_utf32_is_fullwidth(), chars, curattr, cv, dirty_disabled, height, width, x, and y.

Referenced by _import_ansi(), _import_bin(), _import_text(), caca_conio_cgets(), caca_conio_cputs(), caca_conio_putch(), caca_dither_bitmap(), caca_fill_box(), caca_fill_triangle(), caca_fill_triangle_textured_l(), caca_flush_figlet(), caca_put_figchar(), caca_put_str(), caca_putchar(), draw_box(), draw_checkers(), draw_solid_line(), draw_thin_line(), ellipsepoints(), import_caca(), Java_org_zoy_caca_Canvas_putCanvasChar(), langton(), main(), matrix(), open_charfont(), put_char(), and Canvas::putChar().

◆ caca_put_str()

int caca_put_str ( caca_canvas_t ,
int  ,
int  ,
char const *   
)

Print a string.

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

See caca_put_char() for more information on how fullwidth characters are handled when overwriting each other or at the canvas' boundaries.

This function returns the number of cells printed by the string. It is not the number of characters printed, because fullwidth characters account for two cells.

This function never fails.

Parameters
cvA handle to the libcaca canvas.
xX coordinate.
yY coordinate.
sThe string to print.
Returns
The number of cells printed.

Definition at line 254 of file string.c.

References caca_put_char(), caca_utf32_is_fullwidth(), caca_utf8_to_utf32(), cv, height, width, x, and y.

Referenced by caca_vprintf(), cprintf(), cucul_putstr(), drawfire(), Java_org_zoy_caca_Canvas_putCanvasString(), main(), print_help(), print_status(), put_str(), and Canvas::putStr().

◆ caca_set_canvas_boundaries()

int caca_set_canvas_boundaries ( caca_canvas_t ,
int  ,
int  ,
int  ,
int   
)

Set a canvas' new boundaries.

Set new boundaries for a canvas. This function can be used to crop a canvas, to expand it or for combinations of both actions. All frames are affected by this function.

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.
Parameters
cvThe canvas to crop.
xX coordinate of the top-left corner.
yY coordinate of the top-left corner.
wThe width of the cropped area.
hThe height of the cropped area.
Returns
0 in case of success, -1 if an error occurred.

Definition at line 561 of file string.c.

References _caca_load_frame_info(), caca_frame::attrs, caca_add_dirty_rect(), caca_blit(), caca_create_canvas(), caca_create_frame(), caca_get_frame_count(), caca_set_frame(), caca_frame::chars, cv, dirty_disabled, frame, frames, height, refcount, seterrno, width, x, and y.

Referenced by Java_org_zoy_caca_Canvas_setCanvasBoundaries(), set_canvas_boundaries(), and Canvas::setBoundaries().

◆ caca_set_canvas_handle()

int caca_set_canvas_handle ( caca_canvas_t ,
int  ,
int   
)

Set cursor handle.

Set the canvas' handle. Blitting functions will use the handle value to put the canvas at the proper coordinates.

This function never fails.

Parameters
cvA handle to the libcaca canvas.
xX handle coordinate.
yY handle coordinate.
Returns
This function always returns 0.

Definition at line 403 of file string.c.

References cv, frame, frames, caca_frame::handlex, caca_frame::handley, x, and y.

Referenced by caca_put_figchar(), Java_org_zoy_caca_Canvas_setHandleXY(), and set_canvas_handle().

◆ caca_vprintf()

int caca_vprintf ( caca_canvas_t cv,
int  x,
int  y,
char const *  format,
va_list  args 
)

Print a formated string (va_list version).

Format a string at the given coordinates, using the default foreground and background values. The coordinates may be outside the canvas boundaries (eg. a negative X 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 vprintf() function.

This function returns the number of cells printed by the string. It is not the number of characters printed, because fullwidth characters account for two cells.

This function never fails.

Parameters
cvA handle to the libcaca canvas.
xX coordinate.
yY coordinate.
formatThe format string to print.
argsA va_list containting the arguments to the format string.
Returns
The number of cells printed.

Definition at line 335 of file string.c.

References caca_put_str(), cv, width, x, and y.

Referenced by caca_conio_cprintf(), caca_conio_printf(), and caca_printf().

◆ caca_wherex()

int caca_wherex ( caca_canvas_t const *  )

Get X cursor position.

Retrieve the X coordinate of the cursor's position.

This function never fails.

Parameters
cvA handle to the libcaca canvas.
Returns
The cursor's X coordinate.

Definition at line 75 of file string.c.

References cv, frame, frames, and caca_frame::x.

Referenced by caca_conio_cgets(), caca_conio_clreol(), caca_conio_cprintf(), caca_conio_cputs(), caca_conio_printf(), caca_conio_putch(), caca_conio_wherex(), and wherex().

◆ caca_wherey()

int caca_wherey ( caca_canvas_t const *  )

Get Y cursor position.

Retrieve the Y coordinate of the cursor's position.

This function never fails.

Parameters
cvA handle to the libcaca canvas.
Returns
The cursor's Y coordinate.

Definition at line 89 of file string.c.

References cv, frame, frames, and caca_frame::y.

Referenced by caca_conio_cgets(), caca_conio_clreol(), caca_conio_cprintf(), caca_conio_cputs(), caca_conio_printf(), caca_conio_putch(), caca_conio_wherey(), and wherey().