1IM_OPEN(3)                 Library Functions Manual                 IM_OPEN(3)
2
3
4

NAME

6       im_open,  im_open_local, im_open_local_array - open VIPS image descrip‐
7       tor(s)
8

SYNOPSIS

10       #include <vips/vips.h>
11
12       IMAGE *im_open( const char *filename, const char *mode )
13
14       IMAGE *im_open_local( IMAGE *im, const char *filename, const char *mode
15       )
16
17       int im_open_local_array( IMAGE *im,
18         IMAGE **out, int n, const char *filename, const char *mode )
19
20

DESCRIPTION

22       im_open(3)  examines  the  mode string, and creates an appropriate VIPS
23       IMAGE descriptor.  See `VIPS Library Programmers' Guide,' for an intro‐
24       duction to IMAGE input and output.
25
26       r  opens  the  named file for reading. If the file is not in the native
27       VIPS format for your machine,  im_open(3)  automatically  converts  the
28       file  for  you in memory. For some large files (eg.  TIFF) this may not
29       be what you want: you should call the appropriate  converter  yourself,
30       and   arrange   for   the   conversion  to  take  place  on  disc.  See
31       im_tiff2vips(3),  im_jpeg2vips(3),  im_png2vips(3),  im_magick2vips(3),
32       and im_ppm2vips(3).
33
34       im_open(3) can read files in most formats.
35
36       w opens the named file for writing. It looks at the file name suffix to
37       determine the type to write -- for example:
38
39         im_open( "fred.tif", "w" )
40
41       will write in TIFF format.
42
43       You can pass parameters to the  conversion  functions  encoded  in  the
44       filename string. For example:
45
46         im_open( "fred.tif:deflate", "w" )
47
48       will  write a deflate (ZIP) compressed TIFF file. See the man pages for
49       im_vips2tiff(3), im_vips2jpeg(3), im_vips2png(3) and im_vips2ppm(3) for
50       details on all of the options available.
51
52       t creates a temporary memory buffer image.
53
54       p  creates a "glue" descriptor you can use to join two image processing
55       operations together.
56
57       rw opens the named file for reading and writing. This  will  only  work
58       for  VIPS  files  in  a  format  native to your machine. It is only for
59       paintbox-type applications.
60
61       im_open_local(3)  is  a  convenience  function  which  opens  an  image
62       descriptor as im_open(3), but makes it local to im, that is, when im is
63       closed, the descriptor created by im_open_local(3) will be closed too.
64
65       im_open_local(3) is handy for saving you from adding  many  im_close(3)
66       calls to escape points. Example: find the total of an array of images.
67
68         #include <vips/vips.h>
69         #include <vips/region.h>
70
71         int
72         total( IMAGE **in, int nin, IMAGE *out )
73         {
74           int i;
75           IMAGE *t1, *t2;
76
77           if( nin <= 0 ) {
78             im_errormsg( "total: nin should be > 0" );
79             return( -1 );
80           }
81           else if( nin == 1 )
82             return( im_copy( *in, out ) );
83           else
84             for( t1 = *in, i = 1; i < nin; i++ ) {
85               if(  i  +  1  ==  nin  )         t2 = out;      else if( !(t2 =
86       im_open_local( out, "t2", "p" )) )
87                 return( -1 );
88
89               if( im_add( t1, in[i], t2 ) )
90                 return( -1 );
91               t1 = t2;
92             }
93
94           return( 0 );
95         }
96
97       This function will create many intermediate images, but does  not  need
98       to  close them. Any which are created will be closed automatically when
99       out is closed by our caller.
100
101       im_open_local(3) returns NULL on error, or if its  first  parameter  is
102       NULL.
103
104       im_open_local_array(3)  will open an array of images, failing if any of
105       the opens fail. It's handy if you need a number of images for  interme‐
106       diates. Example:
107
108         IMAGE *t[6];
109
110         if( im_open_local_array( out, t, 6, "mytemps", "p" ) )
111           return( -1 );
112
113       opens 6 temp images (t[0] to t[5]).
114
115

RETURN VALUE

117       The function returns the image descriptor on success and NULL on error.
118

SEE ALSO

120       im_close(3),    im_vips2tiff(3),    im_vips2jpeg(3),    im_vips2ppm(3),
121       im_tiff2vips(3), im_jpeg2vips(3), im_ppm2vips(3),  `VIPS  Library  Pro‐
122       grammers' Guide,' in accompanying documentation.
123

125       K. Martinez, 1992.
126

AUTHOR

128       K. Martinez.
129
130
131
132                                30 October 1992                     IM_OPEN(3)
Impressum