.TH "caca_importexport" 3caca "Mon Mar 25 2024 04:02:10" "Version 0.99.beta20" "libcaca" \" -*- nroff -*-
.ad l
.nh
.SH NAME
caca_importexport \- libcaca importers/exporters from/to various
.SH SYNOPSIS
.br
.PP
.SS "Modules"

.in +1c
.ti -1c
.RI "\fBlibcaca display functions\fP"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "__extern ssize_t \fBcaca_import_canvas_from_memory\fP (\fBcaca_canvas_t\fP *, void const *, size_t, char const *)"
.br
.RI "Import a memory buffer into a canvas\&. "
.ti -1c
.RI "__extern ssize_t \fBcaca_import_canvas_from_file\fP (\fBcaca_canvas_t\fP *, char const *, char const *)"
.br
.RI "Import a file into a canvas\&. "
.ti -1c
.RI "__extern ssize_t \fBcaca_import_area_from_memory\fP (\fBcaca_canvas_t\fP *, int, int, void const *, size_t, char const *)"
.br
.RI "Import a memory buffer into a canvas area\&. "
.ti -1c
.RI "__extern ssize_t \fBcaca_import_area_from_file\fP (\fBcaca_canvas_t\fP *, int, int, char const *, char const *)"
.br
.RI "Import a file into a canvas area\&. "
.ti -1c
.RI "__extern char const *const * \fBcaca_get_import_list\fP (void)"
.br
.RI "Get available import formats\&. "
.ti -1c
.RI "__extern void * \fBcaca_export_canvas_to_memory\fP (\fBcaca_canvas_t\fP const *, char const *, size_t *)"
.br
.RI "Export a canvas into a foreign format\&. "
.ti -1c
.RI "__extern void * \fBcaca_export_area_to_memory\fP (\fBcaca_canvas_t\fP const *, int, int, int, int, char const *, size_t *)"
.br
.RI "Export a canvas portion into a foreign format\&. "
.ti -1c
.RI "__extern char const *const * \fBcaca_get_export_list\fP (void)"
.br
.RI "Get available export formats\&. "
.in -1c
.SH "Detailed Description"
.PP 
formats
.PP
These functions import various file formats into a new canvas, or export the current canvas to various text formats\&. 
.SH "Function Documentation"
.PP 
.SS "__extern ssize_t caca_import_canvas_from_memory (\fBcaca_canvas_t\fP * cv, void const * data, size_t len, char const * format)"
Import a memory buffer into the given libcaca canvas's current frame\&. The current frame is resized accordingly and its contents are replaced with the imported data\&.
.PP
Valid values for \fCformat\fP are:
.IP "\(bu" 2
\fC""\fP: attempt to autodetect the file format\&.
.IP "\(bu" 2
\fC"caca"\fP: import native libcaca files\&.
.IP "\(bu" 2
\fC"text"\fP: import ASCII text files\&.
.IP "\(bu" 2
\fC"ansi"\fP: import ANSI files\&.
.IP "\(bu" 2
\fC"utf8"\fP: import UTF-8 files with ANSI colour codes\&.
.IP "\(bu" 2
\fC"bin"\fP: import BIN files\&.
.PP
.PP
The number of bytes read is returned\&. If the file format is valid, but not enough data was available, 0 is returned\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCENOMEM\fP Not enough memory to allocate canvas\&.
.IP "\(bu" 2
\fCEOVERFLOW\fP Importing data caused a value overflow\&.
.IP "\(bu" 2
\fCEINVAL\fP Invalid format requested\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fIcv\fP A libcaca canvas in which to import the file\&. 
.br
\fIdata\fP A memory area containing the data to be loaded into the canvas\&. 
.br
\fIlen\fP The size in bytes of the memory area\&. 
.br
\fIformat\fP A string describing the input format\&. 
.RE
.PP
\fBReturns\fP
.RS 4
The number of bytes read, or 0 if there was not enough data, or -1 if an error occurred\&. 
.RE
.PP

