src/parsec/disk-image/parsec/parsec-benchmark/pkgs/apps/vips/src/doc/src/ipio.tex

\section{Programming in-place functions}

VIPS includes a little support for in-place functions --- functions
which operate directly on an image, both reading and writing from the same
descriptor via the data pointer. This is an extremely dangerous way to
handle IO, since any bugs in your program will trash your input image.

Operations of this type should call \verb+im_rwcheck()+ instead of
\verb+im_incheck()+. \verb+im_rwcheck()+ tries to get a descriptor ready
for in-place writing. For example, a function which cleared an image to
black might be written as:

\begin{verbatim}
#include <stdio.h>
#include <memory.h>

#include <vips/vips.h>

int
black_inplace( IMAGE *im )
{  
   /* Check that we can RW to im.
    */
   if( im_rwcheck( im ) )
      return( -1 );

   /* Zap the image!
    */
   memset( im->data, 0, 
      IM_IMAGE_SIZEOF_LINE( im ) * 
      im->Ysize );

   return( 0 );
}
\end{verbatim}

This function might be called from an application as:

\begin{verbatim}
#include <stdio.h>
#include <stdlib.h>

#include <vips/vips.h>

void
zap( char *name )
{
   IMAGE *im;

   if( !(im = im_open( name, "rw" )) ||
      black_inplace( im ) ||
      im_updatehist( im, "zap image" ) ||
      im_close( im ) )
      error_exit( "failure!" );
}
\end{verbatim}