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 named is opened read-only and an `IMAGE` descriptor is returned with all the fields filled in.

  If you open a non-VIPS image, or a VIPS image written on a machine with a different byte ordering, `im_open()` will use one of the conversion functions (eg. see the man page for `im_tiff2vips()`) to make the image readable. For big images this can require a large amount of RAM -- you might be better off allocating a disc file and calling the conversion function yourself..

  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" );

  /noindent 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.

`"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 below.

`"w"`
  An `IMAGE` descriptor is created which, when written to, will write pels 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.

If an error occurs opening the image, `im_open()` calls `im_errormsg()` with a string describing the cause of the error and returns `NULL`. `im_errormsg()` has type

    void im_errormsg( const char *format,
      ... )

The arguments to `im_errormsg()` works 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_errorstring()`.

    const char *im_errorstring()

Applications may display this string to give users feedback about the cause of the error. The VIPS exit function, `error_exit()`, prints `im_errorstring` to `stderr` and terminates the program with an error code of 1.

    void error_exit( const char *format,
      ... )

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, setting `im_errorstring()`. 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