Execution

Once the calling program has initialized the library, set any of the desired parameters, and populated the input arrays with data it will call the main fucntion Boolean_MT. This is where the actual "work" gets done.

Syntax:

int Boolean_MT
 (int*** XY_arr,int** pair_num_arr, int * N,
  int** XY1_arr, int * pair_num1_arr, int N1, 
  int** XY2_arr, int * pair_num2_arr, int N2,
  int code,

Function:

this is the core boolean function call. It takes as input two sets of input geometric data (polygons stored in arrays) and produces an array of output polygons based on the operation code selected. Prior to calling Boolean_MT, the caller should first set up the various parameters that "flavor" the operations. After calling Boolean_MT and using the results, the caller should release the memory.

Inputs:

int** XY1_arr - an array of pointers - each element in the array points to the memory location where the coordinates for the polygon are stored. See illustration.

int * pair_num1_arr - an array where each element contains the number of vertices in that polygon.

int N1 - integer - number of polygons in this set.

int** XY2_arr - an second array of pointers - each element in this second array points to the memory location where the coordinates for the polygon are stored.

int * pair_num2_arr - an array where each element contains the number of vertices in that polygon.

int N2 - integer - number of polygons in this set.

int code - boolean operation, one of the following: UNION_OPCODE, DIFFERENCE_OPCODE,XOR_OPCODE,INTERSECTION_OPCODE

bdll_handle - the thread handle.

Output

int*** XY_arr - an array of pointers each pointing to the array element of polygon coordinates.

pair_num_arr - an array where each element is the number of vertices in the returned polygon.

Return Codes:

Notes

Implicit Union - operations Difference, XOR and intersection all require that each of the two input sets are first unionized. This is done automatically and need not be explicitly called by the user.

In the case that there is no second operand (for example, union of a single array of polygons) then set XY2_arr, pair_num2_arr, and N2 to NULL,NULL,0 respectively.

Syntax:

int DoBinary_MT
    (int*** XY_out_arr, int** pair_num_out_arr, int* Nout,
     int** XY_in_arr1, int* pair_num_in_arr1, int Polys1,
     int** XY_in_arr2, int* pair_num_in_arr2, int Polys2,
     short index, short thrnum, short operation);

Function:

both this function (and Boolean_MT) are thread safe - however this function is internally multi-threaded and does automatic partitioning of the data. For large datasets where the standard function would bog down (due to n² compute time) this one scales closer to linear. This function always has two operands.

Arguments

int*** XY_out_arr - an array of pointers to the X,Y coordinates for the output polygons.

int** pair_num_out_arr an array where each element contains the number of vertex pairs for the output polygon.

int* Nout - number of output polygons.

int** XY_in_arr1 - an array of pointers for the first operand - each element in the array points to the memory location where the first coordinate of each polygon is stored.

int* pair_num_in_arr1 - an array where each element contains the number of vertex pairs for that polygon.

int Polys1 - integer - number of polygons in the first operand.

int** XY_in_arr2 - an array of pointers for the second operand - each element in the array points to the memory location of the first coordinate of each polygon in the collection.

int* pair_num_in_arr2 - an array where each element contains the number of vertices in that polygon.

int Polys2 - integer - number of polygons in the second operand.

short index - the index number (handle) returned by a prior call to BoolDllInit_MT()

short threadnum - tells the library how many threads should be used for performing the desired operation.

short operation - geometric boolean operation, one of the following: DIFFERENCE_OPCODE, XOR_OPCODE or INTERSECTION_OPCODE

Output

int*** XY_arr - the address of an array of pointers for the output polygons.

int** pair_num_arr - address of the array containing the number of vertices for each of the returned polygons.

int* N - the address of the number of output polygons.

Return Codes:

 0 if no errors.

-2 if the number of requested threads exceeds the maximum ( 64 ).

Notes

Implicit Union - operations Difference, XOR and intersection all require that each of the two input sets are first unionized. This is done automatically and need not be explicitly called by the user.

Syntax:

int DoUnion_MT
    (int*** XY_out_arr, int** pair_num_out_arr, int* Nout,
     int** XY_in_arr, int* pair_num_in_arr, int Polys,
     short index, short thrnum
     );

Function:

both this function (and Boolean_MT) are thread safe - however this function is internally multi-threaded and does automatic partitioning of the data. For large datasets where the standard function would bog down (due to n² compute time) this one scales closer to linear. This function has only a single operand.

Arguments

int*** XY_out_arr - an array of pointers to the X,Y coordinates for the output polygons.

int** pair_num_out_arr an array where each element contains the number of vertex pairs for the output polygon.

int* Nout - number of output polygons.

int** XY_in_arr - an array of pointers for the polygons - each element in the array points to the memory location where the first coordinate of each polygon is stored.

int* pair_num_in_arr - an array where each element contains the number of vertex pairs for that polygon.

int Polys - integer - number of polygons in the first operand.

short index - the index number (handle) returned by a prior call to BoolDllInit_MT()

short threadnum - tells the library how many threads should be used for performing the desired operation.

Output

int*** XY_out_arr - the address of an array of pointers for the output polygons.

int** pair_num_out_arr - address of the array containing the number of vertices for each of the returned polygons.

int* Nout - the address of the number of output polygons.

Return Codes:

 0 if no errors.

-2 if the number of requested threads exceeds the maximum ( 64 ).

Syntax:

int Deembedding
          ( int** XY1_arr, int* pair_num1_arr, int N1, 
            int*** XY_arr, int** pair_num_arr, int* N, 
            int index
          );

Function:

A special union operation which differs from standard union. The intent is to group polygons based on whether they are fully contained by a "parent" polgyon. Examples and illustrations can be found here.

Inputs:

int** XY1_arr - an array of pointers for the polygons - each element in the array points to the memory location where the first coordinate of each polygon is stored.

int* pair_num1_arr - an array where each element contains the number of vertex pairs for that polygon.

int N1 - number of polygons in the input array.

short index - a thread index obtained by calling BoolDllInit_MT()

Output

int*** XY_arr - the address of an array of pointers for the output polygons.

int** pair_num_arr - address of the array containing the number of vertices for each of the returned polygons. A negative value for vertex count indicates that this is a child polygon.

int* N - the address of the number of output polygons.

Return Codes:

 0 if no errors.