contrib/gtkgensurf/triangle.h

   1 /*****************************************************************************/
   2 /*                                                                           */
   3 /*  (triangle.h)                                                             */
   4 /*                                                                           */
   5 /*  Include file for programs that call Triangle.                            */
   6 /*                                                                           */
   7 /*  Accompanies Triangle Version 1.3                                         */
   8 /*  July 19, 1996                                                            */
   9 /*                                                                           */
  10 /*  Copyright 1996                                                           */
  11 /*  Jonathan Richard Shewchuk                                                */
  12 /*  School of Computer Science                                               */
  13 /*  Carnegie Mellon University                                               */
  14 /*  5000 Forbes Avenue                                                       */
  15 /*  Pittsburgh, Pennsylvania  15213-3891                                     */
  16 /*  jrs@cs.cmu.edu                                                           */
  17 /*                                                                           */
  18 /*****************************************************************************/
  19
  20 /*****************************************************************************/
  21 /*                                                                           */
  22 /*  How to call Triangle from another program                                */
  23 /*                                                                           */
  24 /*                                                                           */
  25 /*  If you haven't read Triangle's instructions (run "triangle -h" to read   */
  26 /*  them), you won't understand what follows.                                */
  27 /*                                                                           */
  28 /*  Triangle must be compiled into an object file (triangle.o) with the      */
  29 /*  TRILIBRARY symbol defined (preferably by using the -DTRILIBRARY compiler */
  30 /*  switch).  The makefile included with Triangle will do this for you if    */
  31 /*  you run "make trilibrary".  The resulting object file can be called via  */
  32 /*  the procedure triangulate().                                             */
  33 /*                                                                           */
  34 /*  If the size of the object file is important to you, you may wish to      */
  35 /*  generate a reduced version of triangle.o.  The REDUCED symbol gets rid   */
  36 /*  of all features that are primarily of research interest.  Specifically,  */
  37 /*  the -DREDUCED switch eliminates Triangle's -i, -F, -s, and -C switches.  */
  38 /*  The CDT_ONLY symbol gets rid of all meshing algorithms above and beyond  */
  39 /*  constrained Delaunay triangulation.  Specifically, the -DCDT_ONLY switch */
  40 /*  eliminates Triangle's -r, -q, -a, -S, and -s switches.                   */
  41 /*                                                                           */
  42 /*  IMPORTANT:  These definitions (TRILIBRARY, REDUCED, CDT_ONLY) must be    */
  43 /*  made in the makefile or in triangle.c itself.  Putting these definitions */
  44 /*  in this file will not create the desired effect.                         */
  45 /*                                                                           */
  46 /*                                                                           */
  47 /*  The calling convention for triangulate() follows.                        */
  48 /*                                                                           */
  49 /*      void triangulate(triswitches, in, out, vorout)                       */
  50 /*      char *triswitches;                                                   */
  51 /*      struct triangulateio *in;                                            */
  52 /*      struct triangulateio *out;                                           */
  53 /*      struct triangulateio *vorout;                                        */
  54 /*                                                                           */
  55 /*  `triswitches' is a string containing the command line switches you wish  */
  56 /*  to invoke.  No initial dash is required.  Some suggestions:              */
  57 /*                                                                           */
  58 /*  - You'll probably find it convenient to use the `z' switch so that       */
  59 /*    points (and other items) are numbered from zero.  This simplifies      */
  60 /*    indexing, because the first item of any type always starts at index    */
  61 /*    [0] of the corresponding array, whether that item's number is zero or  */
  62 /*    one.                                                                   */
  63 /*  - You'll probably want to use the `Q' (quiet) switch in your final code, */
  64 /*    but you can take advantage of Triangle's printed output (including the */
  65 /*    `V' switch) while debugging.                                           */
  66 /*  - If you are not using the `q' or `a' switches, then the output points   */
  67 /*    will be identical to the input points, except possibly for the         */
  68 /*    boundary markers.  If you don't need the boundary markers, you should  */
  69 /*    use the `N' (no nodes output) switch to save memory.  (If you do need  */
  70 /*    boundary markers, but need to save memory, a good nasty trick is to    */
  71 /*    set out->pointlist equal to in->pointlist before calling triangulate(),*/
  72 /*    so that Triangle overwrites the input points with identical copies.)   */
  73 /*  - The `I' (no iteration numbers) and `g' (.off file output) switches     */
  74 /*    have no effect when Triangle is compiled with TRILIBRARY defined.      */
  75 /*                                                                           */
  76 /*  `in', `out', and `vorout' are descriptions of the input, the output,     */
  77 /*  and the Voronoi output.  If the `v' (Voronoi output) switch is not used, */
  78 /*  `vorout' may be NULL.  `in' and `out' may never be NULL.                 */
  79 /*                                                                           */
  80 /*  Certain fields of the input and output structures must be initialized,   */
  81 /*  as described below.                                                      */
  82 /*                                                                           */
  83 /*****************************************************************************/
  84
  85 /*****************************************************************************/
  86 /*                                                                           */
  87 /*  The `triangulateio' structure.                                           */
  88 /*                                                                           */
  89 /*  Used to pass data into and out of the triangulate() procedure.           */
  90 /*                                                                           */
  91 /*                                                                           */
  92 /*  Arrays are used to store points, triangles, markers, and so forth.  In   */
  93 /*  all cases, the first item in any array is stored starting at index [0].  */
  94 /*  However, that item is item number `1' unless the `z' switch is used, in  */
  95 /*  which case it is item number `0'.  Hence, you may find it easier to      */
  96 /*  index points (and triangles in the neighbor list) if you use the `z'     */
  97 /*  switch.  Unless, of course, you're calling Triangle from a Fortran       */
  98 /*  program.                                                                 */
  99 /*                                                                           */
 100 /*  Description of fields (except the `numberof' fields, which are obvious): */
 101 /*                                                                           */
 102 /*  `pointlist':  An array of point coordinates.  The first point's x        */
 103 /*    coordinate is at index [0] and its y coordinate at index [1], followed */
 104 /*    by the coordinates of the remaining points.  Each point occupies two   */
 105 /*    REALs.                                                                 */
 106 /*  `pointattributelist':  An array of point attributes.  Each point's       */
 107 /*    attributes occupy `numberofpointattributes' REALs.                     */
 108 /*  `pointmarkerlist':  An array of point markers; one int per point.        */
 109 /*                                                                           */
 110 /*  `trianglelist':  An array of triangle corners.  The first triangle's     */
 111 /*    first corner is at index [0], followed by its other two corners in     */
 112 /*    counterclockwise order, followed by any other nodes if the triangle    */
 113 /*    represents a nonlinear element.  Each triangle occupies                */
 114 /*    `numberofcorners' ints.                                                */
 115 /*  `triangleattributelist':  An array of triangle attributes.  Each         */
 116 /*    triangle's attributes occupy `numberoftriangleattributes' REALs.       */
 117 /*  `trianglearealist':  An array of triangle area constraints; one REAL per */
 118 /*    triangle.  Input only.                                                 */
 119 /*  `neighborlist':  An array of triangle neighbors; three ints per          */
 120 /*    triangle.  Output only.                                                */
 121 /*                                                                           */
 122 /*  `segmentlist':  An array of segment endpoints.  The first segment's      */
 123 /*    endpoints are at indices [0] and [1], followed by the remaining        */
 124 /*    segments.  Two ints per segment.                                       */
 125 /*  `segmentmarkerlist':  An array of segment markers; one int per segment.  */
 126 /*                                                                           */
 127 /*  `holelist':  An array of holes.  The first hole's x and y coordinates    */
 128 /*    are at indices [0] and [1], followed by the remaining holes.  Two      */
 129 /*    REALs per hole.  Input only, although the pointer is copied to the     */
 130 /*    output structure for your convenience.                                 */
 131 /*                                                                           */
 132 /*  `regionlist':  An array of regional attributes and area constraints.     */
 133 /*    The first constraint's x and y coordinates are at indices [0] and [1], */
 134 /*    followed by the regional attribute and index [2], followed by the      */
 135 /*    maximum area at index [3], followed by the remaining area constraints. */
 136 /*    Four REALs per area constraint.  Note that each regional attribute is  */
 137 /*    used only if you select the `A' switch, and each area constraint is    */
 138 /*    used only if you select the `a' switch (with no number following), but */
 139 /*    omitting one of these switches does not change the memory layout.      */
 140 /*    Input only, although the pointer is copied to the output structure for */
 141 /*    your convenience.                                                      */
 142 /*                                                                           */
 143 /*  `edgelist':  An array of edge endpoints.  The first edge's endpoints are */
 144 /*    at indices [0] and [1], followed by the remaining edges.  Two ints per */
 145 /*    edge.  Output only.                                                    */
 146 /*  `edgemarkerlist':  An array of edge markers; one int per edge.  Output   */
 147 /*    only.                                                                  */
 148 /*  `normlist':  An array of normal vectors, used for infinite rays in       */
 149 /*    Voronoi diagrams.  The first normal vector's x and y magnitudes are    */
 150 /*    at indices [0] and [1], followed by the remaining vectors.  For each   */
 151 /*    finite edge in a Voronoi diagram, the normal vector written is the     */
 152 /*    zero vector.  Two REALs per edge.  Output only.                        */
 153 /*                                                                           */
 154 /*                                                                           */
 155 /*  Any input fields that Triangle will examine must be initialized.         */
 156 /*  Furthermore, for each output array that Triangle will write to, you      */
 157 /*  must either provide space by setting the appropriate pointer to point    */
 158 /*  to the space you want the data written to, or you must initialize the    */
 159 /*  pointer to NULL, which tells Triangle to allocate space for the results. */
 160 /*  The latter option is preferable, because Triangle always knows exactly   */
 161 /*  how much space to allocate.  The former option is provided mainly for    */
 162 /*  people who need to call Triangle from Fortran code, though it also makes */
 163 /*  possible some nasty space-saving tricks, like writing the output to the  */
 164 /*  same arrays as the input.                                                */
 165 /*                                                                           */
 166 /*  Triangle will not free() any input or output arrays, including those it  */
 167 /*  allocates itself; that's up to you.                                      */
 168 /*                                                                           */
 169 /*  Here's a guide to help you decide which fields you must initialize       */
 170 /*  before you call triangulate().                                           */
 171 /*                                                                           */
 172 /*  `in':                                                                    */
 173 /*                                                                           */
 174 /*    - `pointlist' must always point to a list of points; `numberofpoints'  */
 175 /*      and `numberofpointattributes' must be properly set.                  */
 176 /*      `pointmarkerlist' must either be set to NULL (in which case all      */
 177 /*      markers default to zero), or must point to a list of markers.  If    */
 178 /*      `numberofpointattributes' is not zero, `pointattributelist' must     */
 179 /*      point to a list of point attributes.                                 */
 180 /*    - If the `r' switch is used, `trianglelist' must point to a list of    */
 181 /*      triangles, and `numberoftriangles', `numberofcorners', and           */
 182 /*      `numberoftriangleattributes' must be properly set.  If               */
 183 /*      `numberoftriangleattributes' is not zero, `triangleattributelist'    */
 184 /*      must point to a list of triangle attributes.  If the `a' switch is   */
 185 /*      used (with no number following), `trianglearealist' must point to a  */
 186 /*      list of triangle area constraints.  `neighborlist' may be ignored.   */
 187 /*    - If the `p' switch is used, `segmentlist' must point to a list of     */
 188 /*      segments, `numberofsegments' must be properly set, and               */
 189 /*      `segmentmarkerlist' must either be set to NULL (in which case all    */
 190 /*      markers default to zero), or must point to a list of markers.        */
 191 /*    - If the `p' switch is used without the `r' switch, then               */
 192 /*      `numberofholes' and `numberofregions' must be properly set.  If      */
 193 /*      `numberofholes' is not zero, `holelist' must point to a list of      */
 194 /*      holes.  If `numberofregions' is not zero, `regionlist' must point to */
 195 /*      a list of region constraints.                                        */
 196 /*    - If the `p' switch is used, `holelist', `numberofholes',              */
 197 /*      `regionlist', and `numberofregions' is copied to `out'.  (You can    */
 198 /*      nonetheless get away with not initializing them if the `r' switch is */
 199 /*      used.)                                                               */
 200 /*    - `edgelist', `edgemarkerlist', `normlist', and `numberofedges' may be */
 201 /*      ignored.                                                             */
 202 /*                                                                           */
 203 /*  `out':                                                                   */
 204 /*                                                                           */
 205 /*    - `pointlist' must be initialized (NULL or pointing to memory) unless  */
 206 /*      the `N' switch is used.  `pointmarkerlist' must be initialized       */
 207 /*      unless the `N' or `B' switch is used.  If `N' is not used and        */
 208 /*      `in->numberofpointattributes' is not zero, `pointattributelist' must */
 209 /*      be initialized.                                                      */
 210 /*    - `trianglelist' must be initialized unless the `E' switch is used.    */
 211 /*      `neighborlist' must be initialized if the `n' switch is used.  If    */
 212 /*      the `E' switch is not used and (`in->numberofelementattributes' is   */
 213 /*      not zero or the `A' switch is used), `elementattributelist' must be  */
 214 /*      initialized.  `trianglearealist' may be ignored.                     */
 215 /*    - `segmentlist' must be initialized if the `p' or `c' switch is used,  */
 216 /*      and the `P' switch is not used.  `segmentmarkerlist' must also be    */
 217 /*      initialized under these circumstances unless the `B' switch is used. */
 218 /*    - `edgelist' must be initialized if the `e' switch is used.            */
 219 /*      `edgemarkerlist' must be initialized if the `e' switch is used and   */
 220 /*      the `B' switch is not.                                               */
 221 /*    - `holelist', `regionlist', `normlist', and all scalars may be ignored.*/
 222 /*                                                                           */
 223 /*  `vorout' (only needed if `v' switch is used):                            */
 224 /*                                                                           */
 225 /*    - `pointlist' must be initialized.  If `in->numberofpointattributes'   */
 226 /*      is not zero, `pointattributelist' must be initialized.               */
 227 /*      `pointmarkerlist' may be ignored.                                    */
 228 /*    - `edgelist' and `normlist' must both be initialized.                  */
 229 /*      `edgemarkerlist' may be ignored.                                     */
 230 /*    - Everything else may be ignored.                                      */
 231 /*                                                                           */
 232 /*  After a call to triangulate(), the valid fields of `out' and `vorout'    */
 233 /*  will depend, in an obvious way, on the choice of switches used.  Note    */
 234 /*  that when the `p' switch is used, the pointers `holelist' and            */
 235 /*  `regionlist' are copied from `in' to `out', but no new space is          */
 236 /*  allocated; be careful that you don't free() the same array twice.  On    */
 237 /*  the other hand, Triangle will never copy the `pointlist' pointer (or any */
 238 /*  others); new space is allocated for `out->pointlist', or if the `N'      */
 239 /*  switch is used, `out->pointlist' remains uninitialized.                  */
 240 /*                                                                           */
 241 /*  All of the meaningful `numberof' fields will be properly set; for        */
 242 /*  instance, `numberofedges' will represent the number of edges in the      */
 243 /*  triangulation whether or not the edges were written.  If segments are    */
 244 /*  not used, `numberofsegments' will indicate the number of boundary edges. */
 245 /*                                                                           */
 246 /*****************************************************************************/
 247
 248 #ifdef __cplusplus
 249 extern "C" {
 250 #endif
 251
 252 struct triangulateio {
 253   REAL *pointlist;                                               /* In / out */
 254   REAL *pointattributelist;                                      /* In / out */
 255   int *pointmarkerlist;                                          /* In / out */
 256   int numberofpoints;                                            /* In / out */
 257   int numberofpointattributes;                                   /* In / out */
 258
 259   int *trianglelist;                                             /* In / out */
 260   REAL *triangleattributelist;                                   /* In / out */
 261   REAL *trianglearealist;                                         /* In only */
 262   int *neighborlist;                                             /* Out only */
 263   int numberoftriangles;                                         /* In / out */
 264   int numberofcorners;                                           /* In / out */
 265   int numberoftriangleattributes;                                /* In / out */
 266
 267   int *segmentlist;                                              /* In / out */
 268   int *segmentmarkerlist;                                        /* In / out */
 269   int numberofsegments;                                          /* In / out */
 270
 271   REAL *holelist;                        /* In / pointer to array copied out */
 272   int numberofholes;                                      /* In / copied out */
 273
 274   REAL *regionlist;                      /* In / pointer to array copied out */
 275   int numberofregions;                                    /* In / copied out */
 276
 277   int *edgelist;                                                 /* Out only */
 278   int *edgemarkerlist;            /* Not used with Voronoi diagram; out only */
 279   REAL *normlist;                /* Used only with Voronoi diagram; out only */
 280   int numberofedges;                                             /* Out only */
 281 };
 282
 283 void triangulate(char *, struct triangulateio *, struct triangulateio *,
 284                  struct triangulateio *);
 285
 286 #ifdef __cplusplus
 287 }
 288 #endif