.TH "caca_display" 3caca "Sat Apr 6 2019" "Version 0.99.beta19" "libcaca" \" -*- nroff -*-
.ad l
.nh
.SH NAME
caca_display
.SH SYNOPSIS
.br
.PP
.SS "Functions"

.in +1c
.ti -1c
.RI "__extern \fBcaca_display_t\fP * \fBcaca_create_display\fP (\fBcaca_canvas_t\fP *)"
.br
.RI "Attach a caca graphical context to a caca canvas\&. "
.ti -1c
.RI "__extern \fBcaca_display_t\fP * \fBcaca_create_display_with_driver\fP (\fBcaca_canvas_t\fP *, char const *)"
.br
.RI "Attach a specific caca graphical context to a caca canvas\&. "
.ti -1c
.RI "__extern char const  *const  * \fBcaca_get_display_driver_list\fP (void)"
.br
.RI "Get available display drivers\&. "
.ti -1c
.RI "__extern char const  * \fBcaca_get_display_driver\fP (\fBcaca_display_t\fP *)"
.br
.RI "Return a caca graphical context's current output driver\&. "
.ti -1c
.RI "__extern int \fBcaca_set_display_driver\fP (\fBcaca_display_t\fP *, char const *)"
.br
.RI "Set the output driver\&. "
.ti -1c
.RI "__extern int \fBcaca_free_display\fP (\fBcaca_display_t\fP *)"
.br
.RI "Detach a caca graphical context from a caca backend context\&. "
.ti -1c
.RI "__extern \fBcaca_canvas_t\fP * \fBcaca_get_canvas\fP (\fBcaca_display_t\fP *)"
.br
.RI "Get the canvas attached to a caca graphical context\&. "
.ti -1c
.RI "__extern int \fBcaca_refresh_display\fP (\fBcaca_display_t\fP *)"
.br
.RI "Flush pending changes and redraw the screen\&. "
.ti -1c
.RI "__extern int \fBcaca_set_display_time\fP (\fBcaca_display_t\fP *, int)"
.br
.RI "Set the refresh delay\&. "
.ti -1c
.RI "__extern int \fBcaca_get_display_time\fP (\fBcaca_display_t\fP const *)"
.br
.RI "Get the display's average rendering time\&. "
.ti -1c
.RI "__extern int \fBcaca_get_display_width\fP (\fBcaca_display_t\fP const *)"
.br
.RI "Get the display width\&. "
.ti -1c
.RI "__extern int \fBcaca_get_display_height\fP (\fBcaca_display_t\fP const *)"
.br
.RI "Get the display height\&. "
.ti -1c
.RI "__extern int \fBcaca_set_display_title\fP (\fBcaca_display_t\fP *, char const *)"
.br
.RI "Set the display title\&. "
.ti -1c
.RI "__extern int \fBcaca_set_mouse\fP (\fBcaca_display_t\fP *, int)"
.br
.RI "Show or hide the mouse pointer\&. "
.ti -1c
.RI "__extern int \fBcaca_set_cursor\fP (\fBcaca_display_t\fP *, int)"
.br
.RI "Show or hide the cursor\&. "
.in -1c
.SH "Detailed Description"
.PP 
These functions provide the basic \fIlibcaca\fP routines for display initialisation, system information retrieval and configuration\&. 
.SH "Function Documentation"
.PP 
.SS "__extern \fBcaca_display_t\fP* caca_create_display (\fBcaca_canvas_t\fP * cv)"
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\&.
.PP
If no caca canvas is provided, a new one is created\&. Its handle can be retrieved using \fBcaca_get_canvas()\fP and it is automatically destroyed when \fBcaca_free_display()\fP is called\&.
.PP
See also \fBcaca_create_display_with_driver()\fP\&.
.PP
If an error occurs, NULL is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCENOMEM\fP Not enough memory\&.
.IP "\(bu" 2
\fCENODEV\fP Graphical device could not be initialised\&.
.PP
.PP
\fBParameters:\fP
.RS 4
\fIcv\fP The caca canvas or NULL to create a canvas automatically\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
The caca graphical context or NULL if an error occurred\&. 
.RE
.PP

