Next: About this document ... Up: libguide Previous: 3.7 Memory allocation revisited Contents

# 4. 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 `im_rwcheck()` instead of `im_incheck()`. `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:

    #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 );
    }

This function might be called from an application as:

    #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!" );
    }