2.4 Image formats

VIPS has a simple system for adding support for new image file formats. You can register a new format and it will automatically be supported by all the VIPS interfaces. You can ask VIPS to find a format to load a file with, or to select a image file writer based on a filename. Convenience functions copy a file to an IMAGE, or an IMAGE to a file.

This is a parallel API to im_open(), see §2.2.4. The format system is useful for images which are large or slow to open, because you pass a descriptor to write to and so control how and where the decompressed image is held. im_open() is useful for images in formats which can be directly read from disc, since you will avoid a copy operation and can directly control the disc file. The inplace operations (see §4.2.8), for example, will only work directly on disc images if you use im_open().

2.4.1 How a format is represented

See the man page for im_format for full details, but briefly, an image format consists of the following items:

2.4.2 The format table

VIPS keeps a table of known formats, sorted by insert order and priority. You register new formats with im_format_register() and, optionally, unregister with im_format_unregister(). You can call these operations from a plugin’s init function.

Any of the functions may be left NULL and VIPS will try to make do with what you do supply. Of course a format with all functions as NULL will not be very useful.

The priority system is useful if a file can be read by several possible format loaders. For example, the libMagick loader can read TIFF files, but not as well as VIPS’ native TIFF reader. To make sure the VIPS TIFF reader is tried first, the libMagick format is given a low priority. Most of the time, you won’t need this.

A switch to the vips command-line program is handy for listing the supported formats. Try:

vips --list formats

As an example, Figure 2.9 shows how to register a new format in a plugin.


static const char ⋆my_suffs[] = { ".me", NULL };  
 
static int  
is_myformat( const char ⋆filename )  
{  
  unsigned char buf[2];  
 
  if( im__get_bytes( filename, buf, 2 ) &&  
    (int) buf[0] == 0xff &&  
    (int) buf[1] == 0xd8 )  
    return( 1 );  
 
  return( 0 );  
}  
 
char ⋆  
g_module_check_init( GModule ⋆self )  
{  
  im_format_t ⋆format;  
 
  format = im_format_register( "myformat",  
    _( "My image format" ),  
    my_suffs,  
    is_myformat,  
    read_myformat_header,  
    read_myformat_image,  
    write_myformat,  
    NULL  
  };  
  im_format_set_priority( format, 100 );  
}


Figure 2.9: Registering a format in a plugin

2.4.3 Finding a format

You can loop over the format table in order with im_format_map(). Like all the map functions in VIPS, this take a function and applies it to every element in the table until it returns non-zero, or until the table has been all covered.

You find an im_format_t to use to open a file with im_format_for_file(). This searches the VIPS format table and returns the first format whose test function returns true, setting an error message and returning NULL if no format is found.

You find a format to write a file with im_format_for_name(). This returns the first format with a save function whose suffix list matches the suffix of the supplied filename.

2.4.4 Convenience functions

A pair of convenience functions, im_format_write() and im_format_read(), will copy an image to and from disc using the appropriate format.