libvips/man/VipsFormat.3

180 lines
4.8 KiB
Groff
Raw Normal View History

.TH VIPS_FORMAT 3 "16 August 2008"
2008-08-16 20:59:26 +02:00
.SH NAME
VipsFormat,
vips_format_map, vips_format_for_file, vips_format_for_name,
vips_format_write \-
2008-08-16 20:59:26 +02:00
load and search image formats
.SH SYNOPSIS
#include <vips/vips.h>
typedef enum {
.br
2008-11-28 22:26:23 +01:00
VIPS_FORMAT_NONE = 0,
2008-08-16 20:59:26 +02:00
.br
2008-11-28 22:26:23 +01:00
VIPS_FORMAT_PARTIAL = 1
2008-08-16 20:59:26 +02:00
.br
} VipsFormatFlags;
2008-08-16 20:59:26 +02:00
2008-11-28 22:26:23 +01:00
typedef struct _VipsFormatClass {
.br
VipsObjectClass parent_class;
gboolean (*is_a)( const char * );
.br
int (*header)( const char *, IMAGE * );
.br
int (*load)( const char *, IMAGE * );
.br
int (*save)( IMAGE *, const char * );
.br
VipsFormatFlags (*get_flags)( const char * );
.br
int priority;
.br
const char **suffs;
.br
} VipsFormatClass;
void *vips_format_map( VSListMap2Fn fn, void *a, void *b );
2008-08-16 20:59:26 +02:00
.br
VipsFormatClass *vips_format_for_file( const char *filename );
2008-08-16 20:59:26 +02:00
.br
VipsFormatClass *vips_format_for_name( const char *filename );
2008-08-16 20:59:26 +02:00
2008-11-28 22:26:23 +01:00
int vips_format_write( IMAGE *im, const char *filename );
2008-10-11 23:29:16 +02:00
2008-11-28 22:26:23 +01:00
int vips_format_read( const char *filename, IMAGE *out );
2008-10-11 23:29:16 +02:00
2008-08-16 20:59:26 +02:00
.SH DESCRIPTION
2008-11-28 22:26:23 +01:00
These functions search the
2008-08-16 20:59:26 +02:00
available image formats to find one suitable for loading or saving a file.
2008-10-11 23:29:16 +02:00
.B im_open(3)
will do something similar, but that returns a descriptor to the file rather
than copying to a descriptor you supply.
The two APIs are useful in different circumstances:
.B im_open(3)
is good if you want to directly manipulate a file on disc, for example with
2008-11-28 22:26:23 +01:00
the paintbox functions. On the other hand, this format API is useful for
controlling how a image
2008-10-11 23:29:16 +02:00
is unpacked, since you can specify a destination for the copy.
2008-11-28 22:26:23 +01:00
Image formats are subclasses of
.B VipsFormat
as outlined above. They are expected to implement at least one of the methods.
They should also set values for the
.B nickname
and
.B description
members of
.B VipsObject.
2008-08-16 20:59:26 +02:00
2008-11-28 22:26:23 +01:00
Other members are:
2008-08-16 20:59:26 +02:00
2008-11-28 22:26:23 +01:00
.B is_a()
2008-08-16 20:59:26 +02:00
A function which tests whether a file is of the specified format. This is
useful if you can guess a file type from the first few bytes in the file. If
you leave this function NULL, vips will guess from the filename suffix for
you.
2008-11-28 22:26:23 +01:00
.B header()
2008-08-16 20:59:26 +02:00
Load only the image header, not any of the image pixels. vips will call this
first on
.B im_open(3)
and delay loading pixels until asked. If you leave this NULL, vips will just
use the
2009-03-28 18:32:53 +01:00
.B load()
2008-08-16 20:59:26 +02:00
function.
2008-11-28 22:26:23 +01:00
.B load()
2008-08-16 20:59:26 +02:00
Load the image from the file into the IMAGE. You can leave this function NULL
if you only have a
2008-11-28 22:26:23 +01:00
.B save()
2009-03-28 18:32:53 +01:00
method implemented. Load options may be embedded in the filename, see the
loaders below.
2008-08-16 20:59:26 +02:00
2008-11-28 22:26:23 +01:00
.B save()
2008-08-16 20:59:26 +02:00
Write from the IMAGE to the file in this format. You can leave this function
2009-03-28 18:32:53 +01:00
NULL if you only have a load method implemented. Save options may be embedded
in the filename, see the savers below.
2008-08-16 20:59:26 +02:00
2008-11-28 22:26:23 +01:00
.B get_flags()
A function which examines the file and sets various flags to indicate
2008-08-16 20:59:26 +02:00
properties of the image. The only flag implemented at the moment is
2008-11-28 22:26:23 +01:00
.B VIPS_FORMAT_PARTIAL
2008-08-16 20:59:26 +02:00
which may be set to indicate that the file can be read lazily.
2008-11-28 22:26:23 +01:00
.B priority
2008-08-16 20:59:26 +02:00
sets a priority for the format. Priorities for formats default to zero: you
mmay set a lower or higher number to set where in the format table your format
is positioned.
2008-11-28 22:26:23 +01:00
.B suffs
A NULL-terminated array of possible file-name suffixes for this format. This
list is used to filter filenames when they are shown to the user, and to help
select a format to sav a file as. For example, the JPEG format has the
suffixes:
.B { ".jpg", ".jpeg", ".jpe", NULL }
2008-08-16 20:59:26 +02:00
2008-11-28 22:26:23 +01:00
.B vips_format_map(3)
maps a function over the list of available formats. See
2008-08-16 20:59:26 +02:00
.B im_slist_map(3).
2008-11-28 22:26:23 +01:00
.B vips_format_for_file(3)
2008-10-11 23:29:16 +02:00
looks at a file on disc and selects the 'best' format to use to load that
file. If no suitable format is found, it returns NULL and sets an error
message.
2008-08-16 20:59:26 +02:00
2008-11-28 22:26:23 +01:00
.B vips_format_for_name(3)
2008-08-16 20:59:26 +02:00
looks at a filename and picks a format to use to save that file based on the
2008-10-11 23:29:16 +02:00
file extension. If no suitable format is found, it returns NULL and sets an
error message.
2008-11-28 22:26:23 +01:00
.B vips_format_read(3)
2008-10-11 23:29:16 +02:00
is a convenience function which copies the image from the file into the IMAGE.
error, it returns non-zero and sets an error message.
2008-11-28 22:26:23 +01:00
.B vips_format_write(3)
2008-10-11 23:29:16 +02:00
is a convenience function which copies the image to the file in the
appropriate format. On error, it returns non-zero and sets an error message.
2008-08-16 20:59:26 +02:00
2009-03-28 18:32:53 +01:00
.SH SUPPORTED FORMATS
See the following manpages for details on each of the converters and the
options they implement.
.B im_analyze2vips(3)
.B im_csv2vips(3)
.B im_exr2vips(3)
.B im_jpeg2vips(3)
.B im_magick2vips(3)
.B im_png2vips(3)
.B im_ppm2vips(3)
.B im_tiff2vips(3)
.B im_vips2csv(3)
.B im_vips2jpeg(3)
.B im_vips2png(3)
.B im_vips2ppm(3)
.B im_vips2tiff(3)
You can also load Matlab .mat files and load or save Radiance HDR files. See
.B im_binfile(3)
and
.B im_raw2vips(3)
for RAW file read.
2009-03-30 15:34:50 +02:00
You can list the supported formats with
$ vips --list classes
look for subclasses of
.B VipsFormat.
2008-08-16 20:59:26 +02:00
.SH RETURN VALUE
The functions return 0 success and -1 on error.
.SH SEE ALSO
2009-03-30 15:34:50 +02:00
im_tiff2vips(3), im_open(3), vips(1).
2008-08-16 20:59:26 +02:00
.SH AUTHOR
Jesper Friis and John Cupitt