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

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: 2.4 Polymorphism Up: 2. Programming WIO operations Previous: 2.2 Memory allocation Contents