SYNOPSIS

#include <vips/vips.h>

int im_demand_hint( im, hint, in1, in2, ..., NULL )
IMAGE *im, *in1, *in2, ...;
im_demand_type hint;

int im_demand_hint_array( im, hint, in )
IMAGE *im, **in;
im_demand_type hint;

DESCRIPTION

im_demand_hint(3) suggests to im_generate(3) the sorts of demand with which this image processing operation would be happiest.

im is the image this operation is generating. hint is the demand style this operation would like (see below), and in1 ... is a NULL-terminated list of the image upon which this output image directly depends, that is, the images which this operation will call im_prepare(3) for.

This list of parent images is necessary, as im_demand_hint(3) needs to know what demand style this operation's ancestors have requested. If an ancestor of this operation has specified a very restrictive demand style, then this operation must fall back to that restrictive style and ignore the hint given in this call to im_demand_hint(3).

VIPS currently supports three demand styles. More may be added in the future. These demand styles are given below in order of increasing restrictiveness. When demanding output from a pipeline, im_generate(3) will use the most restrictive of the styles requested by the operations in the pipeline.

IM_THINSTRIP
This operation would like to output strips the width of the image and a few pels high. This is option suitable for point-to-point operations, such as those in the arithmetic package.

This option is only efficient for cases where each output pel depends upon the pel in the corresponding position in the input image.

IM_FATSTRIP
This operation would like to output strips the width of the image and as high as possible. This option is suitable for area operations which do not violently transform coordinates, such as im_conv(3).

IM_SMALLTILE
This is the most general demand format, and is the default. Output is demanded in small (around 100x100 pel) sections. This style works reasonably efficiently, even for bizzare operations like 45 degree rotate.

IM_ANY
This image is not being demand-read from a disc file (even indirectly) so any demand style is OK. It's used for things like im_black(3) where the pixels are calculated.

im_demand_hint_array(3) works exactly as im_demand_hint(3), but expects a pointer to a NULL-terminated array of parent images as its third argument. You may use im_allocate_input_array(3), if you wish, to build this structure.

As an example, here is part of the code for im_invert(3). In this operation, each output pel depends upon the corresponding input pel. In other words, there is no coordinate transformation in im_prepare(3). This style of operation is most efficient with IM_THINSTRIP IO.

int im_invert( IMAGE *in, IMAGE *out )
{
       if( in->Coding != NOCODING ) {

               im_errormsg( "im_invert: input coded" );

               return( -1 );

       }

       if( in->BandFmt != FMTUCHAR ) {

               im_errormsg( "im_invert: input not UCHAR" );

               return( -1 );

       }


        if( im_piocheck( in, out ) )
               return( -1 );


        if( im_cp_desc( out, in ) ) 
               return( -1 );

       if( im_demand_hint( out, IM_THINSTRIP, in, NULL ) )

                return( -1 );

       if( im_generate( out,

               im_start_one, inv_gen, im_stop_one, in, NULL ) )

               return( -1 );

       return( 0 );

}

RETURN VALUE

All functions returns 0 on success and non-zero on error.

COPYRIGHT

National Gallery

AUTHOR

J. Cupitt - 3/9/93