caca_set_canvas_boundaries(3)

libcaca canvas drawing(3caca)       libcaca      libcaca canvas drawing(3caca)



NAME
       libcaca canvas drawing -

   Defines
       #define CACA_MAGIC_FULLWIDTH   0x000ffffe

   Functions
       __extern int caca_gotoxy (caca_canvas_t *, int, int)
           Set cursor position.
       __extern int caca_get_cursor_x (caca_canvas_t const *)
           Get X cursor position.
       __extern int caca_get_cursor_y (caca_canvas_t const *)
           Get Y cursor position.
       __extern int caca_put_char (caca_canvas_t *, int, int, uint32_t)
           Print an ASCII or Unicode character.
       __extern uint32_t caca_get_char (caca_canvas_t const *, int, int)
           Get the Unicode character at the given coordinates.
       __extern int caca_put_str (caca_canvas_t *, int, int, char const *)
           Print a string.
       __extern int caca_printf (caca_canvas_t *, int, int, char const *,...)
           Print a formated string.
       __extern int caca_clear_canvas (caca_canvas_t *)
           Clear the canvas.
       __extern int caca_set_canvas_handle (caca_canvas_t *, int, int)
           Set cursor handle.
       __extern int caca_get_canvas_handle_x (caca_canvas_t const *)
           Get X handle position.
       __extern int caca_get_canvas_handle_y (caca_canvas_t const *)
           Get Y handle position.
       __extern int caca_blit (caca_canvas_t *, int, int, caca_canvas_t const
           *, caca_canvas_t const *)
           Blit a canvas onto another one.
       __extern int caca_set_canvas_boundaries (caca_canvas_t *, int, int,
           int, int)
           Set a canvas' new boundaries.

Detailed Description
       These functions provide low-level character printing routines and
       higher level graphics functions.

Define Documentation
   #define CACA_MAGIC_FULLWIDTH   0x000ffffe Used to indicate that the
       previous character was a fullwidth glyph.
       Referenced by caca_blit(), caca_flip(), caca_put_attr(),
       caca_put_char(), and caca_rotate_180().

