| .TH VIPS_FORMAT 3 "16 August 2008" |
| .SH NAME |
| VipsFormat, |
| vips_format_map, vips_format_for_file, vips_format_for_name, |
| vips_format_write \- |
| load and search image formats |
| .SH SYNOPSIS |
| #include <vips/vips.h> |
| |
| typedef enum { |
| .br |
| VIPS_FORMAT_NONE = 0, |
| .br |
| VIPS_FORMAT_PARTIAL = 1 |
| .br |
| } VipsFormatFlags; |
| |
| typedef struct _VipsFormatClass { |
| .br |
| VipsObjectClass parent_class; |
| |
| gboolean (*is_a)( const char * ); |
| .br |
| int (*header)( const char *, IMAGE * ); |
| .br |
| int (*load)( const char *, IMAGE * ); |
| .br |
| int (*save)( IMAGE *, const char * ); |
| .br |
| VipsFormatFlags (*get_flags)( const char * ); |
| .br |
| int priority; |
| .br |
| const char **suffs; |
| .br |
| } VipsFormatClass; |
| |
| void *vips_format_map( VSListMap2Fn fn, void *a, void *b ); |
| .br |
| VipsFormatClass *vips_format_for_file( const char *filename ); |
| .br |
| 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 ); |
| |
| .SH DESCRIPTION |
| These functions search the |
| available image formats to find one suitable for loading or saving a file. |
| |
| .B 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: |
| .B 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 |
| .B VipsFormat |
| as outlined above. They are expected to implement at least one of the methods. |
| They should also set values for the |
| .B nickname |
| and |
| .B description |
| members of |
| .B VipsObject. |
| |
| Other members are: |
| |
| .B 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. |
| |
| .B header() |
| Load only the image header, not any of the image pixels. vips will call this |
| first on |
| .B im_open(3) |
| and delay loading pixels until asked. If you leave this NULL, vips will just |
| use the |
| .B load() |
| function. |
| |
| .B load() |
| Load the image from the file into the IMAGE. You can leave this function NULL |
| if you only have a |
| .B save() |
| method implemented. Load options may be embedded in the filename, see the |
| loaders below. |
| |
| .B 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. |
| |
| .B 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 |
| .B VIPS_FORMAT_PARTIAL |
| which may be set to indicate that the file can be read lazily. |
| |
| .B 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. |
| |
| .B 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: |
| .B { ".jpg", ".jpeg", ".jpe", NULL } |
| |
| .B vips_format_map(3) |
| maps a function over the list of available formats. See |
| .B im_slist_map(3). |
| |
| .B 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. |
| |
| .B 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. |
| |
| .B 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. |
| |
| .B 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. |
| |
| .SH SUPPORTED FORMATS |
| |
| See the following manpages for details on each of the converters and the |
| options they implement. |
| |
| .B im_analyze2vips(3) |
| .B im_csv2vips(3) |
| .B im_exr2vips(3) |
| .B im_jpeg2vips(3) |
| .B im_magick2vips(3) |
| .B im_png2vips(3) |
| .B im_ppm2vips(3) |
| .B im_tiff2vips(3) |
| .B im_vips2csv(3) |
| .B im_vips2jpeg(3) |
| .B im_vips2png(3) |
| .B im_vips2ppm(3) |
| .B im_vips2tiff(3) |
| |
| You can also load Matlab .mat files and load or save Radiance HDR files. See |
| .B im_binfile(3) |
| and |
| .B im_raw2vips(3) |
| for RAW file read. |
| |
| You can list the supported formats with |
| |
| $ vips --list classes |
| |
| look for subclasses of |
| .B VipsFormat. |
| |
| .SH RETURN VALUE |
| The functions return 0 success and -1 on error. |
| .SH SEE ALSO |
| im_tiff2vips(3), im_open(3), vips(1). |
| .SH AUTHOR |
| Jesper Friis and John Cupitt |