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

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

Functions

caca_display_tcaca_create_display (caca_canvas_t *)
 Attach a caca graphical context to a caca canvas. More...
 
caca_display_tcaca_create_display_with_driver (caca_canvas_t *, char const *)
 Attach a specific caca graphical context to a caca canvas. More...
 
const char *const * caca_get_display_driver_list (void)
 Get available display drivers. More...
 
const char * caca_get_display_driver (caca_display_t *)
 Return a caca graphical context's current output driver. More...
 
int caca_set_display_driver (caca_display_t *, char const *)
 Set the output driver. More...
 
int caca_free_display (caca_display_t *)
 Detach a caca graphical context from a caca backend context. More...
 
caca_canvas_tcaca_get_canvas (caca_display_t *)
 Get the canvas attached to a caca graphical context. More...
 
int caca_refresh_display (caca_display_t *)
 Flush pending changes and redraw the screen. More...
 
int caca_set_display_time (caca_display_t *, int)
 Set the refresh delay. More...
 
int caca_get_display_time (caca_display_t const *)
 Get the display's average rendering time. More...
 
int caca_get_display_width (caca_display_t const *)
 Get the display width. More...
 
int caca_get_display_height (caca_display_t const *)
 Get the display height. More...
 
int caca_set_display_title (caca_display_t *, char const *)
 Set the display title. More...
 
int caca_set_mouse (caca_display_t *, int)
 Show or hide the mouse pointer. More...
 
int caca_set_cursor (caca_display_t *, int)
 Show or hide the cursor. More...
 

Detailed Description

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

Function Documentation

◆ caca_create_display()

caca_display_t* caca_create_display ( caca_canvas_t cv)

Attach a caca graphical context to a caca canvas.

Create a graphical context using device-dependent features (ncurses for terminals, an X11 window, a DOS command window...) that attaches to a libcaca canvas. Everything that gets drawn in the libcaca canvas can then be displayed by the libcaca driver.

If no caca canvas is provided, a new one is created. Its handle can be retrieved using caca_get_canvas() and it is automatically destroyed when caca_free_display() is called.

See also caca_create_display_with_driver().

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

  • ENOMEM Not enough memory.
  • ENODEV Graphical device could not be initialised.
Parameters
cvThe caca canvas or NULL to create a canvas automatically.
Returns
The caca graphical context or NULL if an error occurred.

Definition at line 68 of file caca.c.

References caca_create_display_with_driver(), and cv.

Referenced by __caca0_init(), Caca::Attach(), Caca::Caca(), conio_init(), display_initialize(), initialize(), Java_org_zoy_caca_Display_createDisplay(), Java_org_zoy_caca_Display_createDisplayAndCanvas(), and main().

◆ caca_create_display_with_driver()

caca_display_t* caca_create_display_with_driver ( caca_canvas_t cv,
char const *  driver 
)

Attach a specific caca graphical context to a caca canvas.

Create a graphical context using device-dependent features (ncurses for terminals, an X11 window, a DOS command window...) that attaches to a libcaca canvas. Everything that gets drawn in the libcaca canvas can then be displayed by the libcaca driver.

If no caca canvas is provided, a new one is created. Its handle can be retrieved using caca_get_canvas() and it is automatically destroyed when caca_free_display() is called.

If no driver name is provided, libcaca will try to autodetect the best output driver it can.

See also caca_create_display().

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

  • ENOMEM Not enough memory.
  • ENODEV Graphical device could not be initialised.
Parameters
cvThe caca canvas or NULL to create a canvas automatically.
driverA string describing the desired output driver or NULL to choose the best driver automatically.
Returns
The caca graphical context or NULL if an error occurred.

Definition at line 98 of file caca.c.

References autorelease, caca_can_resize(), caca_create_canvas(), caca_free_canvas(), caca_install_driver(), caca_manage_canvas(), caca_unmanage_canvas(), cv, cv, dp, and seterrno.

Referenced by caca_create_display(), display_initialize(), Java_org_zoy_caca_Display_createDisplayAndCanvasWithDriver(), and Java_org_zoy_caca_Display_createDisplayWithDriver().

◆ caca_free_display()

int caca_free_display ( caca_display_t dp)

Detach a caca graphical context from a caca backend context.

