next up previous contents
Next: 2.4 Polymorphism Up: 2. Programming WIO operations Previous: 2.2 Memory allocation   Contents

2.3 Output to an image

Before attempting WIO output, programs should call im_outcheck(). It has type:

int im_outcheck( IMAGE *im )

If im_outcheck() succeeds, VIPS guarantees that WIO output is sensible.

Programs should then set fields in the output descriptor to describe the sort of image they wish to write (size, type, and so on) and call im_setupout(). It has type:

int im_setupout( IMAGE *im )

im_setupout() creates the output file or memory buffer, using the size and type fields that were filled in by the program between the calls to im_outcheck() and im_setupout(), and gets it ready for writing.

Pels are written with im_writeline(). This takes a y position (pel (0,0) is in the top-left-hand corner of the image), a descriptor and a pointer to a line of pels. It has type:

int im_writeline( int y, 
   IMAGE *im, unsigned char *pels )

Two convenience functions are available to make this process slightly easier. im_iocheck() is useful for programs which take one input image and produce one image output. It simply calls im_incheck() and im_outcheck(). It has type:

int im_iocheck( IMAGE *in, IMAGE *out )

The second convenience function copies the fields describing size, type and history from one image descriptor to another. It is useful when the output image will be similar in size and type to the input image. It has type:

int im_cp_desc( IMAGE *out, IMAGE *in )

Figure 2.2: Invert an image
\begin{figure}\begin{quote}
\begin{verbatim}...

Figure 2.2 is a WIO VIPS operation which finds the photographic negative of an unsigned char image. This operation might be called from an application with:

#include <stdio.h>
#include <stdlib.h>

#include <vips/vips.h>

void
find_negative( char *inn, char *outn )
{
   IMAGE *in, *out;

   if( !(in = im_open( inn, "r" )) ||
      !(out = im_open( outn, "w" )) ||
      invert( in, out ) ||
      im_updatehist( out, "invert" ) ||
      im_close( in ) || 
      im_close( out ) )
      error_exit( "failure!" );
}

Note the call to im_updatehist(). This has type

int im_updatehist( IMAGE *im, 
   char *format, ... )

It formats its arguments in the manner of printf() and appends that string, together with a date and time, to the Hist field in the image descriptor.


next up previous contents
Next: 2.4 Polymorphism Up: 2. Programming WIO operations Previous: 2.2 Memory allocation   Contents
John Cupitt 2003-07-21