History of allocArray

== Syntax ==

int allocArray (int nr, int X, int Y, int Z, int bytes)

== Arguments ==

:nr

::Number of the Array. Values from 0 to 99 are allowed.

:X, Y, Z

::Amount of X, Y and Z cells in the three-dimensional array. If you want to allocate a one-dimensional array simply set Y and Z to zero. If you want to allocate a two-dimensional array, please set Z to zero.

:bytes

::Size in bytes of each cell of the array. Only values of 1, 2, 4 and 8 are allowed.

== Return ==

Returns a value of 1 if the allocation succeeded and a value of zero if it failed.

== Description ==

This function lets you allocate up to 100 different arrays of a user-definable size, with up to three dimensions and with up to 8 bytes per cell. 1 byte arrays have values from 0 to 255, 2 byte arrays have values from 0 to 65535, 4 byte arrays can use integer or float values and 8 byte arrays use double values.

Note that FilterMeister does not support standard C-language arrays. For this purpose FilterMeister offers you alternative functions like allocArray, putArray and getArray. Or you can dynamically allocate memory with the malloc function.

These 100 arrays are internally managed by FilterMeister and automatically freed when FilterMeister or a FM plug-in exits. So you don't necessarily need to free them yourself with freeArray, but it is recommended to do so if you don't need an array all the time.

By default, arrays are allocated by calling the host application's buffer allocation API, if it exists. This permits the host application to coordinate its memory requirements with those of the plug-in filter. If the host application does not support the buffer allocation API, or if you call set_array_mode(0), then FilterMeister will allocate arrays from the C runtime heap instead.

Basically these array functions are a replacement for the less flexible tile buffers. FilterMeister will support defining arrays as it is usually done in C in future. In the meantime please use the Array functions.

== Example ==

<code>

%ffp

//This code works for 8-bit images as well as 16-bit images

ForEveryTile:

int bitMultiply=(imageMode > 9 ? 128 : 1);

//Allocate Array Nr. 5 and make it the same size and bitdepth as the image

if (allocArray(5,X,Y,Z, imageMode>9?2:1 )) {

//Store the image data in the array

for (y=y_start; y<y_end; y++){

updateProgress(y,y_end);

for (x=x_start; x<x_end; x++){

for (z=0; z<Z; z++){

putArray(5,x,y,z, src(x,y,z) );

}}}

//Read the image data from the array

//and write it back to the image as a negative

for (y=y_start; y<y_end; y++){

updateProgress(y,y_end);

for (x=x_start; x<x_end; x++){

for (z=0; z<Z; z++){

pset(x,y,z, 255*bitMultiply - getArray(5,x,y,z) );

}}}

//Free the array

freeArray(5);

}

else

ErrorOk ("Array allocation failed");

return true;

</code>

== See Also ==

allocArrayPad, freeArray, getArray, fgetArray, putArray, fputArray, getArrayDim, copyArray, fillArray, set_array_mode