libvips/man/im_open.3

.TH IM_OPEN 3 "30 October 1992"
.SH NAME
im_open, im_open_local, im_open_local_array \- open VIPS 
image descriptor(s)
.SH 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 )

.SH DESCRIPTION
.B im_open(3)
examines the mode string, and creates an appropriate VIPS IMAGE descriptor.

.B "r" 
opens the named file for reading. If the file is not in the native VIPS format
for your machine,
.B 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
.B im_tiff2vips(3),
.B im_jpeg2vips(3),
.B im_png2vips(3),
.B im_magick2vips(3),
and
.B im_ppm2vips(3).

.B im_open(3)
can read files in most formats.

.B "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
.B im_vips2tiff(3),
.B im_vips2jpeg(3),
.B im_vips2png(3)
and
.B im_vips2ppm(3)
for details on all of the options available.

.B "t"
creates a temporary memory buffer image.

.B "p"
creates a "glue" descriptor you can use to join two image processing
operations together.

.B "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.

.B 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.

.B im_open_local(3) 
is handy for saving you from adding many 
.B im_close(3) 
calls to
escape points. Example: find the total of an array of images.

  #include <vips/vips.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.

.B im_open_local(3) 
returns NULL on error, or if its first parameter is NULL.

.B 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]).

.SH RETURN VALUE
The function returns the image descriptor on success and NULL on error.
.SH SEE ALSO
im_close(3), im_vips2tiff(3), im_vips2jpeg(3), im_vips2ppm(3),
im_tiff2vips(3), im_jpeg2vips(3), im_ppm2vips(3).
.SH COPYRIGHT
K. Martinez, 1992.
.SH AUTHOR
K. Martinez.