Next: 3.3 Examples Up: 3. The VIPS image Previous: 3.1 Image descriptors Contents

# 3.2 Opening and closing

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:

`"r"`
  The file is opened read-only. If you open a non-VIPS image, or a VIPS image written on a machine with a different byte ordering, `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.

`"w"`
  An `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.

`"t"`
  As the `"w"` mode, but pels written to the descriptor will be saved in a temporary memory buffer.

`"p"`
  This creates a special partial image. Partial images are used to join VIPS operations together, see §3.8.

`"rw"`
  As the `"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"`.

Next: 3.3 Examples Up: 3. The VIPS image Previous: 3.1 Image descriptors Contents