Older Newer
Sun, 27 Dec 2009 15:49:22 . . . . 41.249.24.227 [removed spam link]


Changes by last author:

Added:
= 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.

<code>

</code>

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

<code>

</code>

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

<code>

</code>

:Basically these array funtions 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>

== Also see ==

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

== Comments ==

:Everyone can add his comments about his experiences with this function here. Tips for using it are welcome, too.