NAME
im_demand_hint - hint on demand style for im_generate(3)
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.
SEE ALSO
im_generate(3), im_prepare(3).
COPYRIGHT
National Gallery
AUTHOR
J. Cupitt - 3/9/93
11 April 1990 IM_IOCHECK(3)