---
name: "im_allocate_input_array"
section: "3"
platform: "linux"
package: "libvips-dev"
version: "7.20.7-1+b3"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/im_generate"
---

# im\_allocate\_input\_array(3)

generate image pixels

Part of [im\_generate(3)](/im_generate/3.md).

## NAME

im\_generate, im\_start\_one, im\_stop\_one, im\_allocate\_input\_array,  im\_start\_many, im\_stop\_many - generate image pixels

## SYNOPSIS

**#include \<vips/vips.h\>**

void \*im\_start\_one( out, in )\
 IMAGE \*out, \*in;

int im\_stop\_one( reg )\
 REGION \*reg;

IMAGE \*\*im\_allocate\_input\_array( IMAGE \*out, ... )

void \*im\_start\_many( out, in )\
 IMAGE \*out, \*\*in;

int im\_stop\_many( REGION \*\*out )\
 REGION \*\*out;

int im\_generate( im, \
     start\_fn, gen\_fn, stop\_fn, void \*a, void \*b )\
 IMAGE \*im;\
 void \*(\*start\_fn)();\
 int (\*gen\_fn)();\
 int (\*stop\_fn)();\
 void \*a, void \*b;

where, typically,

void \*start\_fn( im, a, b )\
 IMAGE \*im;\
 void \*a, \*b;

int gen\_fn( or, seq, a, b )\
 REGION \*or;\
 void \*seq;\
 void \*a, \*b;

int stop\_fn( seq, a, b )\
 void \*seq;\
 void \*a, \*b;

## DESCRIPTION

**[im\_generate(3)](/im_generate/3.md),** with its supporting convenience functions, is used for PIO image output.  See also **[im\_wrapone(3)](/im_wrapone/3.md)** for an easy alternative to  **[im\_generate(3)](/im_generate/3.md)** for simple image processing operations.

**[im\_start\_one(3)](/im_start_one/3.md)** and  **[im\_stop\_one(3)](/im_stop_one/3.md)** are convenience functions, useful for simple one-image-in, one-image-out operations.  **[im\_start\_one(3)](/im_start_one/3.md)** assumes the first of the two user arguments (a, above) is the input image. It creates a REGION on this image and returns a pointer to the region as a sequence value.

**[im\_stop\_one(3)](/im_stop_one/3.md)** assumes the sequence value is a REGION pointer, and frees it.

**[im\_allocate\_input\_array(3)](/im_allocate_input_array/3.md)** takes as arguments the output image and a list of input images, terminated with a NULL. It allocates a NULL-terminated array to hold the images, and attaches a close callback to the output image to free that array. Example:

    IMAGE \*in, \*in2, \*in3, \*in4;\
     IMAGE \*\*arry;

    if( !(arry = im\_allocate\_input\_array( out, \
         in1, in2, in3, in4, NULL )) )\
         return( -1 );

builds the structure

    IMAGE \*arry\[\] = { in1, in2, in3, in4, NULL };

and makes sure it will be freed.

**[im\_start\_many(3)](/im_start_many/3.md)** and  **[im\_stop\_many(3)](/im_stop_many/3.md)** work exactly as  **[im\_start\_one(3)](/im_start_one/3.md)** and **[im\_stop\_one(3)](/im_stop_one/3.md),** but with NULL-terminated arrays of IMAGEs and REGIONs. They are useful for many-images-in, one-image-out operations. **[im\_start\_many(3)](/im_start_many/3.md)** assumes that the first of the two user arguments is a pointer to a NULL-terminates array of IMAGEs. It builds and returns as the sequence value a NULL-terminated array of REGIONs.

**[im\_stop\_many(3)](/im_stop_many/3.md)** assumes the sequence value is a pointer to a NULL-terminated array of REGIONs. It frees all the regions in turn. See  **[im\_add(3)](/im_add/3.md)** for an example of this pair of functions in action.

**[im\_generate(3)](/im_generate/3.md)** looks at the type of im and acts accordingly:

    IM\_PARTIAL: the start, process and stop functions are attached to the  region, and im\_generate returns immediately. See  **[im\_prepare(3)](/im_prepare/3.md).**

    IM\_SETBUF: memory for the output image is created and sequences started to fill it. It is an error to write to the same buffer twice.

    IM\_MMAPINRW: sequences are started, and asked to fill the image in patches.

    IM\_OPENOUT: The output file is created and a header written to disc. A  buffer large enough to hold GENERATE\_TILE\_HEIGHT complete horizontal lines is created, and sequences started to fill this buffer. When the buffer has been filled, the whole set of lines are flushed to disc in a single [write(2)](/write/2.md) operation, and work starts on the next set of lines.

Any other image type is an error.  **[im\_generate(3)](/im_generate/3.md)** returns 0 for complete success, and non-zero on failure.

    static int\
     wombat\_gen( or, ir, in )\
     REGION \*or, \*ir;\
     IMAGE \*in;\
     {\
         ... process!

        return( 0 );\
     }

    int\
     im\_wombat( in, out )\
     IMAGE \*in, \*out;\
     {\
         if( im\_iocheck( in, out ) )\
             return( -1 );

        ... check parametersm check image descriptors \
         ... for type-compatibility, etc. etc.

        if( im\_cp\_desc( out, in ) )\
             return( -1 );

        ... set fields in out for the type of image you\
         ... wish to write

        if( im\_generate( out,\
             im\_start\_one, wombat\_gen, im\_stop\_one, \
             in, NULL ) )\
             return( -1 );

        return( 0 );\
     }

See also the source to  **[im\_invert(3)](/im_invert/3.md),** **[im\_exptra(3)](/im_exptra/3.md),** and, if you are brave, **[im\_conv(3)](/im_conv/3.md)** or  **[im\_add(3)](/im_add/3.md).**

On machines with several CPUs,  **[im\_generate(3)](/im_generate/3.md)** and **[im\_iterate(3)](/im_iterate/3.md)** automatically parallelise programs. You can set the desired concurrency level with the environment variable IM\_CONCURRENCY, for example

    example% export IM\_CONCURRENCY=2\
     example% lintra 2.0 fred.v 0.0 fred2.v

will run lintra with enough concurrency to keep 2 CPUs fully occupied. If IM\_CONCURRENCY is not set, then it defaults to 1. See also [im\_concurrency\_set(3)](/im_concurrency_set/3.md).

Most programs which use VIPS will also let you use the command-line argument --vips-concurrency to set parallelisation, see [im\_get\_option\_group(3)](/im_get_option_group/3.md).

## COPYRIGHT

National Gallery, 1993

## SEE ALSO

[im\_wrapone(3)](/im_wrapone/3.md), [im\_add\_eval\_callback(3)](/im_add_eval_callback/3.md), [im\_iterate(3)](/im_iterate/3.md), [im\_piocheck(3)](/im_piocheck/3.md), [im\_concurrency\_set(3)](/im_concurrency_set/3.md), [im\_get\_option\_group(3)](/im_get_option_group/3.md), \`VIPS manual,' in accompanying documentation.

## AUTHOR

J. Cupitt - 23/7/93