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 basic functions

These functions provide the basic libcaca routines for library initialisation, system information retrieval and configuration. More...

Functions

caca_canvas_tcaca_create_canvas (int, int)
 Initialise a libcaca canvas. More...
 
int caca_manage_canvas (caca_canvas_t *, int(*)(void *), void *)
 Manage a canvas. More...
 
int caca_unmanage_canvas (caca_canvas_t *, int(*)(void *), void *)
 unmanage a canvas. More...
 
int caca_set_canvas_size (caca_canvas_t *, int, int)
 Resize a canvas. More...
 
int caca_get_canvas_width (caca_canvas_t const *)
 Get the canvas width. More...
 
int caca_get_canvas_height (caca_canvas_t const *)
 Get the canvas height. More...
 
const uint32_t * caca_get_canvas_chars (caca_canvas_t const *)
 Get the canvas character array. More...
 
const uint32_t * caca_get_canvas_attrs (caca_canvas_t const *)
 Get the canvas attribute array. More...
 
int caca_free_canvas (caca_canvas_t *)
 Free a libcaca canvas. More...
 
int caca_rand (int, int)
 
const char * caca_get_version (void)
 Return the libcaca version. More...
 

Detailed Description

These functions provide the basic libcaca routines for library initialisation, system information retrieval and configuration.

Function Documentation

◆ caca_create_canvas()

caca_canvas_t * caca_create_canvas ( int  ,
int   
)

Initialise a libcaca canvas.

Initialise internal libcaca structures and the backend that will be used for subsequent graphical operations. It must be the first libcaca function to be called in a function. caca_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.
Parameters
widthThe desired canvas width
heightThe desired canvas height
Returns
A libcaca canvas handle upon success, NULL if an error occurred.

Definition at line 54 of file canvas.c.

References _caca_load_frame_info(), caca_frame::attrs, caca_canvas::autoinc, CACA_DEFAULT, caca_resize(), caca_set_color_ansi(), CACA_TRANSPARENT, caca_frame::chars, caca_frame::curattr, cv, caca_canvas::dirty_disabled, caca_canvas::ff, caca_canvas::frame, caca_canvas::framecount, caca_canvas::frames, geterrno, caca_frame::handlex, caca_frame::handley, caca_frame::height, caca_frame::name, caca_canvas::ndirty, caca_canvas::refcount, caca_canvas::resize_callback, caca_canvas::resize_data, seterrno, caca_frame::width, caca_frame::x, and caca_frame::y.

Referenced by __caca0_init(), __caca0_load_sprite(), caca_conio_movetext(), caca_create_display_with_driver(), caca_export_area_to_memory(), caca_import_area_from_file(), caca_import_area_from_memory(), caca_set_canvas_boundaries(), Canvas::Canvas(), canvas_initialize(), conio_init(), cucul_import_canvas(), initialize(), Java_org_zoy_caca_Canvas_createCanvas(), main(), open_charfont(), and update_figfont_settings().

◆ caca_free_canvas()

int caca_free_canvas ( caca_canvas_t )

Free a libcaca canvas.

Free all resources allocated by caca_create_canvas(). The canvas pointer becomes invalid and must no longer be used unless a new call to caca_create_canvas() is made.

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
cvA libcaca canvas.
Returns
0 in case of success, -1 if an error occurred.

Definition at line 308 of file canvas.c.

References caca_frame::attrs, caca_canvas_set_figfont(), caca_frame::chars, cv, caca_canvas::framecount, caca_canvas::frames, caca_frame::name, caca_canvas::refcount, and seterrno.

Referenced by __caca0_end(), __caca0_init(), __caca0_load_sprite(), caca_canvas_set_figfont(), caca_create_display_with_driver(), caca_export_area_to_memory(), caca_free_display(), caca_import_area_from_file(), caca_import_area_from_memory(), canvas_free(), conio_fini(), cucul_import_canvas(), free_charfont(), Java_org_zoy_caca_Canvas_freeCanvas(), main(), uninitialize(), update_figfont_settings(), and Canvas::~Canvas().

◆ caca_get_canvas_attrs()

const uint32_t * caca_get_canvas_attrs ( caca_canvas_t const *  )

Get the canvas attribute array.

Returns the current canvas' internal attribute array. The array elements consist in native endian 32-bit attribute values as returned by caca_get_attr().

This function is probably only useful for libcaca 's internal display drivers.

This function never fails.

Parameters
cvA libcaca canvas.
Returns
The canvas attribute array.

Definition at line 291 of file canvas.c.

References caca_canvas::attrs, and cv.

◆ caca_get_canvas_chars()

const uint32_t * caca_get_canvas_chars ( caca_canvas_t const *  )

Get the canvas character array.

Return the current canvas' internal character array. The array elements consist in native endian 32-bit Unicode values as returned by caca_get_char().

