IM_OPEN(3)

NAME
im_open, im_open_local, im_open_local_array - open VIPS image descriptor(s)

SYNOPSIS
#include <vips/vips.h> IMAGE *im_open( const char *filename, const char *mode ) IMAGE *im_open_local( IMAGE *im, const char *filename, const char *mode ) int im_open_local_array( IMAGE *im,
  IMAGE **out, int n, const char *filename, const char *mode )

DESCRIPTION
im_open(3) examines the mode string, and creates an appropriate VIPS IMAGE descriptor. See `VIPS Library Programmers' Guide,' for an introduction to IMAGE input and output. r opens the named file for reading. If the file is not in the native VIPS format for your machine, im_open(3) automatically converts the file for you in memory. For some large files (eg. TIFF) this may not be what you want: you should call the appropriate converter yourself, and arrange for the conversion to take place on disc. See im_tiff2vips(3), im_jpeg2vips(3), im_png2vips(3), im_magick2vips(3), and im_ppm2vips(3). im_open(3) can read files in most formats. w opens the named file for writing. It looks at the file name suffix to determine the type to write -- for example:
  im_open( "fred.tif", "w" ) will write in TIFF format. You can pass parameters to the conversion functions encoded in the filename string. For example:
  im_open( "fred.tif:deflate", "w" ) will write a deflate (ZIP) compressed TIFF file. See the man pages for im_vips2tiff(3), im_vips2jpeg(3), im_vips2png(3) and im_vips2ppm(3) for details on all of the options available. t creates a temporary memory buffer image. p creates a "glue" descriptor you can use to join two image processing operations together. rw opens the named file for reading and writing. This will only work for VIPS files in a format native to your machine. It is only for paintbox-type applications. im_open_local(3) is a convenience function which opens an image descriptor as im_open(3), but makes it local to im, that is, when im is closed, the descriptor created by im_open_local(3) will be closed too. im_open_local(3) is handy for saving you from adding many im_close(3) calls to escape points. Example: find the total of an array of images.
  #include <vips/vips.h>
  #include <vips/region.h>
  int
  total( IMAGE **in, int nin, IMAGE *out )
  {
    int i;
    IMAGE *t1, *t2;
    if( nin <= 0 ) {
      im_errormsg( "total: nin should be > 0" );
      return( -1 );
    }
    else if( nin == 1 )
      return( im_copy( *in, out ) );
    else
      for( t1 = *in, i = 1; i < nin; i++ ) {
        if( i + 1 == nin )
      t2 = out;
    else if( !(t2 = im_open_local( out, "t2", "p" )) )
          return( -1 );
        if( im_add( t1, in[i], t2 ) )
          return( -1 );
        t1 = t2;
      }
    return( 0 );
  } This function will create many intermediate images, but does not need to close them. Any which are created will be closed automatically when out is closed by our caller. im_open_local(3) returns NULL on error, or if its first parameter is NULL. im_open_local_array(3) will open an array of images, failing if any of the opens fail. It's handy if you need a number of images for intermediates. Example:
  IMAGE *t[6];
  if( im_open_local_array( out, t, 6, "mytemps", "p" ) )
    return( -1 ); opens 6 temp images (t[0] to t[5]).

RETURN VALUE
The function returns the image descriptor on success and NULL on error.

SEE ALSO
im_close(3), im_vips2tiff(3), im_vips2jpeg(3), im_vips2ppm(3), im_tiff2vips(3), im_jpeg2vips(3), im_ppm2vips(3), `VIPS Library Programmers' Guide,' in accompanying documentation.

COPYRIGHT
K. Martinez, 1992.

AUTHOR
K. Martinez.