next up previous contents
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_error(). 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
\begin{figure}\begin{quote}
\begin{verbatim}...

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 up previous contents
Next: 2.2 Memory allocation Up: 2. Programming WIO operations Previous: 2. Programming WIO operations   Contents
John Cupitt 2004-11-02