Boolean API

For sample usage please see at test.cpp in test project.

Prerequisite

Copy ivmodule.dll to your project. Folder is not improtant. For 32 bit project use 32 bit version, for 64 bit project use 64 bit version.

Include ivboolean.h and declare pointers to 3 functions: iv3dInit, iv3dDone, iv3dCreate. Where iv3dInit - initialization of module, iv3dDone - destroying 3d module. iv3dCreate - create boolean processor object.

IV3DINIT iv3dInit=NULL;
	  IV3DDONE iv3dDone=NULL;
	  IVBOOLCREATEPROC iv3dCreate=NULL;
	  HINSTANCE ivModule=0;

This may be global variables or data members of any object, structure. Naming is not critical. Load and initialize dll only once. You may execute boolean operation many times from multiple threads.

Loading

Implementation below is quite standard.

bool MyLoadLibrary()
{
	HINSTANCE hi=LoadLibraryExA("ivmodule.dll",NULL,LOAD_WITH_ALTERED_SEARCH_PATH);
	if(hi)
	{
		iv3dCreate=(IVBOOLCREATEPROC )GetProcAddress(hi,"ivCreateBoolean");
		iv3dInit=(IV3DINIT)GetProcAddress(hi,"iv3dInit");
		iv3dDone=(IV3DDONE)GetProcAddress(hi,"iv3dDone");
		ivModule=hi;
		if(iv3dCreate && iv3dInit && iv3dDone)
		{
			iv3dInit();
			return true;
		};
	}
	return false;
}

This function, loads dll, locates 3 functions and in case if all functions were found, initialises 3d library.

Boolean Operation

Firstly you need to create boolean processor:

ivbool3d::Processor*proc=iv3dCreate();

It is safe to call it from any thread.

Source Data

Now you should define source objects - A and B. Each operand can be made from many objects. You should avoid self intersections on your own. Source object is created with AddSource method. Parameter is type of operand. 0 - A, 1- B.

ivbool3d::Object*obj=proc->AddSource(0);//A channel

Points

Vertices are defined with function: obj->SetPoints, parameters are array of points and number of points. Each point is made of 3 float components: x,yz.

Normals: obj->SetNormals. Normal is same 3d point

UV Coordinates: obj->SetUV. Each component is made of two float values.

Vertices should be added before faces. UV and Normals are optional, but if you want to process them, you should provide separate UV and normal faces.

Faces

Firstly you should define number of faces with help of obj->SetNumFaces method.

Each face can have different number of points. In case of 3 it will be triangle, 4 - quad, etc. Polygons will be triangulated automatically. Face is created with obj->NewFace method. Parameters are: number of points in face and pointer into array of indices. Method returns index of face. In case of no errors, index is incremented from 0 to numFaces-1.

Normal faces should be created with SetNormalFace method. First parameter is index of face, second indices to array of normals.

UV faces should be created with SetUVFace0 method. First parameter is index of face, second indices to array of UV coordinates. For second UV channel, use SetUVFace1, etc. Different UV channes share same array of UV coordinates.

Material index may be set with SetMtlID method. First parameter is index of face, second - index of material.

Execution

When source objects are set, call Process method.

First parameter is type of boolean operation: OR, AND, SUB, CUT, UNION and variations.

Second parameter is combinations of flags:

• REDUCE - Reduce number of triangles by combining small triangles into one face, improve mesh quality, etc. For customizing reduce operation please use SetReduceProps method.
• DEBUG_LOG - output logging information into Output window of Visual Studio.
• POLYGONISE - restore polygons from triangles. Use SetMaxPolySize in order to customize polygionization process.
• POLYGONISE_HOLES - detect holes in polygons and convert them into holes (Polygon with holes).

Get Results

If process was successfull, you may call GetResult method and get constructed object. This method return object and you should use it's method in order to retrieve points, normals, uv, faces.

• GetPoints - returns pointer to internall array of points and number of points in array.
• GetNormals - returns pointer to internall array of normals and number of items in array.
• GetUV - returns pointer to internall array of UV points and number of items in array.
• GetNumFaces - returns number of faces.
• GetFace - returns information about face. Information contains: size of face, indices to points, normals, uv, holes, etc.

Next Boolean operation

After first execution, you may destroy boolean object by calling Destroy metod, create new boolean object via iv3dCreate. Or you may clear boolean object with call Reset method instead. This will prepare boolean object for next operation. Second way may be little bit faster.

Destroying

On done, call iv3dDone function and unload dll with FreeLibrary function.

Debugging

If you have problems with filling in source objects, you may save current state to finalmesh file, load it into finalmesh and check. In order to do that, before calling Process, call dbgSetSaveFileName method with name of finalmesh file. After this, during execution of Process method, file will be saved and ready for inspection.