---
name: "VipsFormat"
section: "3"
platform: "linux"
package: "libvips-dev"
version: "7.20.7-1+b3"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/VipsFormat"
---

# VipsFormat(3)

load and search image formats

## 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)](/im_open/3.md)** 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)](/im_open/3.md)** 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)](/im_open/3.md)** 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)](/vips_format_map/3.md)** maps a function over the list of available formats. See  **im\_slist\_map(3).**

**[vips\_format\_for\_file(3)](/vips_format_for_file/3.md)** 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)](/vips_format_for_name/3.md)** 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)](/vips_format_read/3.md)** 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)](/vips_format_write/3.md)** 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_analyze2vips/3.md)** **[im\_csv2vips(3)](/im_csv2vips/3.md)** **[im\_exr2vips(3)](/im_exr2vips/3.md)** **[im\_jpeg2vips(3)](/im_jpeg2vips/3.md)** **[im\_magick2vips(3)](/im_magick2vips/3.md)** **[im\_png2vips(3)](/im_png2vips/3.md)** **[im\_ppm2vips(3)](/im_ppm2vips/3.md)** **[im\_tiff2vips(3)](/im_tiff2vips/3.md)** **[im\_vips2csv(3)](/im_vips2csv/3.md)** **[im\_vips2jpeg(3)](/im_vips2jpeg/3.md)** **[im\_vips2png(3)](/im_vips2png/3.md)** **[im\_vips2ppm(3)](/im_vips2ppm/3.md)** **[im\_vips2tiff(3)](/im_vips2tiff/3.md)**

You can also load Matlab .mat files and load or save Radiance HDR files. See  **[im\_binfile(3)](/im_binfile/3.md)** and **[im\_raw2vips(3)](/im_raw2vips/3.md)** 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_tiff2vips/3.md), [im\_open(3)](/im_open/3.md), [vips(1)](/vips/1.md).

## AUTHOR

Jesper Friis and John Cupitt