libvips/doc/src/format.tex

\section{Image formats}
\label{sec:format}

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 \verb+IMAGE+, or an \verb+IMAGE+ to a file.

This is a parallel API to \verb+im_open()+, see \pref{sec:open}. 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. \verb+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 \pref{sec:inplace}), for example, will only work directly on disc
images if you use \verb+im_open()+.

\subsection{How a format is represented}

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

\begin{itemize}
\item
A name, a name that can be shows to the user, and a list of possible filename
suffixes (\verb+.tif+, for example)

\item
A function which tests for a file being in that format, a function which loads 
just the header of the file (that is, it reads properties like width and
height and does not read any pixel data) and a function which loads the pixel
data

\item
A function which will write an IMAGE to a file in the format

\item
And finally a function which examines a file in the format and returns flags
indicating how VIPS should deal with the file. The only flag in the current
version is one indicating that the file can be opened lazily

\end{itemize}

\subsection{The format table}

VIPS keeps a table of known formats, sorted by insert order and priority. You
register new formats with \verb+im_format_register()+ and, optionally,
unregister with \verb+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 \verb+vips+ command-line program is handy for listing the
supported formats. Try:

\begin{verbatim}
vips --list formats
\end{verbatim}

As an example, \fref{fg:newformat} shows how to register a new format in a
plugin.

\begin{fig2}
\begin{verbatim}
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 );
}
\end{verbatim}
\caption{Registering a format in a plugin}
\label{fg:newformat}
\end{fig2}

\subsection{Finding a format}

You can loop over the format table in order with \verb+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 \verb+im_format_t+ to use to open a file with
\verb+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 \verb+im_format_for_name()+. This
returns the first format with a save function whose suffix list matches the
suffix of the supplied filename.

\subsection{Convenience functions}

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