Detach a graphical context from its caca backend and destroy it. The libcaca canvas continues to exist and other graphical contexts can be attached to it afterwards.

If the caca canvas was automatically created by caca_create_display(), it is automatically destroyed and any handle to it becomes invalid.

This function never fails.

Parameters
dpThe libcaca graphical context.
Returns
This function always returns 0.

Definition at line 238 of file caca.c.

References autorelease, caca_can_resize(), caca_free_canvas(), caca_uninstall_driver(), caca_unmanage_canvas(), cv, and dp.

Referenced by __caca0_end(), conio_fini(), Caca::Detach(), display_free(), Java_org_zoy_caca_Display_freeDisplay(), main(), uninitialize(), and Caca::~Caca().

◆ caca_get_canvas()

caca_canvas_t* caca_get_canvas ( caca_display_t dp)

Get the canvas attached to a caca graphical context.

Return a handle on the caca_canvas_t object that was either attached or created by caca_create_display().

This function never fails.

Parameters
dpThe libcaca graphical context.
Returns
The libcaca canvas.

Definition at line 259 of file caca.c.

References cv, and dp.

Referenced by display_initialize(), and Java_org_zoy_caca_Display_getDisplayCanvas().

◆ caca_get_display_driver()

const char* caca_get_display_driver ( caca_display_t dp)

Return a caca graphical context's current output driver.

Return the given display's current output driver.

This function never fails.

Parameters
dpThe caca display.
Returns
A static string.

Definition at line 196 of file caca.c.

References dp, caca_display::drv::driver, and drv.

Referenced by get_driver(), and Java_org_zoy_caca_Display_getDisplayDriver().

◆ caca_get_display_driver_list()

const char* const * caca_get_display_driver_list ( void  )

Get available display drivers.

Return a list of available display drivers. The list is a NULL-terminated array of strings, interleaving a string containing the internal value for the display driver, and a string containing the natural language description for that driver.

This function never fails.

Returns
An array of strings.

Definition at line 149 of file caca.c.

Referenced by driver_list(), and Java_org_zoy_caca_Display_getDisplayDriverList().

◆ caca_get_display_height()

int caca_get_display_height ( caca_display_t const *  dp)

Get the display height.

If libcaca runs in a window, get the usable window height. This value can be used for aspect ratio calculation. If libcaca does not run in a window or if there is no way to know the font size, assume a 6x10 font is being used. Note that the units are not necessarily pixels.

This function never fails.

Parameters
dpThe libcaca display context.
Returns
The display height.

Definition at line 79 of file graphics.c.

References dp, drv, and caca_display::drv::get_display_height.

Referenced by get_height(), Caca::getHeight(), Java_org_zoy_caca_Display_getDisplayHeight(), and set_zoom().

◆ caca_get_display_time()

int caca_get_display_time ( caca_display_t const *  dp)

Get the display's average rendering time.

Get the average rendering time, which is the average measured time between two caca_refresh_display() calls, in microseconds. If constant framerate was activated by calling caca_set_display_time(), the average rendering time will be close to the requested delay even if the real rendering time was shorter.

This function never fails.

Parameters
dpThe libcaca display context.
Returns
The render time in microseconds.

Definition at line 125 of file graphics.c.

References dp, and rendertime.

Referenced by get_time(), Caca::getDisplayTime(), and Java_org_zoy_caca_Display_getDisplayTime().

◆ caca_get_display_width()

int caca_get_display_width ( caca_display_t const *  dp)

Get the display width.

If libcaca runs in a window, get the usable window width. This value can be used for aspect ratio calculation. If libcaca does not run in a window or if there is no way to know the font size, most drivers will assume a 6x10 font is being used. Note that the units are not necessarily pixels.

This function never fails.

Parameters
dpThe libcaca display context.
Returns
The display width.

Definition at line 62 of file graphics.c.

References dp, drv, and caca_display::drv::get_display_width.

Referenced by get_width(), Caca::getWidth(), Java_org_zoy_caca_Display_getDisplayWidth(), and set_zoom().

◆ caca_refresh_display()

int caca_refresh_display ( caca_display_t dp)

Flush pending changes and redraw the screen.

Flush all graphical operations and print them to the display device. Nothing will show on the screen until this function is called.

