Next: 2.2 Memory allocation Up: 2. Programming WIO operations Previous: 2. Programming WIO operations Contents

# 2.1 Input from an image

In WIO input, the whole of the image data is made available to the program via the `data` field of the descriptor. To make an image ready for reading in this style, programs should call `im_incheck()`:

    int im_incheck( IMAGE *im )

If it succeeds, it returns 0, if it fails, it returns non-zero and sets `im_errorstring`. On success, VIPS guarantees that all of the user-accessible fields in the descriptor contain valid data, and that all of the image data may be read by simply reading from the `data` field (see below for an example).

VIPS has some simple macros to help address calculations on images:

    int IM_IMAGE_SIZEOF_ELEMENT( IMAGE *im )
    int IM_IMAGE_SIZEOF_PEL( IMAGE *im )
    int IM_IMAGE_SIZEOF_LINE( IMAGE *im )
    int IM_IMAGE_N_ELEMENTS( IMAGE *im )
    char *IM_IMAGE_ADDR( IMAGE *im,
      int x, int y )

These macros calculate `sizeof()` a band element, a pel and a horizontal line of pels. `IM_IMAGE_N_ELEMENTS` returns the number of band elements across an image. `IM_IMAGE_ADDR` calculates the address of a pixel in an image. If `DEBUG` is defined, it does bounds checking too.

Figure 2.1: Find average of image

Figure 2.1 is a simple WIO operation which calculates the average of an unsigned char image. It will work for any size image, with any number of bands. See §2.4 for techniques for making operations which will work for any image type. This operation might be called from an application with:

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

    #include <vips/vips.h>

    void
    find_average( char *name )
    {
       IMAGE *im;
       double avg;

       if( !(im = im_open( name, "r" )) ||
          average( im, &avg ) ||
          im_close( im ) )
          error_exit( "failure!" );

       printf( "Average of \"%s\" is %G\n",
          name, avg );
    }

When you write an image processing operation, you can test it by writing a VIPS function descriptor and calling it from the `vips` universal main program, or from the `nip` interface. See the Application Programmers' Guide.

Next: 2.2 Memory allocation Up: 2. Programming WIO operations Previous: 2. Programming WIO operations Contents