.TH "caca_dirty" 3caca "Mon Mar 25 2024 04:02:10" "Version 0.99.beta20" "libcaca" \" -*- nroff -*-
.ad l
.nh
.SH NAME
caca_dirty \- libcaca dirty rectangle manipulation
.SH SYNOPSIS
.br
.PP
.SS "Modules"

.in +1c
.ti -1c
.RI "\fBlibcaca canvas transformation\fP"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "__extern int \fBcaca_disable_dirty_rect\fP (\fBcaca_canvas_t\fP *)"
.br
.RI "Disable dirty rectangles\&. "
.ti -1c
.RI "__extern int \fBcaca_enable_dirty_rect\fP (\fBcaca_canvas_t\fP *)"
.br
.RI "Enable dirty rectangles\&. "
.ti -1c
.RI "__extern int \fBcaca_get_dirty_rect_count\fP (\fBcaca_canvas_t\fP *)"
.br
.RI "Get the number of dirty rectangles in the canvas\&. "
.ti -1c
.RI "__extern int \fBcaca_get_dirty_rect\fP (\fBcaca_canvas_t\fP *, int, int *, int *, int *, int *)"
.br
.RI "Get a canvas's dirty rectangle\&. "
.ti -1c
.RI "__extern int \fBcaca_add_dirty_rect\fP (\fBcaca_canvas_t\fP *, int, int, int, int)"
.br
.RI "Add an area to the canvas's dirty rectangle list\&. "
.ti -1c
.RI "__extern int \fBcaca_remove_dirty_rect\fP (\fBcaca_canvas_t\fP *, int, int, int, int)"
.br
.RI "Remove an area from the dirty rectangle list\&. "
.ti -1c
.RI "__extern int \fBcaca_clear_dirty_rect_list\fP (\fBcaca_canvas_t\fP *)"
.br
.RI "Clear a canvas's dirty rectangle list\&. "
.in -1c
.SH "Detailed Description"
.PP 
These functions manipulate dirty rectangles for optimised blitting\&. 
.SH "Function Documentation"
.PP 
.SS "__extern int caca_disable_dirty_rect (\fBcaca_canvas_t\fP * cv)"
Disable dirty rectangle handling for all \fIlibcaca\fP graphic calls\&. This is handy when the calling application needs to do slow operations within a known area\&. Just call \fBcaca_add_dirty_rect()\fP afterwards\&.
.PP
This function is recursive\&. Dirty rectangles are only reenabled when \fBcaca_enable_dirty_rect()\fP is called as many times\&.
.PP
This function never fails\&.
.PP
\fBParameters\fP
.RS 4
\fIcv\fP A libcaca canvas\&. 
.RE
.PP
\fBReturns\fP
.RS 4
This function always returns 0\&. 
.RE
.PP

.SS "__extern int caca_enable_dirty_rect (\fBcaca_canvas_t\fP * cv)"
This function can only be called after \fBcaca_disable_dirty_rect()\fP was called\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Dirty rectangles were not disabled\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fIcv\fP A libcaca canvas\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.SS "__extern int caca_get_dirty_rect_count (\fBcaca_canvas_t\fP * cv)"
Get the number of dirty rectangles in a canvas\&. Dirty rectangles are areas that contain cells that have changed since the last reset\&.
.PP
The dirty rectangles are used internally by display drivers to optimise rendering by avoiding to redraw the whole screen\&. Once the display driver has rendered the canvas, it resets the dirty rectangle list\&.
.PP
Dirty rectangles are guaranteed not to overlap\&.
.PP
This function never fails\&.
.PP
\fBParameters\fP
.RS 4
\fIcv\fP A libcaca canvas\&. 
.RE
.PP
\fBReturns\fP
.RS 4
The number of dirty rectangles in the given canvas\&. 
.RE
.PP

.SS "__extern int caca_get_dirty_rect (\fBcaca_canvas_t\fP * cv, int r, int * x, int * y, int * width, int * height)"
Get the canvas's given dirty rectangle coordinates\&. The index must be within the dirty rectangle count\&. See \fBcaca_get_dirty_rect_count()\fP for how to compute this count\&.
.PP
If an error occurs, no coordinates are written in the pointer arguments, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Specified rectangle index is out of bounds\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fIcv\fP A libcaca canvas\&. 
.br
\fIr\fP The requested rectangle index\&. 
.br
\fIx\fP A pointer to an integer where the leftmost edge of the dirty rectangle will be stored\&. 
.br
\fIy\fP A pointer to an integer where the topmost edge of the dirty rectangle will be stored\&. 
.br
\fIwidth\fP A pointer to an integer where the width of the dirty rectangle will be stored\&. 
.br
\fIheight\fP A pointer to an integer where the height of the dirty rectangle will be stored\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.SS "__extern int caca_add_dirty_rect (\fBcaca_canvas_t\fP * cv, int x, int y, int width, int height)"
Add an invalidating zone to the canvas's dirty rectangle list\&. For more information about the dirty rectangles, see \fBcaca_get_dirty_rect()\fP\&.
.PP
This function may be useful to force refresh of a given zone of the canvas even if the dirty rectangle tracking indicates that it is unchanged\&. This may happen if the canvas contents were somewhat directly modified\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Specified rectangle coordinates are out of bounds\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fIcv\fP A libcaca canvas\&. 
.br
\fIx\fP The leftmost edge of the additional dirty rectangle\&. 
.br
\fIy\fP The topmost edge of the additional dirty rectangle\&. 
.br
\fIwidth\fP The width of the additional dirty rectangle\&. 
.br
\fIheight\fP The height of the additional dirty rectangle\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.PP
Referenced by \fBcaca_blit()\fP, \fBcaca_clear_canvas()\fP, \fBcaca_fill_box()\fP, \fBcaca_flip()\fP, \fBcaca_flop()\fP, \fBcaca_free_frame()\fP, \fBcaca_invert()\fP, \fBcaca_put_attr()\fP, \fBcaca_put_char()\fP, \fBcaca_rotate_180()\fP, \fBcaca_rotate_left()\fP, \fBcaca_rotate_right()\fP, \fBcaca_set_canvas_boundaries()\fP, \fBcaca_set_frame()\fP, \fBcaca_stretch_left()\fP, and \fBcaca_stretch_right()\fP\&.
.SS "__extern int caca_remove_dirty_rect (\fBcaca_canvas_t\fP * cv, int x, int y, int width, int height)"
Mark a cell area in the canvas as not dirty\&. For more information about the dirty rectangles, see \fBcaca_get_dirty_rect()\fP\&.
.PP
Values such that \fBxmin\fP > \fBxmax\fP or \fBymin\fP > \fBymax\fP indicate that the dirty rectangle is empty\&. They will be silently ignored\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Specified rectangle coordinates are out of bounds\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fIcv\fP A libcaca canvas\&. 
.br
\fIx\fP The leftmost edge of the clean rectangle\&. 
.br
\fIy\fP The topmost edge of the clean rectangle\&. 
.br
\fIwidth\fP The width of the clean rectangle\&. 
.br
\fIheight\fP The height of the clean rectangle\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 in case of success, -1 if an error occurred\&. 
.RE
.PP

.SS "__extern int caca_clear_dirty_rect_list (\fBcaca_canvas_t\fP * cv)"
Empty the canvas's dirty rectangle list\&.
.PP
This function never fails\&.
.PP
\fBParameters\fP
.RS 4
\fIcv\fP A libcaca canvas\&. 
.RE
.PP
\fBReturns\fP
.RS 4
This function always returns 0\&. 
.RE
.PP

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