Image formats

VIPS has a simple system for adding support for new image file formats. 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. New formats may be added to VIPS by simply defining a new subclass of VipsFormat.

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.5.1 How a format is represented

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

2.5.2 The format class

The interface to the format system is defined by the abstract base class VipsFormat. Formats subclass this and implement some or all of the methods. 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.

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 );
}

// This format adds no new members.
typedef VipsFormat VipsFormatMyformat;
typedef VipsFormatClass VipsFormatMyformatClass;

static void
vips_format_myformat_class_init( VipsFormatMyformatClass ⋆class )
{
  VipsObjectClass ⋆object_class = (VipsObjectClass ⋆) class;
  VipsFormatClass ⋆format_class = (VipsFormatClass ⋆) class;

  object_class->nickname = "myformat";
  object_class->description = _( "My format" );

  format_class->is_a = is_myformat;
  format_class->header = my_header;
  format_class->load = my_read;
  format_class->save = my_write;
  format_class->get_flags = my_get_flags;
  format_class->priority = 100;
  format_class->suffs = my_suffs;
}

static void
vips_format_myformat_init( VipsFormatMyformat ⋆object )
{
}

G_DEFINE_TYPE( VipsFormatMyformat, vips_format_myformat, VIPS_TYPE_FORMAT );

char ⋆
g_module_check_init( GModule ⋆self )
{
  // register the type
  vips_format_myformat_get_type();
}

Figure 2.9: Registering a format in a plugin

2.5.3 Finding a format

You can loop over the subclasses of VipsFormat in order of priority with vips_format_map(). Like all the map functions in VIPS, this take a function and applies it to every element in the table until the function returns non-zero or until the table ends.

You find an VipsFormatClass to use to open a file with vips_format_for_file(). This finds the first format whose is_a() function returns true or whose suffix list matches the suffix of the filename, setting an error message and returning NULL if no format is found.

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

2.5.4 Convenience functions

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

2.5 Image formats

2.5.1 How a format is represented

2.5.2 The format class

2.5.3 Finding a format

2.5.4 Convenience functions