r34526 removed a line which had an unused return value but still needed to run.
[blender-staging.git] / intern / bsp / extern / CSG_BooleanOps.h
1 /**
2  * $Id$
3  * ***** BEGIN GPL LICENSE BLOCK *****
4  *
5  * This program is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU General Public License
7  * as published by the Free Software Foundation; either version 2
8  * of the License, or (at your option) any later version.
9  *
10  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU General Public License for more details.
14  *
15  * You should have received a copy of the GNU General Public License
16  * along with this program; if not, write to the Free Software Foundation,
17  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18  *
19  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
20  * All rights reserved.
21  *
22  * The Original Code is: all of this file.
23  *
24  * Contributor(s): none yet.
25  *
26  * ***** END GPL LICENSE BLOCK *****
27  */
28
29 #ifndef CSG_BOOLEANOPS_H
30 #define CSG_BOOLEANOPS_H
31
32
33 /**
34  * @section Interface structures for CSG module.
35  * This interface falls into 2 categories.
36  * The first section deals with an abstract mesh description 
37  * between blender and this module. The second deals with 
38  * the module functions. 
39  * The CSG module needs to know about the following entities:
40  */
41
42 /**
43  * CSG_IFace -- an interface polygon structure. 
44  * vertex_index is a fixed size array of 4 elements containing indices into
45  * an abstract vertex container. 3 or 4 of these elements may be used to
46  * describe either quads or triangles.
47  * vertex_number is the number of vertices in this face - either 3 or 4.
48  * vertex_colors is an array of {r,g,b} triplets one for each vertex index.
49  * tex_coords is an array of {u,v} triplets one for each vertex index.
50  * user_data is a pointer to arbitary data of fixed width ,
51  * this data is copied around with the face, and duplicated if a face is
52  * split. Contains things like material index. 
53  */
54
55 #ifdef __cplusplus
56 extern "C" {
57 #endif
58
59 typedef struct  {
60   int vertex_index[4];
61   int vertex_number;
62   int orig_face;
63 } CSG_IFace;
64
65 /**
66  * CSG_IVertex -- an interface vertex structure.
67  * position is the location of the vertex in 3d space.
68  */
69
70 typedef struct  {
71   float position[3];
72 } CSG_IVertex;
73
74 /**
75  * The actual useful data contained in a group of faces is
76  * described by the following struct
77  */
78
79 /**
80  * @section Iterator abstraction.
81  * 
82  * The CSG module asks blender to fill in an instance of the above
83  * structure, and requests blender to move up and down (iterate) through
84  * it's face and vertex containers.
85  * 
86  * An iterator supports the following functions.
87  * int IsDone(iterator *it)  -- returns true if the iterator has reached
88  * the end of it's container.
89  *
90  * void Fill(iterator *it,DataType *data) -- Return the contents of the
91  * container at the current iterator position.
92  *
93  * void Step(iterator *it) -- increment the iterator to the next position
94  * in the container. 
95  *
96  * The iterator is used in the following manner.
97  * 
98  *   MyIterator * iterator = ... 
99  *   DataType data; 
100  * 
101  *   while (!IsDone(iterator)) {
102  *              Fill(iterator,&data);
103  *              //process information pointed to by data 
104  *              ...
105  *              Step(iterator);
106  *       } 
107  * 
108  * The CSG module does not want to know about the implementation of these
109  * functions  so we use the c function ptr mechanism to hide them. Our
110  * iterator descriptor now looks like this.
111  */
112
113 typedef void* CSG_IteratorPtr;
114
115 typedef int (*CSG_FaceItDoneFunc)(CSG_IteratorPtr it);
116 typedef void (*CSG_FaceItFillFunc)(CSG_IteratorPtr it,CSG_IFace *face);
117 typedef void (*CSG_FaceItStepFunc)(CSG_IteratorPtr it);
118 typedef void (*CSG_FaceItResetFunc)(CSG_IteratorPtr it);
119
120 typedef struct CSG_FaceIteratorDescriptor {
121         CSG_IteratorPtr it;
122         CSG_FaceItDoneFunc Done;
123         CSG_FaceItFillFunc Fill;
124         CSG_FaceItStepFunc Step;
125         CSG_FaceItResetFunc Reset;
126         unsigned int num_elements;
127 } CSG_FaceIteratorDescriptor; 
128
129 /**
130  * Similarly to walk through the vertex arrays we have.
131  */
132 typedef int (*CSG_VertexItDoneFunc)(CSG_IteratorPtr it);
133 typedef void (*CSG_VertexItFillFunc)(CSG_IteratorPtr it,CSG_IVertex *face);
134 typedef void (*CSG_VertexItStepFunc)(CSG_IteratorPtr it);
135 typedef void (*CSG_VertexItResetFunc)(CSG_IteratorPtr it);
136
137 typedef struct CSG_VertexIteratorDescriptor {
138         CSG_IteratorPtr it;
139         CSG_VertexItDoneFunc Done;
140         CSG_VertexItFillFunc Fill;
141         CSG_VertexItStepFunc Step;
142         CSG_VertexItResetFunc Reset;
143         unsigned int num_elements;
144 } CSG_VertexIteratorDescriptor; 
145
146 /**
147  * The actual iterator structures are not exposed to the CSG module, they
148  * will contain datatypes specific to blender.
149  */
150
151 /**
152  * @section CSG Module interface functions.
153  * 
154  * The functions below are to be used in the following way:
155  * 
156  *  // Create a boolean operation handle
157  *  CSG_BooleanOperation *operation = CSG_NewBooleanFunction();
158  *  if (operation == NULL) {
159  *              // deal with low memory exception
160  *  }
161  *
162  *  // Report to the user if they will loose any data!
163  *  ...
164  * 
165  *  // Get some mesh iterators for your mesh data structures
166  *  CSG_FaceIteratorDescriptor obA_faces = ...
167  *  CSG_VertexIteratorDescriptor obA_verts = ...
168  *  
169  *  // same for object B
170  *  CSG_FaceIteratorDescriptor obB_faces = ...
171  *  CSG_VertexIteratorDescriptor obB_verts = ...
172  *  
173  *  // perform the operation...!
174  *
175  *  int success = CSG_PerformBooleanOperation(
176  *     operation,
177  *     e_csg_intersection,
178  *     obA_faces,
179  *     obA_vertices,
180  *     obB_faces,
181  *     obB_vertices
182  *  );
183  *
184  *  // if the operation failes report miserable faiulre to user
185  *  // and clear up data structures.
186  *  if (!success) {
187  *    ...
188  *    CSG_FreeBooleanOperation(operation);
189  *    return;
190  *  }
191  *
192  *  // read the new mesh vertices back from the module
193  *  // and assign to your own mesh structure.
194  *
195  *  // First we need to create a CSG_IVertex so the module can fill it in.
196  *  CSG_IVertex vertex;
197  *  CSG_VertexIteratorDescriptor * verts_it = CSG_OutputVertexDescriptor(operation);
198  *
199  *  // initialize your vertex container with the number of verts (verts_it->num_elements)
200  * 
201  *  while (!verts_it->Done(verts_it->it)) {
202  *              verts_it->Fill(verts_it->it,&vertex);
203  *
204  *      // create a new vertex of your own type and add it
205  *      // to your mesh structure.
206  *      verts_it->Step(verts_it->it);
207  *  }
208  *  // Free the vertex iterator
209  *      CSG_FreeVertexDescriptor(verts_it);
210  * 
211  *  // similarly for faces.
212  *  CSG_IFace face;
213  *
214  *  // you may need to reserve some memory in face->user_data here.
215  * 
216  *  // initialize your face container with the number of faces (faces_it->num_elements)
217  * 
218  *  CSG_FaceIteratorDescriptor * faces_it = CSG_OutputFaceDescriptor(operation);
219  * 
220  *  while (!faces_it->Done(faces_it->it)) {
221  *              faces_it->Fill(faces_it->it,&face);
222  *
223  *      // create a new face of your own type and add it
224  *      // to your mesh structure.
225  *      faces_it->Step(&faces_it->it);
226  *  }
227  *      
228  *  // Free the face iterator
229  *      CSG_FreeVertexDescriptor(faces_it);
230  *
231  *  // that's it free the operation.
232  *
233  *  CSG_FreeBooleanOperation(operation);
234  *  return;
235  *  
236  */
237
238 /**
239  * Description of boolean operation type.
240  */
241
242 typedef enum {
243         e_csg_union,
244         e_csg_intersection,
245         e_csg_difference,
246         e_csg_classify
247 } CSG_OperationType;
248
249 /**
250  * 'Handle' into the CSG module that identifies a particular CSG operation.
251  *  the pointer CSG_info containers module specific data, and should not
252  *  be touched in anyway outside of the module.
253  */
254
255 typedef struct {
256         void *CSG_info;
257 } CSG_BooleanOperation;
258
259 /**
260  * Return a ptr to a CSG_BooleanOperation object allocated
261  * on the heap. The CSG module owns the memory associated with 
262  * the returned ptr, use CSG_FreeBooleanOperation() to free this memory.
263  */
264         CSG_BooleanOperation * 
265 CSG_NewBooleanFunction(
266         void
267 );
268
269 /**
270  * Attempt to perform a boolean operation between the 2 objects of the 
271  * desired type. This may fail due to an internal error or lack of memory.
272  * In this case 0 is returned, otehrwise 1 is returned indicating success.
273  * @param operation is a 'handle' into the CSG_Module created by CSG_NewBooleanFunction()
274  * @param op_type is the operation to perform.
275  * @param obAFaces is an iterator over the faces of objectA,
276  * @param obAVertices is an iterator over the vertices of objectA
277  * @param obAFaces is an iterator over the faces of objectB,
278  * @param obAVertices is an iterator over the vertices of objectB
279  * @param interp_func the face_vertex data interpolation function.(see above)
280  * 
281  * All iterators must be valid and pointing to the first element in their
282  * respective containers.
283  */
284         int
285 CSG_PerformBooleanOperation(
286         CSG_BooleanOperation * operation,
287         CSG_OperationType op_type,
288         CSG_FaceIteratorDescriptor obAFaces,
289         CSG_VertexIteratorDescriptor obAVertices,
290         CSG_FaceIteratorDescriptor obBFaces,
291         CSG_VertexIteratorDescriptor obBVertices
292 );
293
294 /**
295  * If the a boolean operation was successful, you may access the results
296  * through the following functions.
297  *
298  * CSG_OuputFaceDescriptor() returns a ptr to a CSG_FaceIteratorDesciptor 
299  * allocated on the heap and owned by the CSG module. The iterator is
300  * positioned at the start of the internal face container.
301  * CSG_OutputVertexDescriptor() returns a ptr to a CSG_VertexIteratorDescriptor
302  * allocated on the heap and owned by the CSG module. The iterator is
303  * positioned at the start of the internal vertex container.
304  * There is no function to rewind an iterator but you may obtain more
305  * than one
306  * iterator at a time. Please use the function CSG_FreeFaceIterator()
307  * and CSG_FreeVertexIterator to free internal memory allocated for these
308  * iterators.
309  * 
310  * If the last operation was not successful, these functions return NULL.
311  */
312         int
313 CSG_OutputFaceDescriptor(
314         CSG_BooleanOperation * operation,
315         CSG_FaceIteratorDescriptor * output
316 );
317
318         int
319 CSG_OutputVertexDescriptor(
320         CSG_BooleanOperation * operation,
321         CSG_VertexIteratorDescriptor *output
322 );
323
324 /**
325  * Clean up functions.
326  * Free internal memory associated with CSG interface structures. You must
327  * call these functions on any structures created by the module, even if
328  * subsequent operations did not succeed.
329  */
330         void
331 CSG_FreeVertexDescriptor(
332         CSG_VertexIteratorDescriptor * v_descriptor
333 );
334
335         void
336 CSG_FreeFaceDescriptor(
337         CSG_FaceIteratorDescriptor * f_descriptor
338 );
339
340 /**
341  * Free the memory associated with a boolean operation. 
342  * NOTE any iterator descriptor describing the output will become
343  * invalid after this call and should be freed immediately.
344  */
345         void
346 CSG_FreeBooleanOperation(
347         CSG_BooleanOperation *operation
348 );
349
350 #ifdef __cplusplus
351 }
352 #endif
353
354
355
356 #endif
357