.PP
Referenced by \fBcaca_import_area_from_memory()\fP, and \fBcaca_import_canvas_from_file()\fP\&.
.SS "__extern ssize_t caca_import_canvas_from_file (\fBcaca_canvas_t\fP * cv, char const * filename, char const * format)"
Import a file into the given libcaca canvas's current frame\&. The current frame is resized accordingly and its contents are replaced with the imported data\&.
.PP
Valid values for \fCformat\fP are:
.IP "\(bu" 2
\fC""\fP: attempt to autodetect the file format\&.
.IP "\(bu" 2
\fC"caca"\fP: import native libcaca files\&.
.IP "\(bu" 2
\fC"text"\fP: import ASCII text files\&.
.IP "\(bu" 2
\fC"ansi"\fP: import ANSI files\&.
.IP "\(bu" 2
\fC"utf8"\fP: import UTF-8 files with ANSI colour codes\&.
.IP "\(bu" 2
\fC"bin"\fP: import BIN files\&.
.PP
.PP
The number of bytes read is returned\&. If the file format is valid, but not enough data was available, 0 is returned\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCENOSYS\fP File access is not implemented on this system\&.
.IP "\(bu" 2
\fCENOMEM\fP Not enough memory to allocate canvas\&.
.IP "\(bu" 2
\fCEINVAL\fP Invalid format requested\&. caca_import_file() may also fail and set \fBerrno\fP for any of the errors specified for the routine fopen()\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fIcv\fP A libcaca canvas in which to import the file\&. 
.br
\fIfilename\fP The name of the file to load\&. 
.br
\fIformat\fP A string describing the input format\&. 
.RE
.PP
\fBReturns\fP
.RS 4
The number of bytes read, or 0 if there was not enough data, or -1 if an error occurred\&. 
.RE
.PP

.PP
References \fBcaca_file_close()\fP, \fBcaca_file_eof()\fP, \fBcaca_file_open()\fP, \fBcaca_file_read()\fP, and \fBcaca_import_canvas_from_memory()\fP\&.
.PP
Referenced by \fBcaca_import_area_from_file()\fP\&.
.SS "__extern ssize_t caca_import_area_from_memory (\fBcaca_canvas_t\fP * cv, int x, int y, void const * data, size_t len, char const * format)"
Import a memory buffer into the given libcaca canvas's current frame, at the specified position\&. For more information, see \fBcaca_import_canvas_from_memory()\fP\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Unsupported format requested or invalid coordinates\&.
.IP "\(bu" 2
\fCENOMEM\fP Not enough memory to allocate canvas\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fIcv\fP A libcaca canvas in which to import the file\&. 
.br
\fIx\fP The leftmost coordinate of the area to import to\&. 
.br
\fIy\fP The topmost coordinate of the area to import to\&. 
.br
\fIdata\fP A memory area containing the data to be loaded into the canvas\&. 
.br
\fIlen\fP The size in bytes of the memory area\&. 
.br
\fIformat\fP A string describing the input format\&. 
.RE
.PP
\fBReturns\fP
.RS 4
The number of bytes read, or 0 if there was not enough data, or -1 if an error occurred\&. 
.RE
.PP

.PP
References \fBcaca_blit()\fP, \fBcaca_create_canvas()\fP, \fBcaca_free_canvas()\fP, and \fBcaca_import_canvas_from_memory()\fP\&.
.SS "__extern ssize_t caca_import_area_from_file (\fBcaca_canvas_t\fP * cv, int x, int y, char const * filename, char const * format)"
Import a file into the given libcaca canvas's current frame, at the specified position\&. For more information, see \fBcaca_import_canvas_from_file()\fP\&.
.PP
If an error occurs, -1 is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCENOSYS\fP File access is not implemented on this system\&.
.IP "\(bu" 2
\fCENOMEM\fP Not enough memory to allocate canvas\&.
.IP "\(bu" 2
\fCEINVAL\fP Unsupported format requested or invalid coordinates\&. caca_import_file() may also fail and set \fBerrno\fP for any of the errors specified for the routine fopen()\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fIcv\fP A libcaca canvas in which to import the file\&. 
.br
\fIx\fP The leftmost coordinate of the area to import to\&. 
.br
\fIy\fP The topmost coordinate of the area to import to\&. 
.br
\fIfilename\fP The name of the file to load\&. 
.br
\fIformat\fP A string describing the input format\&. 
.RE
.PP
\fBReturns\fP
.RS 4
The number of bytes read, or 0 if there was not enough data, or -1 if an error occurred\&. 
.RE
.PP