.PP
References caca_create_display_with_driver()\&.
.PP
Referenced by caca_conio_window()\&.
.SS "__extern \fBcaca_display_t\fP* caca_create_display_with_driver (\fBcaca_canvas_t\fP * cv, char const * driver)"
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\&.
.PP
If no caca canvas is provided, a new one is created\&. Its handle can be retrieved using \fBcaca_get_canvas()\fP and it is automatically destroyed when \fBcaca_free_display()\fP is called\&.
.PP
If no driver name is provided, \fIlibcaca\fP will try to autodetect the best output driver it can\&.
.PP
See also \fBcaca_create_display()\fP\&.
.PP
If an error occurs, NULL is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCENOMEM\fP Not enough memory\&.
.IP "\(bu" 2
\fCENODEV\fP Graphical device could not be initialised\&.
.PP
.PP
\fBParameters:\fP
.RS 4
\fIcv\fP The caca canvas or NULL to create a canvas automatically\&. 
.br
\fIdriver\fP A string describing the desired output driver or NULL to choose the best driver automatically\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
The caca graphical context or NULL if an error occurred\&. 
.RE
.PP

.PP
References caca_create_canvas(), caca_free_canvas(), caca_manage_canvas(), and caca_unmanage_canvas()\&.
.PP
Referenced by caca_create_display()\&.
.SS "__extern char const* const* caca_get_display_driver_list (void)"
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\&.
.PP
This function never fails\&.
.PP
\fBReturns:\fP
.RS 4
An array of strings\&. 
.RE
.PP

.SS "__extern char const* caca_get_display_driver (\fBcaca_display_t\fP * dp)"
Return the given display's current output driver\&.
.PP
This function never fails\&.
.PP
\fBParameters:\fP
.RS 4
\fIdp\fP The caca display\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
A static string\&. 
.RE
.PP

.SS "__extern int caca_set_display_driver (\fBcaca_display_t\fP * dp, char const * driver)"
Dynamically change the given display's output driver\&.
.PP
FIXME: decide what to do in case of failure
.PP
\fBParameters:\fP
.RS 4
\fIdp\fP The caca display\&. 
.br
\fIdriver\fP A string describing the desired output driver or NULL to choose the best driver automatically\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.SS "__extern int caca_free_display (\fBcaca_display_t\fP * dp)"
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\&.
.PP
If the caca canvas was automatically created by \fBcaca_create_display()\fP, it is automatically destroyed and any handle to it becomes invalid\&.
.PP
This function never fails\&.
.PP
\fBParameters:\fP
.RS 4
\fIdp\fP The libcaca graphical context\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
This function always returns 0\&. 
.RE
.PP

.PP
References caca_free_canvas(), and caca_unmanage_canvas()\&.
.PP
Referenced by caca_conio_window()\&.
.SS "__extern \fBcaca_canvas_t\fP* caca_get_canvas (\fBcaca_display_t\fP * dp)"
Return a handle on the \fIcaca_canvas_t\fP object that was either attached or created by \fBcaca_create_display()\fP\&.
.PP
This function never fails\&.
.PP
\fBParameters:\fP
.RS 4
\fIdp\fP The libcaca graphical context\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
The libcaca canvas\&. 
.RE
.PP

.SS "__extern int caca_refresh_display (\fBcaca_display_t\fP * dp)"
Flush all graphical operations and print them to the display device\&. Nothing will show on the screen until this function is called\&.
.PP
If \fBcaca_set_display_time()\fP was called with a non-zero value, \fBcaca_refresh_display()\fP will use that value to achieve constant framerate: if two consecutive calls to \fBcaca_refresh_display()\fP are within a time range shorter than the value set with \fBcaca_set_display_time()\fP, the second call will be delayed before performing the screen refresh\&.
.PP
This function never fails\&.
.PP
\fBParameters:\fP
.RS 4
\fIdp\fP The libcaca display context\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
This function always returns 0\&. 
.RE
.PP

