182 lines
5.3 KiB
Groff
182 lines
5.3 KiB
Groff
.TH IM_FORMAT 3 "16 August 2008"
|
|
.SH NAME
|
|
im_format_register, im_format_set_priority, im_format_unregister,
|
|
im_format_map, im_format_for_file, im_format_for_name, im_format_write \-
|
|
load and search image formats
|
|
.SH SYNOPSIS
|
|
#include <vips/vips.h>
|
|
|
|
typedef enum {
|
|
.br
|
|
IM_FORMAT_FLAG_NONE = 0,
|
|
.br
|
|
IM_FORMAT_FLAG_PARTIAL = 1
|
|
.br
|
|
} im_format_flags;
|
|
|
|
typedef gboolean (*im_format_is_a_fn)( const char * );
|
|
.br
|
|
typedef int (*im_format_header_fn)( const char *, IMAGE * );
|
|
.br
|
|
typedef int (*im_format_load_fn)( const char *, IMAGE * );
|
|
.br
|
|
typedef int (*im_format_save_fn)( IMAGE *, const char * );
|
|
.br
|
|
typedef im_format_flags (*im_format_flags_fn)( const char * );
|
|
|
|
typedef struct im__format_t {
|
|
.br
|
|
const char *name;
|
|
.br
|
|
const char *name_user;
|
|
.br
|
|
int priority;
|
|
.br
|
|
const char **suffs;
|
|
.br
|
|
im_format_is_a_fn is_a;
|
|
.br
|
|
im_format_header_fn header;
|
|
.br
|
|
im_format_load_fn load;
|
|
.br
|
|
im_format_save_fn save;
|
|
.br
|
|
im_format_flags_fn flags;
|
|
.br
|
|
} im_format_t;
|
|
|
|
im_format_t *im_format_register(
|
|
.br
|
|
const char *name, const char *name_user, const char **suffs,
|
|
.br
|
|
im_format_is_a_fn is_a, im_format_header_fn header,
|
|
.br
|
|
im_format_load_fn load, im_format_save_fn save,
|
|
.br
|
|
im_format_flags_fn flags );
|
|
.br
|
|
void im_format_set_priority( im_format_t *format, int priority );
|
|
.br
|
|
void im_format_unregister( im_format_t *format );
|
|
|
|
void *im_format_map( VSListMap2Fn fn, void *a, void *b );
|
|
.br
|
|
im_format_t *im_format_for_file( const char *filename );
|
|
.br
|
|
im_format_t *im_format_for_name( const char *filename );
|
|
|
|
int im_format_write( IMAGE *im, const char *filename );
|
|
|
|
int im_format_read( const char *filename, IMAGE *out );
|
|
|
|
.SH DESCRIPTION
|
|
These functions register and unregister image formats, and search the table of
|
|
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. The format API is useful for controlling how a image
|
|
is unpacked, since you can specify a destination for the copy.
|
|
|
|
.B im_format_register(3)
|
|
registers an image format with vips. This might typically be called during
|
|
module load, see the documentation for GModule.
|
|
|
|
An image format has a number of components:
|
|
|
|
.B name
|
|
The internal name by which the format should be known. For example, the
|
|
OpenEXR image format is known within vips as "exr". You can identify formats
|
|
by testing this field with
|
|
.B strcmp(3).
|
|
|
|
.B name_user
|
|
The name as it should be displayed to the user. It can be internationalised.
|
|
For example, in English, the "analyze" format is shown as "Analyze 6.0".
|
|
|
|
.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 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 lload method implemented.
|
|
|
|
.B flags
|
|
A function which examines the file and sets various flags to indicated
|
|
properties of the image. The only flag implemented at the moment is
|
|
.B IM_FORMAT_FLAG_PARTIAL
|
|
which may be set to indicate that the file can be read lazily.
|
|
|
|
vips registers the format and returns a pointer to the
|
|
.B im_format_t
|
|
it created. This may later be used to unregister the format.
|
|
|
|
.B im_format_set_priority(3)
|
|
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 im_format_unregister(3)
|
|
removes a format from vips. It mmight typically be called during module
|
|
unload, see the documentation for GModule.
|
|
|
|
.B im_format_map(3)
|
|
maps a function over the list of loaded formats. See
|
|
.B im_slist_map(3).
|
|
|
|
.B im_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 im_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 im_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 im_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
|