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 dirty rectangle manipulation

These functions manipulate dirty rectangles for optimised blitting. More...

Functions

int caca_disable_dirty_rect (caca_canvas_t *)
 Disable dirty rectangles. More...
 
int caca_enable_dirty_rect (caca_canvas_t *)
 Enable dirty rectangles. More...
 
int caca_get_dirty_rect_count (caca_canvas_t *)
 Get the number of dirty rectangles in the canvas. More...
 
int caca_get_dirty_rect (caca_canvas_t *, int, int *, int *, int *, int *)
 Get a canvas's dirty rectangle. More...
 
int caca_add_dirty_rect (caca_canvas_t *, int, int, int, int)
 Add an area to the canvas's dirty rectangle list. More...
 
int caca_remove_dirty_rect (caca_canvas_t *, int, int, int, int)
 Remove an area from the dirty rectangle list. More...
 
int caca_clear_dirty_rect_list (caca_canvas_t *)
 Clear a canvas's dirty rectangle list. More...
 

Detailed Description

These functions manipulate dirty rectangles for optimised blitting.

Function Documentation

◆ caca_add_dirty_rect()

int caca_add_dirty_rect ( caca_canvas_t cv,
int  x,
int  y,
int  width,
int  height 
)

Add an area to the canvas's dirty rectangle list.

Add an invalidating zone to the canvas's dirty rectangle list. For more information about the dirty rectangles, see caca_get_dirty_rect().

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.

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

  • EINVAL Specified rectangle coordinates are out of bounds.
Parameters
cvA libcaca canvas.
xThe leftmost edge of the additional dirty rectangle.
yThe topmost edge of the additional dirty rectangle.
widthThe width of the additional dirty rectangle.
heightThe height of the additional dirty rectangle.
Returns
0 in case of success, -1 if an error occurred.

Definition at line 164 of file dirty.c.

References cv, debug, caca_canvas::dirty, caca_canvas::height, merge_new_rect(), caca_canvas::ndirty, seterrno, caca_canvas::width, x, caca_canvas::xmax, caca_canvas::xmin, y, caca_canvas::ymax, and caca_canvas::ymin.

Referenced by add_dirty_rect(), caca_blit(), caca_clear_canvas(), caca_fill_box(), caca_flip(), caca_flop(), caca_free_frame(), caca_invert(), caca_put_attr(), caca_put_char(), caca_resize(), caca_rotate_180(), caca_rotate_left(), caca_rotate_right(), caca_set_canvas_boundaries(), caca_set_frame(), caca_stretch_left(), and caca_stretch_right().

◆ caca_clear_dirty_rect_list()

int caca_clear_dirty_rect_list ( caca_canvas_t cv)

Clear a canvas's dirty rectangle list.

Empty the canvas's dirty rectangle list.

This function never fails.

Parameters
cvA libcaca canvas.
Returns
This function always returns 0.

Definition at line 256 of file dirty.c.

References cv, and caca_canvas::ndirty.

Referenced by caca_refresh_display().

◆ caca_disable_dirty_rect()

int caca_disable_dirty_rect ( caca_canvas_t cv)

Disable dirty rectangles.

Disable dirty rectangle handling for all libcaca graphic calls. This is handy when the calling application needs to do slow operations within a known area. Just call caca_add_dirty_rect() afterwards.

This function is recursive. Dirty rectangles are only reenabled when caca_enable_dirty_rect() is called as many times.

This function never fails.

Parameters
cvA libcaca canvas.
Returns
This function always returns 0.

Definition at line 51 of file dirty.c.

References cv, and caca_canvas::dirty_disabled.

◆ caca_enable_dirty_rect()

int caca_enable_dirty_rect ( caca_canvas_t cv)

Enable dirty rectangles.

This function can only be called after caca_disable_dirty_rect() was called.

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

  • EINVAL Dirty rectangles were not disabled.
Parameters
cvA libcaca canvas.
Returns
0 in case of success, -1 if an error occurred.

Definition at line 69 of file dirty.c.

References cv, caca_canvas::dirty_disabled, and seterrno.

◆ caca_get_dirty_rect()

int caca_get_dirty_rect ( caca_canvas_t cv,
int  r,
int *  x,
int *  y,
int *  width,
int *  height 
)

Get a canvas's dirty rectangle.

Get the canvas's given dirty rectangle coordinates. The index must be within the dirty rectangle count. See caca_get_dirty_rect_count() for how to compute this count.

If an error occurs, no coordinates are written in the pointer arguments, -1 is returned and errno is set accordingly:

  • EINVAL Specified rectangle index is out of bounds.
Parameters
cvA libcaca canvas.
rThe requested rectangle index.
xA pointer to an integer where the leftmost edge of the dirty rectangle will be stored.
yA pointer to an integer where the topmost edge of the dirty rectangle will be stored.
widthA pointer to an integer where the width of the dirty rectangle will be stored.
heightA pointer to an integer where the height of the dirty rectangle will be stored.
Returns
0 in case of success, -1 if an error occurred.

Definition at line 125 of file dirty.c.

References cv, debug, caca_canvas::dirty, caca_canvas::ndirty, seterrno, x, caca_canvas::xmax, caca_canvas::xmin, y, caca_canvas::ymax, and caca_canvas::ymin.

Referenced by dirty_rect().

◆ caca_get_dirty_rect_count()

int caca_get_dirty_rect_count ( caca_canvas_t cv)

Get the number of dirty rectangles in the canvas.

Get the number of dirty rectangles in a canvas. Dirty rectangles are areas that contain cells that have changed since the last reset.

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.

Dirty rectangles are guaranteed not to overlap.

This function never fails.

Parameters
cvA libcaca canvas.
Returns
The number of dirty rectangles in the given canvas.

Definition at line 98 of file dirty.c.

References cv, and caca_canvas::ndirty.

Referenced by dirty_rects().

◆ caca_remove_dirty_rect()

int caca_remove_dirty_rect ( caca_canvas_t cv,
int  x,
int  y,
int  width,
int  height 
)

Remove an area from the dirty rectangle list.

Mark a cell area in the canvas as not dirty. For more information about the dirty rectangles, see caca_get_dirty_rect().

Values such that xmin > xmax or ymin > ymax indicate that the dirty rectangle is empty. They will be silently ignored.

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

  • EINVAL Specified rectangle coordinates are out of bounds.
Parameters
cvA libcaca canvas.
xThe leftmost edge of the clean rectangle.
yThe topmost edge of the clean rectangle.
widthThe width of the clean rectangle.
heightThe height of the clean rectangle.
Returns
0 in case of success, -1 if an error occurred.

Definition at line 219 of file dirty.c.

References cv, caca_canvas::height, seterrno, caca_canvas::width, x, and y.

Referenced by remove_dirty_rect().