.PP
References caca_clear_dirty_rect_list()\&.
.PP
Referenced by caca_conio_window()\&.
.SS "__extern int caca_set_display_time (\fBcaca_display_t\fP * dp, int usec)"
Set the refresh delay in microseconds\&. The refresh delay is used by \fBcaca_refresh_display()\fP to achieve constant framerate\&. See the \fBcaca_refresh_display()\fP documentation for more details\&.
.PP
If the argument is zero, constant framerate is disabled\&. This is the default behaviour\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Refresh delay value is invalid\&.
.PP
.PP
\fBParameters:\fP
.RS 4
\fIdp\fP The libcaca display context\&. 
.br
\fIusec\fP The refresh delay in microseconds\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 upon success, -1 if an error occurred\&. 
.RE
.PP

.SS "__extern int caca_get_display_time (\fBcaca_display_t\fP const * dp)"
Get the average rendering time, which is the average measured time between two \fBcaca_refresh_display()\fP calls, in microseconds\&. If constant framerate was activated by calling \fBcaca_set_display_time()\fP, the average rendering time will be close to the requested delay even if the real rendering time was shorter\&.
.PP
This function never fails\&.
.PP
\fBParameters:\fP
.RS 4
\fIdp\fP The libcaca display context\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
The render time in microseconds\&. 
.RE
.PP

.SS "__extern int caca_get_display_width (\fBcaca_display_t\fP const * dp)"
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\&.
.PP
This function never fails\&.
.PP
\fBParameters:\fP
.RS 4
\fIdp\fP The libcaca display context\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
The display width\&. 
.RE
.PP

.SS "__extern int caca_get_display_height (\fBcaca_display_t\fP const * dp)"
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\&.
.PP
This function never fails\&.
.PP
\fBParameters:\fP
.RS 4
\fIdp\fP The libcaca display context\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
The display height\&. 
.RE
.PP

.SS "__extern int caca_set_display_title (\fBcaca_display_t\fP * dp, char const * title)"
If libcaca runs in a window, try to change its title\&. This works with the ncurses, S-Lang, OpenGL, X11 and Win32 drivers\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCENOSYS\fP Display driver does not support setting the window title\&.
.PP
.PP
\fBParameters:\fP
.RS 4
\fIdp\fP The libcaca display context\&. 
.br
\fItitle\fP The desired display title\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 upon success, -1 if an error occurred\&. 
.RE
.PP

.SS "__extern int caca_set_mouse (\fBcaca_display_t\fP * dp, int flag)"
Show or hide the mouse pointer\&. This function works with the ncurses, S-Lang and X11 drivers\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCENOSYS\fP Display driver does not support hiding the mouse pointer\&.
.PP
.PP
\fBParameters:\fP
.RS 4
\fIdp\fP The libcaca display context\&. 
.br
\fIflag\fP 0 hides the pointer, 1 shows the system's default pointer (usually an arrow)\&. Other values are reserved for future use\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 upon success, -1 if an error occurred\&. 
.RE
.PP

.PP
References caca_get_canvas_height(), caca_get_canvas_width(), and caca_set_canvas_size()\&.
.SS "__extern int caca_set_cursor (\fBcaca_display_t\fP * dp, int flag)"
Show or hide the cursor, for devices that support such a feature\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCENOSYS\fP Display driver does not support showing the cursor\&.
.PP
.PP
\fBParameters:\fP
.RS 4
\fIdp\fP The libcaca display context\&. 
.br
\fIflag\fP 0 hides the cursor, 1 shows the system's default cursor (usually a white rectangle)\&. Other values are reserved for future use\&. 
.RE
.PP
\fBReturns:\fP
.RS 4
0 upon success, -1 if an error occurred\&. 
.RE
.PP

.PP
Referenced by caca_conio_window()\&.
.SH "Author"
.PP 
Generated automatically by Doxygen for libcaca from the source code\&.