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