This function is probably only useful for libcaca 's internal display drivers.

This function never fails.

Parameters
cvA libcaca canvas.
Returns
The canvas character array.

Definition at line 272 of file canvas.c.

References caca_canvas::chars, and cv.

◆ caca_get_canvas_height()

int caca_get_canvas_height ( caca_canvas_t const *  )

Get the canvas height.

Returns the current canvas' height, in character cells.

This function never fails.

Parameters
cvA libcaca canvas.
Returns
The canvas height.

Definition at line 253 of file canvas.c.

References cv, and caca_canvas::height.

Referenced by _caca_handle_resize(), _get_next_event(), caca_fill_triangle_textured_l(), caca_flush_figlet(), caca_get_mouse_y(), caca_install_driver(), draw_checkers(), drawfire(), export_tga(), Canvas::getHeight(), initialize(), Java_org_zoy_caca_Canvas_getCanvasHeight(), langton(), main(), matrix(), metaballs(), moire(), plasma(), raw_init_graphics(), rotozoom(), set_canvas_width(), set_zoom(), and transition().

◆ caca_get_canvas_width()

int caca_get_canvas_width ( caca_canvas_t const *  )

Get the canvas width.

Return the current canvas' width, in character cells.

This function never fails.

Parameters
cvA libcaca canvas.
Returns
The canvas width.

Definition at line 239 of file canvas.c.

References cv, and caca_canvas::width.

Referenced by _caca_handle_resize(), _get_next_event(), caca_conio_clreol(), caca_conio_movetext(), caca_fill_triangle_textured_l(), caca_get_mouse_x(), caca_install_driver(), draw_checkers(), drawfire(), export_tga(), Canvas::getWidth(), initialize(), Java_org_zoy_caca_Canvas_getCanvasWidth(), langton(), main(), matrix(), metaballs(), moire(), plasma(), raw_init_graphics(), rotozoom(), set_canvas_height(), set_zoom(), and transition().

◆ caca_get_version()

const char* caca_get_version ( void  )

Return the libcaca version.

Return a read-only string with the libcaca version information.

This function never fails.

Returns
The libcaca version information.

Definition at line 272 of file caca.c.

References PACKAGE_VERSION.

Referenced by export_html(), get_version(), Canvas::getVersion(), Caca::getVersion(), Java_org_zoy_caca_Caca_getVersion(), and version().

◆ caca_manage_canvas()

int caca_manage_canvas ( caca_canvas_t ,
int(*)(void *)  ,
void *   
)

Manage a canvas.

Lock a canvas to prevent it from being resized. If non-NULL, the callback function pointer will be called upon each caca_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.
Parameters
cvA libcaca canvas.
callbackAn optional callback function pointer.
pThe argument to be passed to callback.
Returns
0 in case of success, -1 if an error occurred.

Definition at line 133 of file canvas.c.

References cv, caca_canvas::refcount, caca_canvas::resize_callback, caca_canvas::resize_data, and seterrno.

Referenced by caca_create_display_with_driver().

◆ caca_rand()

int caca_rand ( int  ,
int   
)

Definition at line 346 of file canvas.c.

References _caca_getticks(), min, caca.common::rand(), and timer.

◆ caca_set_canvas_size()

int caca_set_canvas_size ( caca_canvas_t ,
int  ,
int   
)

Resize a canvas.

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.
Parameters
cvA libcaca canvas.
widthThe desired canvas width.
heightThe desired canvas height.
Returns
0 in case of success, -1 if an error occurred.

Definition at line 212 of file canvas.c.

References caca_resize(), cv, caca_canvas::refcount, caca_canvas::resize_callback, caca_canvas::resize_data, and seterrno.

Referenced by _caca_handle_resize(), _import_ansi(), _import_bin(), _import_text(), caca_canvas_set_figfont(), caca_flush_figlet(), caca_put_figchar(), import_caca(), Java_org_zoy_caca_Canvas_setCanvasSize(), main(), raw_init_graphics(), set_canvas_height(), set_canvas_size(), set_canvas_width(), and Canvas::setSize().

◆ caca_unmanage_canvas()

int caca_unmanage_canvas ( caca_canvas_t ,
int(*)(void *)  ,
void *   
)

unmanage a canvas.

unlock a canvas previously locked by caca_manage_canvas(). for safety reasons, the callback and callback data arguments must be the same as for the caca_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.
Parameters
cva libcaca canvas.
callbackthe callback argument previously passed to caca_manage_canvas().
pthe p argument previously passed to caca_manage_canvas().
Returns
0 in case of success, -1 if an error occurred.

Definition at line 167 of file canvas.c.

References cv, caca_canvas::refcount, caca_canvas::resize_callback, caca_canvas::resize_data, and seterrno.

Referenced by caca_create_display_with_driver(), and caca_free_display().