Function Documentation
   __extern int caca_gotoxy (caca_canvas_t * cv, int x, int y) Put the cursor
       at the given coordinates. Functions making use of the cursor will use
       the new values. Setting the cursor position outside the canvas is legal
       but the cursor will not be shown.
       This function never fails.

       Parameters:
           cv A handle to the libcaca canvas.
           x X cursor coordinate.
           y Y cursor coordinate.

       Returns:
           This function always returns 0.

   __extern int caca_get_cursor_x (caca_canvas_t const * cv) Retrieve the X
       coordinate of the cursor's position.
       This function never fails.

       Parameters:
           cv A handle to the libcaca canvas.

       Returns:
           The cursor's X coordinate.

   __extern int caca_get_cursor_y (caca_canvas_t const * cv) Retrieve the Y
       coordinate of the cursor's position.
       This function never fails.

       Parameters:
           cv A handle to the libcaca canvas.

       Returns:
           The cursor's Y coordinate.

   __extern int caca_put_char (caca_canvas_t * cv, int x, int y, uint32_t ch)
       Print an ASCII or Unicode character at the given coordinates, using the
       default foreground and background colour values.
       If the coordinates are outside the canvas boundaries, nothing is
       printed. If a fullwidth Unicode character gets overwritten, its
       remaining visible parts are replaced with spaces. If the canvas'
       boundaries would split the fullwidth character in two, a space is
       printed instead.

       The behaviour when printing non-printable characters or invalid UTF-32
       characters is undefined. To print a sequence of bytes forming an UTF-8
       character instead of an UTF-32 character, use the caca_put_str()
       function.

       This function never fails.

       Parameters:
           cv A handle to the libcaca canvas.
           x X coordinate.
           y Y coordinate.
           ch The character to print.

       Returns:
           This function always returns 0.

       References CACA_MAGIC_FULLWIDTH, and caca_utf32_is_fullwidth().

       Referenced by caca_dither_bitmap(), caca_draw_cp437_box(),
       caca_draw_thin_box(), caca_fill_box(), caca_fill_triangle(), and
       caca_put_str().

   __extern uint32_t caca_get_char (caca_canvas_t const * cv, int x, int y)
       Get the ASCII or Unicode value of the character at the given
       coordinates. If the value is less or equal to 127 (0x7f), the character
       can be printed as ASCII. Otherise, it must be handled as a UTF-32
       value.
       If the coordinates are outside the canvas boundaries, a space (0x20) is
       returned.

       A special exception is when CACA_MAGIC_FULLWIDTH is returned. This
       value is guaranteed not to be a valid Unicode character, and indicates
       that the character at the left of the requested one is a fullwidth
       character.

       This function never fails.

       Parameters:
           cv A handle to the libcaca canvas.
           x X coordinate.
           y Y coordinate.

       Returns:
           This function always returns 0.

   __extern int caca_put_str (caca_canvas_t * cv, int x, int y, char const *
       s) Print an UTF-8 string at the given coordinates, using the default
       foreground and background values. The coordinates may be outside the
       canvas boundaries (eg. a negative Y coordinate) and the string will be
       cropped accordingly if it is too long.
       See caca_put_char() for more information on how fullwidth characters
       are handled when overwriting each other or at the canvas' boundaries.

       This function never fails.

       Parameters:
           cv A handle to the libcaca canvas.
           x X coordinate.
           y Y coordinate.
           s The string to print.

       Returns:
           This function always returns 0.

       References caca_put_char(), caca_utf32_is_fullwidth(), and
       caca_utf8_to_utf32().

       Referenced by caca_printf().

   __extern int caca_printf (caca_canvas_t * cv, int x, int y, char const *
       format,  ...) Format a string at the given coordinates, using the
       default foreground and background values. The coordinates may be
       outside the canvas boundaries (eg. a negative Y coordinate) and the
       string will be cropped accordingly if it is too long. The syntax of the
       format string is the same as for the C printf() function.
       This function never fails.

       Parameters:
           cv A handle to the libcaca canvas.
           x X coordinate.
           y Y coordinate.
           format The format string to print.
           ... Arguments to the format string.

       Returns:
           This function always returns 0.

       References caca_put_str().

   __extern int caca_clear_canvas (caca_canvas_t * cv) Clear the canvas using
       the current foreground and background colours.
       This function never fails.

       Parameters:
           cv The canvas to clear.

       Returns:
           This function always returns 0.

   __extern int caca_set_canvas_handle (caca_canvas_t * cv, int x, int y) Set
       the canvas' handle. Blitting functions will use the handle value to put
       the canvas at the proper coordinates.
       This function never fails.

       Parameters:
           cv A handle to the libcaca canvas.
           x X handle coordinate.
           y Y handle coordinate.

       Returns:
           This function always returns 0.

   __extern int caca_get_canvas_handle_x (caca_canvas_t const * cv) Retrieve
       the X coordinate of the canvas' handle.
       This function never fails.

       Parameters:
           cv A handle to the libcaca canvas.

       Returns:
           The canvas' handle's X coordinate.

   __extern int caca_get_canvas_handle_y (caca_canvas_t const * cv) Retrieve
       the Y coordinate of the canvas' handle.
       This function never fails.

       Parameters:
           cv A handle to the libcaca canvas.

       Returns:
           The canvas' handle's Y coordinate.

   __extern int caca_blit (caca_canvas_t * dst, int x, int y, caca_canvas_t
       const * src, caca_canvas_t const * mask) Blit a canvas onto another one
       at the given coordinates. An optional mask canvas can be used.
       If an error occurs, -1 is returned and errno is set accordingly:

       · EINVAL A mask was specified but the mask size and source canvas size
         do not match.

       Parameters:
           dst The destination canvas.
           x X coordinate.
           y Y coordinate.
           src The source canvas.
           mask The mask canvas.

       Returns:
           0 in case of success, -1 if an error occurred.

       References CACA_MAGIC_FULLWIDTH.

       Referenced by caca_set_canvas_boundaries().

   __extern int caca_set_canvas_boundaries (caca_canvas_t * cv, int x, int y,
       int w, int h) Set new boundaries for a canvas. This function can be
       used to crop a canvas, to expand it or for combinations of both
       actions. All frames are affected by this function.
       If an error occurs, -1 is returned and errno is set accordingly:

       · EINVAL Specified width or height is invalid.

       · EBUSY The canvas is in use by a display driver and cannot be resized.

       · ENOMEM Not enough memory for the requested canvas size. If this
         happens, the canvas handle becomes invalid and should not be used.

       Parameters:
           cv The canvas to crop.
           x X coordinate of the top-left corner.
           y Y coordinate of the top-left corner.
           w The width of the cropped area.
           h The height of the cropped area.

       Returns:
           0 in case of success, -1 if an error occurred.

       References caca_blit(), caca_create_canvas(), caca_create_frame(),
       caca_get_frame_count(), and caca_set_frame().

Author
       Generated automatically by Doxygen for libcaca from the source code.



Version 0.99.beta16               5 Jan 2010     libcaca canvas drawing(3caca)