Descriptors are created with im_open()
. This takes a file name
and a string representing the mode with which the descriptor is to be opened:
IMAGE *im_open( const char *filename, const char *mode )
The possible values for mode are:
im_open()
will automatically convert it to
native VIPS format. If the underlying file does not support random access
(JPEG, for example), the entire file will be converted in memory.
VIPS can read images in TIFF, JPEG, PPM/PGM/PBM, PNG and VIPS format, all in both big- and little-endian varieties. You can control the details of the conversion with extra characters embedded in the filename. For example:
fred = im_open( "fred.tif:2", "r" );
will read page 2 of a multi-page TIFF. See the man pages for details.
If VIPS has been built with libMagick, it can also read any of the 80 or so libMagick-supported image file formats.
IMAGE
descriptor is created which, when written to, will write
pixels to disc in the specified file.
VIPS looks at the filename suffix to determine the save format. If there
is no suffix, or the filename ends in ".v"
, the image is written
in VIPS native format.
If the filename ends in ".tif"
or ".tiff"
, the image
is written with im_vips2tiff()
. If the filename ends in
".jpg"
, ".jpeg"
or ".jpe"
, the image is written with
im_vips2jpg()
. If the filename ends with ".pbm"
, ".pgm"
or ".ppm"
, the image is written using im_vips2ppm()
.
If the filename ends with ".png"
, the image is written using
im_vips2png()
. Case is not considered when testing the suffix.
If you want to control the details of the conversion to the disc format (such as setting the Q factor for a JPEG, for example), you embed extra control characters in the filename. For example:
fred = im_open( "fred.jpg:95", "w" );
writes to fred
will write a JPEG with Q 95. Again, see the man pages
for the conversion functions for details.
"w"
mode, but pels written to the descriptor will be saved
in a temporary memory buffer.
"r"
mode, but the image is mapped into the caller's address
space read-write. This mode is only provided for the use of paintbox-style
applications which need to directly modify an image. Most programs should
use the "w"
mode for image output.
If an error occurs opening the image, im_open()
calls
im_error()
with a string describing the cause of the error and
returns NULL
. im_error()
has type
void im_error( const char *domain, const char *format, ... )
The first argument is a string giving the name of the thing that raised
the error (just "im_open"
, for example). The format and subsequent
arguments work exactly as printf()
. It formats the message and
appends the string formed to the error log. You can get a pointer to the
error text with im_error_buffer()
.
const char *im_error_buffer()
Applications may display this string to give users feedback about the
cause of the error. The VIPS exit function, error_exit()
, prints
im_error_buffer()
to stderr
and terminates the program with an
error code of 1.
void error_exit( const char *format, ... )
There are other functions for handling errors: see the man page for
im_error()
.
If the file name given to im_open()
ends with ".v"
, VIPS
looks in the same directory as the image for a file with the same name
but with the extension ".desc"
. If present, this file is read in
and a pointer to the data put in the Hist
field of the descriptor. See
the notes on im_updatehist()
in §3.3.
Descriptors are closed with im_close()
. It has type:
int im_close( IMAGE *im )
im_close()
returns 0 on success and non-zero on error.
If the descriptor represents a disc file which
has been written to and whose name ends in ".v"
, VIPS writes the
Hist
field of the image descriptor to a file in the same directory
whose name ends in ".desc"
.