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