| .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> |
| |
| 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 |
