.TH "caca_frame" 3caca "Sun Sep 3 2023 20:34:35" "Version 0.99.beta20" "libcaca" \" -*- nroff -*-
.ad l
.nh
.SH NAME
caca_frame \- libcaca canvas frame handling
.SH SYNOPSIS
.br
.PP
.SS "Modules"

.in +1c
.ti -1c
.RI "\fBlibcaca bitmap dithering\fP"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "__extern int \fBcaca_get_frame_count\fP (\fBcaca_canvas_t\fP const *)"
.br
.RI "Get the number of frames in a canvas\&. "
.ti -1c
.RI "__extern int \fBcaca_set_frame\fP (\fBcaca_canvas_t\fP *, int)"
.br
.RI "Activate a given canvas frame\&. "
.ti -1c
.RI "__extern char const * \fBcaca_get_frame_name\fP (\fBcaca_canvas_t\fP const *)"
.br
.RI "Get the current frame's name\&. "
.ti -1c
.RI "__extern int \fBcaca_set_frame_name\fP (\fBcaca_canvas_t\fP *, char const *)"
.br
.RI "Set the current frame's name\&. "
.ti -1c
.RI "__extern int \fBcaca_create_frame\fP (\fBcaca_canvas_t\fP *, int)"
.br
.RI "Add a frame to a canvas\&. "
.ti -1c
.RI "__extern int \fBcaca_free_frame\fP (\fBcaca_canvas_t\fP *, int)"
.br
.RI "Remove a frame from a canvas\&. "
.in -1c
.SH "Detailed Description"
.PP 
These functions provide high level routines for canvas frame insertion, removal, copying etc\&. 
.SH "Function Documentation"
.PP 
.SS "__extern int caca_get_frame_count (\fBcaca_canvas_t\fP const * cv)"
Return the current canvas' frame count\&.
.PP
This function never fails\&.
.PP
\fBParameters\fP
.RS 4
\fIcv\fP A libcaca canvas 
.RE
.PP
\fBReturns\fP
.RS 4
The frame count 
.RE
.PP

.PP
Referenced by \fBcaca_set_canvas_boundaries()\fP\&.
.SS "__extern int caca_set_frame (\fBcaca_canvas_t\fP * cv, int id)"
Set the active canvas frame\&. All subsequent drawing operations will be performed on that frame\&. The current painting context set by \fBcaca_set_attr()\fP is inherited\&.
.PP
If the frame index is outside the canvas' frame range, nothing happens\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Requested frame is out of range\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fIcv\fP A libcaca canvas 
.br
\fIid\fP The canvas frame to activate 
.RE
.PP
\fBReturns\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.PP
References \fBcaca_add_dirty_rect()\fP\&.
.PP
Referenced by \fBcaca_set_canvas_boundaries()\fP\&.
.SS "__extern char const  * caca_get_frame_name (\fBcaca_canvas_t\fP const * cv)"
Return the current frame's name\&. The returned string is valid until the frame is deleted or \fBcaca_set_frame_name()\fP is called to change the frame name again\&.
.PP
This function never fails\&.
.PP
\fBParameters\fP
.RS 4
\fIcv\fP A libcaca canvas\&. 
.RE
.PP
\fBReturns\fP
.RS 4
The current frame's name\&. 
.RE
.PP

.SS "__extern int caca_set_frame_name (\fBcaca_canvas_t\fP * cv, char const * name)"
Set the current frame's name\&. Upon creation, a frame has a default name of \fC'frame#xxxxxxxx'\fP where \fCxxxxxxxx\fP is a self-incrementing hexadecimal number\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCENOMEM\fP Not enough memory to allocate new frame\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fIcv\fP A libcaca canvas\&. 
.br
\fIname\fP The name to give to the current frame\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.SS "__extern int caca_create_frame (\fBcaca_canvas_t\fP * cv, int id)"
Create a new frame within the given canvas\&. Its contents and attributes are copied from the currently active frame\&.
.PP
The frame index indicates where the frame should be inserted\&. Valid values range from 0 to the current canvas frame count\&. If the frame index is greater than or equals the current canvas frame count, the new frame is appended at the end of the canvas\&. If the frame index is less than zero, the new frame is inserted at index 0\&.
.PP
The active frame does not change, but its index may be renumbered due to the insertion\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCENOMEM\fP Not enough memory to allocate new frame\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fIcv\fP A libcaca canvas 
.br
\fIid\fP The index where to insert the new frame 
.RE
.PP
\fBReturns\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.PP
Referenced by \fBcaca_set_canvas_boundaries()\fP\&.
.SS "__extern int caca_free_frame (\fBcaca_canvas_t\fP * cv, int id)"
Delete a frame from a given canvas\&.
.PP
The frame index indicates the frame to delete\&. Valid values range from 0 to the current canvas frame count minus 1\&. If the frame index is greater than or equals the current canvas frame count, the last frame is deleted\&.
.PP
If the active frame is deleted, frame 0 becomes the new active frame\&. Otherwise, the active frame does not change, but its index may be renumbered due to the deletion\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Requested frame is out of range, or attempt to delete the last frame of the canvas\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fIcv\fP A libcaca canvas 
.br
\fIid\fP The index of the frame to delete 
.RE
.PP
\fBReturns\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.PP
References \fBcaca_add_dirty_rect()\fP\&.
.SH "Author"
.PP 
Generated automatically by Doxygen for libcaca from the source code\&.