NAME
VipsFormat, vips_format_map, vips_format_for_file,
vips_format_for_name, vips_format_write - load and search image formats
SYNOPSIS
#include <vips/vips.h>
typedef enum {
VIPS_FORMAT_NONE = 0,
VIPS_FORMAT_PARTIAL = 1
} VipsFormatFlags;
typedef struct _VipsFormatClass {
VipsObjectClass parent_class;
gboolean (*is_a)( const char * );
int (*header)( const char *, IMAGE * );
int (*load)( const char *, IMAGE * );
int (*save)( IMAGE *, const char * );
VipsFormatFlags (*get_flags)( const char * );
int priority;
const char **suffs;
} VipsFormatClass;
void *vips_format_map( VSListMap2Fn fn, void *a, void *b );
VipsFormatClass *vips_format_for_file( const char *filename );
VipsFormatClass *vips_format_for_name( const char *filename );
int vips_format_write( IMAGE *im, const char *filename );
int vips_format_read( const char *filename, IMAGE *out );
DESCRIPTION
These functions search the available image formats to find one suitable
for loading or saving a file.
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: im_open(3) is good
if you want to directly manipulate a file on disc, for example with the
paintbox functions. On the other hand, this format API is useful for
controlling how a image is unpacked, since you can specify a
destination for the copy.
Image formats are subclasses of VipsFormat as outlined above. They are
expected to implement at least one of the methods. They should also
set values for the nickname and description members of VipsObject.
Other members are:
is_a() 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.
header() Load only the image header, not any of the image pixels. vips
will call this first on im_open(3) and delay loading pixels until
asked. If you leave this NULL, vips will just use the load() function.
load() Load the image from the file into the IMAGE. You can leave this
function NULL if you only have a save() method implemented. Load
options may be embedded in the filename, see the loaders below.
save() Write from the IMAGE to the file in this format. You can leave
this function NULL if you only have a load method implemented. Save
options may be embedded in the filename, see the savers below.
get_flags() A function which examines the file and sets various flags
to indicate properties of the image. The only flag implemented at the
moment is VIPS_FORMAT_PARTIAL which may be set to indicate that the
file can be read lazily.
priority 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.
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: { .jpg , .jpeg , .jpe , NULL }
vips_format_map(3) maps a function over the list of available formats.
See im_slist_map(3).
vips_format_for_file(3) 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.
vips_format_for_name(3) looks at a filename and picks a format to use
to save that file based on the file extension. If no suitable format is
found, it returns NULL and sets an error message.
vips_format_read(3) is a convenience function which copies the image
from the file into the IMAGE. error, it returns non-zero and sets an
error message.
vips_format_write(3) 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.
SUPPORTED FORMATS
See the following manpages for details on each of the converters and
the options they implement.
im_analyze2vips(3) im_csv2vips(3) im_exr2vips(3) im_jpeg2vips(3)
im_magick2vips(3) im_png2vips(3) im_ppm2vips(3) im_tiff2vips(3)
im_vips2csv(3) im_vips2jpeg(3) im_vips2png(3) im_vips2ppm(3)
im_vips2tiff(3)
You can also load Matlab .mat files and load or save Radiance HDR
files. See im_binfile(3) and im_raw2vips(3) for RAW file read.
You can list the supported formats with
$ vips --list classes
look for subclasses of VipsFormat.
RETURN VALUE
The functions return 0 success and -1 on error.
SEE ALSO
im_tiff2vips(3), im_open(3), vips(1).
AUTHOR
Jesper Friis and John Cupitt
16 August 2008 VIPS_FORMAT(3)