src/libtess2/tesselator.h
Go to the documentation of this file.
00001 /*
00002 ** SGI FREE SOFTWARE LICENSE B (Version 2.0, Sept. 18, 2008) 
00003 ** Copyright (C) [dates of first publication] Silicon Graphics, Inc.
00004 ** All Rights Reserved.
00005 **
00006 ** Permission is hereby granted, free of charge, to any person obtaining a copy
00007 ** of this software and associated documentation files (the "Software"), to deal
00008 ** in the Software without restriction, including without limitation the rights
00009 ** to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
00010 ** of the Software, and to permit persons to whom the Software is furnished to do so,
00011 ** subject to the following conditions:
00012 ** 
00013 ** The above copyright notice including the dates of first publication and either this
00014 ** permission notice or a reference to http://oss.sgi.com/projects/FreeB/ shall be
00015 ** included in all copies or substantial portions of the Software. 
00016 **
00017 ** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
00018 ** INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
00019 ** PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL SILICON GRAPHICS, INC.
00020 ** BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
00021 ** TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
00022 ** OR OTHER DEALINGS IN THE SOFTWARE.
00023 ** 
00024 ** Except as contained in this notice, the name of Silicon Graphics, Inc. shall not
00025 ** be used in advertising or otherwise to promote the sale, use or other dealings in
00026 ** this Software without prior written authorization from Silicon Graphics, Inc.
00027 */
00028 /*
00029 ** Author: Mikko Mononen, July 2009.
00030 */
00031 
00032 #ifndef TESSELATOR_H
00033 #define TESSELATOR_H
00034 
00035 #ifdef __cplusplus
00036 extern "C" {
00037 #endif
00038 
00039 enum TessWindingRule
00040 {
00041     TESS_WINDING_ODD,
00042     TESS_WINDING_NONZERO,
00043     TESS_WINDING_POSITIVE,
00044     TESS_WINDING_NEGATIVE,
00045     TESS_WINDING_ABS_GEQ_TWO,
00046 };
00047 
00048 // Tesselation result element types:
00049 // TESS_TRIANGLES
00050 //   Each element is defined as array of 3 TESSindex.
00051 //   The 3 values in the array defines indices to each vertex of a triangle.
00052 // TESS_CONNECTED_TRIANGLES
00053 //   Each element is defined as array of 6 TESSindex.
00054 //   The first 3 values in the array defines indices to each vertex of a triangle.
00055 //   The second 3 values in the array defines indices to each of neighbour element or -1 if there is no neighbour.
00056 // TESS_BOUNDARY_CONTOURS
00057 //   Each element is defined as array of 2 TESSindex.
00058 //   The first value is index to first vertex in contour and the second value is number of vertices in the contour.
00059 enum TessElementType
00060 {
00061     TESS_POLYGONS,
00062     TESS_CONNECTED_POLYGONS,
00063     TESS_BOUNDARY_CONTOURS,
00064 };
00065 
00066 typedef float TESSreal;
00067 typedef int TESSindex;
00068 typedef struct TESStesselator TESStesselator;
00069 typedef struct TESSalloc TESSalloc;
00070 
00071 #define TESS_UNDEF (~(TESSindex)0)
00072 
00073 // Custom memory allocator interface.
00074 // The internal memory allocator allocates mesh edges, vertices and faces
00075 // as well as dictionary nodes and active regions in buckets and uses simple
00076 // freelist to speed up the allocation. The bucket size should roughly match your
00077 // expected input data. For example if you process only hundreds of vertices,
00078 // a bucket size of 128 might be ok, where as when processing thousands of vertices
00079 // bucket size of 1024 might be approproate. The bucket size is a compromise between
00080 // how often to allocate memory from the system versus how much extra space the system
00081 // should allocate. Reasonable defaults are show in commects below, they will be used if
00082 // the bucket sizes are zero.
00083 // 
00084 // The use may left the memrealloc to be null. In that case, the tesselator will not try to
00085 // dynamically grow int's internal arrays. The tesselator only needs the reallocation when it
00086 // has found intersecting segments and needs to add new vertex. This defency can be cured by
00087 // allocating some extra vertices beforehand. The 'extraVertices' variable allows to specify
00088 // number of expected extra vertices.  
00089 struct TESSalloc
00090 {
00091     void *(*memalloc)( void *userData, unsigned int size );
00092     void *(*memrealloc)( void *userData, void* ptr, unsigned int size );
00093     void (*memfree)( void *userData, void *ptr );
00094     void* userData;             // User data passed to the allocator functions.
00095     int meshEdgeBucketSize;     // 512
00096     int meshVertexBucketSize;   // 512
00097     int meshFaceBucketSize;     // 256
00098     int dictNodeBucketSize;     // 512
00099     int regionBucketSize;       // 256
00100     int extraVertices;          // Number of extra vertices allocated for the priority queue.
00101 };
00102     
00103 // tessNewTess() - Creates a new tesselator.
00104 // Use tessDeleteTess() to delete the tesselator.
00105 // Returns:
00106 //   new tesselator object.
00107 TESStesselator* tessNewTess( TESSalloc* alloc );
00108 
00109 // tessDeleteTess() - Deletes a tesselator.
00110 // Parameters:
00111 //   tess - pointer to tesselator object to be deleted.
00112 void tessDeleteTess( TESStesselator *tess );
00113 
00114 // tessAddContour() - Adds a contour to be tesselated.
00115 // The type of the vertex coordinates is assumed to be TESSreal.
00116 // Parameters:
00117 //   tess - pointer to tesselator object.
00118 //   size - number of coordinates per vertex. Must be 2 or 3.
00119 //   pointer - pointer to the first coordinate of the first vertex in the array.
00120 //   stride - defines offset in bytes between consecutive vertices.
00121 //   count - number of vertices in contour.
00122 void tessAddContour( TESStesselator *tess, int size, const void* pointer, int stride, int count );
00123 
00124 // tessTesselate() - tesselate contours.
00125 // Parameters:
00126 //   tess - pointer to tesselator object.
00127 //   windingRule - winding rules used for tesselation, must be one of TessWindingRule.
00128 //   elementType - defines the tesselation result element type, must be one of TessElementType.
00129 //   polySize - defines maximum vertices per polygons if output is polygons.
00130 //   vertexSize - defines the number of coordinates in tesselation result vertex, must be 2 or 3.
00131 //   normal - defines the normal of the input contours, of null the normal is calculated automatically.
00132 // Returns:
00133 //   1 if succeed, 0 if failed.
00134 int tessTesselate( TESStesselator *tess, int windingRule, int elementType, int polySize, int vertexSize, const TESSreal* normal );
00135 
00136 // tessGetVertexCount() - Returns number of vertices in the tesselated output.
00137 int tessGetVertexCount( TESStesselator *tess );
00138 
00139 // tessGetVertices() - Returns pointer to first coordinate of first vertex.
00140 const TESSreal* tessGetVertices( TESStesselator *tess );
00141 
00142 // tessGetElementCount() - Returns number of elements in the the tesselated output.
00143 int tessGetElementCount( TESStesselator *tess );
00144 
00145 // tessGetElements() - Returns pointer to the first element.
00146 const TESSindex* tessGetElements( TESStesselator *tess );
00147 
00148 #ifdef __cplusplus
00149 };
00150 #endif
00151 
00152 #endif // TESSELATOR_H