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.

AUTHOR

Jesper Friis and John Cupitt