Man Linux: Main Page and Category List

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) 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.

SEE ALSO

       im_tiff2vips(3), im_open(3), vips(1).

AUTHOR

       Jesper Friis and John Cupitt

                                16 August 2008                  VIPS_FORMAT(3)