If caca_set_display_time() was called with a non-zero value, caca_refresh_display() will use that value to achieve constant framerate: if two consecutive calls to caca_refresh_display() are within a time range shorter than the value set with caca_set_display_time(), the second call will be delayed before performing the screen refresh.

This function never fails.

Parameters
dpThe libcaca display context.
Returns
This function always returns 0.

Definition at line 146 of file graphics.c.

References _caca_getticks(), _caca_handle_resize(), _caca_sleep(), caca_clear_dirty_rect_list(), cv, delay, caca_display::drv::display, dp, drv, IDLE_USEC, lastticks, rendertime, resize, caca_display::resize::resized, STAT_IADD, and timer.

Referenced by conio_init(), conio_refresh(), Caca::Display(), display_refresh(), drawfire(), Java_org_zoy_caca_Display_displayRefresh(), main(), and refresh_screen().

◆ caca_set_cursor()

int caca_set_cursor ( caca_display_t dp,
int  flag 
)

Show or hide the cursor.

Show or hide the cursor, for devices that support such a feature.

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

  • ENOSYS Display driver does not support showing the cursor.
Parameters
dpThe libcaca display context.
flag0 hides the cursor, 1 shows the system's default cursor (usually a white rectangle). Other values are reserved for future use.
Returns
0 upon success, -1 if an error occurred.

Definition at line 218 of file graphics.c.

References dp, drv, caca_display::drv::set_cursor, and seterrno.

Referenced by caca_conio__setcursortype(), conio_init(), Java_org_zoy_caca_Display_setDisplayCursor(), and set_cursor().

◆ caca_set_display_driver()

int caca_set_display_driver ( caca_display_t dp,
char const *  driver 
)

Set the output driver.

Dynamically change the given display's output driver.

FIXME: decide what to do in case of failure

Parameters
dpThe caca display.
driverA string describing the desired output driver or NULL to choose the best driver automatically.
Returns
0 in case of success, -1 if an error occurred.

Definition at line 212 of file caca.c.

References caca_install_driver(), caca_uninstall_driver(), dp, and seterrno.

Referenced by Java_org_zoy_caca_Display_setDisplayDriver(), and set_driver().

◆ caca_set_display_time()

int caca_set_display_time ( caca_display_t dp,
int  usec 
)

Set the refresh delay.

Set the refresh delay in microseconds. The refresh delay is used by caca_refresh_display() to achieve constant framerate. See the caca_refresh_display() documentation for more details.

If the argument is zero, constant framerate is disabled. This is the default behaviour.

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

  • EINVAL Refresh delay value is invalid.
Parameters
dpThe libcaca display context.
usecThe refresh delay in microseconds.
Returns
0 upon success, -1 if an error occurred.

Definition at line 100 of file graphics.c.

References delay, dp, and seterrno.

Referenced by initialize(), Java_org_zoy_caca_Display_setDisplayTime(), main(), set_mouse(), set_time(), and Caca::setDisplayTime().

◆ caca_set_display_title()

int caca_set_display_title ( caca_display_t dp,
char const *  title 
)

Set the display title.

If libcaca runs in a window, try to change its title. This works with the ncurses, S-Lang, OpenGL, X11 and Win32 drivers.

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

  • ENOSYS Display driver does not support setting the window title.
Parameters
dpThe libcaca display context.
titleThe desired display title.
Returns
0 upon success, -1 if an error occurred.

Definition at line 40 of file graphics.c.

References dp, drv, caca_display::drv::set_display_title, and seterrno.

Referenced by Java_org_zoy_caca_Display_setDisplayTitle(), main(), set_title(), and Caca::setTitle().

◆ caca_set_mouse()

int caca_set_mouse ( caca_display_t dp,
int  flag 
)

Show or hide the mouse pointer.

Show or hide the mouse pointer. This function works with the ncurses, S-Lang and X11 drivers.

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

  • ENOSYS Display driver does not support hiding the mouse pointer.
Parameters
dpThe libcaca display context.
flag0 hides the pointer, 1 shows the system's default pointer (usually an arrow). Other values are reserved for future use.
Returns
0 upon success, -1 if an error occurred.

Definition at line 243 of file graphics.c.

References dp, drv, caca_display::drv::set_mouse, and seterrno.

Referenced by Java_org_zoy_caca_Display_setDisplayMouse(), and Caca::setMouse().