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

%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;
}

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.