.TH IM_IOCHECK 3 "11 April 1990"
.SH NAME
im_demand_hint \- hint on demand style for im_generate(3)
.SH SYNOPSIS
#include <vips/vips.h>
.br
#include <vips/region.h>

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

int im_demand_hint_array( im, hint, in )
.br
IMAGE *im, **in;
.br
im_demand_type hint;
.SH DESCRIPTION
.B im_demand_hint(3) 
suggests to im_generate(3) the sorts of demand with which this image processing
operation would be happiest. 

.B im
is the image this operation is generating.
.B hint
is the demand style this operation would like (see below), and
.B 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
.br
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
.br
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
.br
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
.br
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
.B im_black(3)
where the pixels are calculated.

.B
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 )
.br
{
.br
	if( in->Coding != NOCODING ) {
.br
		im_errormsg( "im_invert: input coded" );
.br
		return( -1 );
.br
	}
.br
	if( in->BandFmt != FMTUCHAR ) {
.br
		im_errormsg( "im_invert: input not UCHAR" );
.br
		return( -1 );
.br
	}
.br
        if( im_piocheck( in, out ) )
.br
		return( -1 );
.br
        if( im_cp_desc( out, in ) ) 
.br
		return( -1 );
.br
	if( im_demand_hint( out, IM_THINSTRIP, in, NULL ) )
.br
		 return( -1 );
.br
	if( im_generate( out,
.br
		im_start_one, inv_gen, im_stop_one, in, NULL ) )
.br
		return( -1 );
.br
	return( 0 );
.br
}

.SH RETURN VALUE
All functions returns 0 on success and non-zero on error.
.SH SEE ALSO
im_generate(3), im_prepare(3). 
.SH COPYRIGHT
National Gallery
.SH AUTHOR
J. Cupitt \- 3/9/93