.PP
References \fBcaca_blit()\fP, \fBcaca_create_canvas()\fP, \fBcaca_free_canvas()\fP, and \fBcaca_import_canvas_from_file()\fP\&.
.SS "__extern char const  *const  * caca_get_import_list (void)"
Return a list of available import formats\&. The list is a NULL-terminated array of strings, interleaving a string containing the internal value for the import format, to be used with caca_import_canvas(), and a string containing the natural language description for that import format\&.
.PP
This function never fails\&.
.PP
\fBReturns\fP
.RS 4
An array of strings\&. 
.RE
.PP

.SS "__extern void * caca_export_canvas_to_memory (\fBcaca_canvas_t\fP const * cv, char const * format, size_t * bytes)"
This function exports a libcaca canvas into various foreign formats such as ANSI art, HTML, IRC colours, etc\&. The returned pointer should be passed to free() to release the allocated storage when it is no longer needed\&.
.PP
Valid values for \fCformat\fP are:
.IP "\(bu" 2
\fC"caca"\fP: export native libcaca files\&.
.IP "\(bu" 2
\fC"ansi"\fP: export ANSI art (CP437 charset with ANSI colour codes)\&.
.IP "\(bu" 2
\fC"html"\fP: export an HTML page with CSS information\&.
.IP "\(bu" 2
\fC"html3"\fP: export an HTML table that should be compatible with most navigators, including textmode ones\&.
.IP "\(bu" 2
\fC"irc"\fP: export UTF-8 text with mIRC colour codes\&.
.IP "\(bu" 2
\fC"ps"\fP: export a PostScript document\&.
.IP "\(bu" 2
\fC"svg"\fP: export an SVG vector image\&.
.IP "\(bu" 2
\fC"tga"\fP: export a TGA image\&.
.IP "\(bu" 2
\fC"troff"\fP: export a troff source\&.
.PP
.PP
If an error occurs, NULL is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Unsupported format requested\&.
.IP "\(bu" 2
\fCENOMEM\fP Not enough memory to allocate output buffer\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fIcv\fP A libcaca canvas 
.br
\fIformat\fP A string describing the requested output format\&. 
.br
\fIbytes\fP A pointer to a size_t where the number of allocated bytes will be written\&. 
.RE
.PP
\fBReturns\fP
.RS 4
A pointer to the exported memory area, or NULL in case of error\&. 
.RE
.PP

.PP
Referenced by \fBcaca_export_area_to_memory()\fP\&.
.SS "__extern void * caca_export_area_to_memory (\fBcaca_canvas_t\fP const * cv, int x, int y, int w, int h, char const * format, size_t * bytes)"
This function exports a portion of a \fIlibcaca\fP canvas into various formats\&. For more information, see \fBcaca_export_canvas_to_memory()\fP\&.
.PP
If an error occurs, NULL is returned and \fBerrno\fP is set accordingly:
.IP "\(bu" 2
\fCEINVAL\fP Unsupported format requested or invalid coordinates\&.
.IP "\(bu" 2
\fCENOMEM\fP Not enough memory to allocate output buffer\&.
.PP
.PP
\fBParameters\fP
.RS 4
\fIcv\fP A libcaca canvas 
.br
\fIx\fP The leftmost coordinate of the area to export\&. 
.br
\fIy\fP The topmost coordinate of the area to export\&. 
.br
\fIw\fP The width of the area to export\&. 
.br
\fIh\fP The height of the area to export\&. 
.br
\fIformat\fP A string describing the requested output format\&. 
.br
\fIbytes\fP A pointer to a size_t where the number of allocated bytes will be written\&. 
.RE
.PP
\fBReturns\fP
.RS 4
A pointer to the exported memory area, or NULL in case of error\&. 
.RE
.PP

.PP
References \fBcaca_blit()\fP, \fBcaca_create_canvas()\fP, \fBcaca_export_canvas_to_memory()\fP, and \fBcaca_free_canvas()\fP\&.
.SS "__extern char const  *const  * caca_get_export_list (void)"
Return a list of available export formats\&. The list is a NULL-terminated array of strings, interleaving a string containing the internal value for the export format, to be used with caca_export_memory(), and a string containing the natural language description for that export format\&.
.PP
This function never fails\&.
.PP
\fBReturns\fP
.RS 4
An array of strings\&. 
.RE
.PP

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