146 lines
4.1 KiB
Groff
146 lines
4.1 KiB
Groff
.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.
|
|
|
|
.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.
|
|
|
|
.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 RETURN VALUE
|
|
The functions return 0 success and -1 on error.
|
|
.SH SEE ALSO
|
|
im_tiff2vips(3), im_open(3).
|
|
.SH AUTHOR
|
|
Jesper Friis and John Cupitt
|