geos_c.h

00001 /************************************************************************
00002  *
00003  * $Id: geos_c.h.in 2027 2007-09-21 17:40:15Z csavage $
00004  *
00005  * C-Wrapper for GEOS library
00006  *
00007  * Copyright (C) 2005 Refractions Research Inc.
00008  *
00009  * This is free software; you can redistribute and/or modify it under
00010  * the terms of the GNU Lesser General Public Licence as published
00011  * by the Free Software Foundation. 
00012  * See the COPYING file for more information.
00013  *
00014  * Author: Sandro Santilli <strk@refractions.net>
00015  *
00016  ***********************************************************************
00017  *
00018  * GENERAL NOTES:
00019  *
00020  *      - Remember to call initGEOS() before any use of this library's
00021  *        functions, and call finishGEOS() when done.
00022  *
00023  *      - Currently you have to explicitly GEOSGeom_destroy() all
00024  *        GEOSGeom objects to avoid memory leaks, and to free()
00025  *        all returned char * (unless const). This might change
00026  *        before first release to ensure greater API stability.
00027  *
00028  ***********************************************************************/
00029 
00030 #ifndef GEOS_C_H
00031 #define GEOS_C_H
00032 
00033 #ifndef __cplusplus
00034 # include <stddef.h> /* for size_t definition */
00035 #endif
00036 
00037 #ifdef __cplusplus
00038 extern "C" {
00039 #endif
00040 
00041 /************************************************************************
00042  *
00043  * Version
00044  *
00045  ***********************************************************************/
00046 
00047 /*
00048  * Following 'ifdef' hack fixes problem with generating geos_c.h on Windows,
00049  * when building with Visual C++ compiler.
00050  */
00051 #if defined(_MSC_VER)
00052 #include <geos/version.h>
00053 #define GEOS_CAPI_VERSION_MAJOR 1
00054 #define GEOS_CAPI_VERSION_MINOR 3
00055 #define GEOS_CAPI_VERSION_PATCH 3
00056 #define GEOS_CAPI_VERSION "3.0.0rc4-CAPI-1.3.3"
00057 #else
00058 #define GEOS_VERSION_MAJOR 3
00059 #define GEOS_VERSION_MINOR 0
00060 #define GEOS_VERSION_PATCH 0
00061 #define GEOS_VERSION "3.0.0"
00062 #define GEOS_JTS_PORT "1.7.1"
00063 
00064 #define GEOS_CAPI_VERSION_MAJOR 1
00065 #define GEOS_CAPI_VERSION_MINOR 4
00066 #define GEOS_CAPI_VERSION_PATCH 1
00067 #define GEOS_CAPI_VERSION "3.0.0-CAPI-1.4.1"
00068 #endif 
00069 
00070 #define GEOS_CAPI_FIRST_INTERFACE GEOS_CAPI_VERSION_MAJOR 
00071 #define GEOS_CAPI_LAST_INTERFACE (GEOS_CAPI_VERSION_MAJOR+GEOS_CAPI_VERSION_MINOR)
00072  
00073 /************************************************************************
00074  *
00075  * (Abstract) type definitions
00076  *
00077  ***********************************************************************/
00078 
00079 typedef void (*GEOSMessageHandler)(const char *fmt, ...);
00080 
00081 /* When we're included by geos_c.cpp, those are #defined to the original
00082  * JTS definitions via preprocessor. We don't touch them to allow the
00083  * compiler to cross-check the declarations. However, for all "normal" 
00084  * C-API users, we need to define them as "opaque" struct pointers, as 
00085  * those clients don't have access to the original C++ headers, by design.
00086  */
00087 #ifndef GEOSGeometry
00088 typedef struct GEOSGeom_t GEOSGeometry;
00089 typedef struct GEOSCoordSeq_t GEOSCoordSequence;
00090 #endif
00091 
00092 /* Those are compatibility definitions for source compatibility
00093  * with GEOS 2.X clients relying on that type.
00094  */
00095 typedef GEOSGeometry* GEOSGeom;
00096 typedef GEOSCoordSequence* GEOSCoordSeq;
00097 
00098 /* Supported geometry types
00099  * This was renamed from GEOSGeomTypeId in GEOS 2.2.X, which might
00100  * break compatibility, this issue is still under investigation.
00101  */
00102 
00103 enum GEOSGeomTypes {
00104         GEOS_POINT,
00105         GEOS_LINESTRING,
00106         GEOS_LINEARRING,
00107         GEOS_POLYGON,
00108         GEOS_MULTIPOINT,
00109         GEOS_MULTILINESTRING,
00110         GEOS_MULTIPOLYGON,
00111         GEOS_GEOMETRYCOLLECTION
00112 };
00113 
00114 /* Byte oders exposed via the c api */
00115 enum GEOSByteOrders {
00116         GEOS_WKB_XDR = 0, /* Big Endian */
00117         GEOS_WKB_NDR = 1 /* Little Endian */
00118 };
00119 
00120 
00121 /************************************************************************
00122  *
00123  * Initialization, cleanup, version
00124  *
00125  ***********************************************************************/
00126 
00127 #if defined(_MSC_VER)
00128 #  define GEOS_DLL     __declspec(dllexport)
00129 #else
00130 #  define GEOS_DLL
00131 #endif
00132 
00133 extern void GEOS_DLL initGEOS(GEOSMessageHandler notice_function,
00134         GEOSMessageHandler error_function);
00135 extern void GEOS_DLL finishGEOS(void);
00136 extern const char GEOS_DLL *GEOSversion();
00137 
00138 
00139 /************************************************************************
00140  *
00141  * NOTE - These functions are DEPRECATED.  Please use the new Reader and
00142  * writer APIS!
00143  *
00144  ***********************************************************************/
00145 
00146 extern GEOSGeometry GEOS_DLL *GEOSGeomFromWKT(const char *wkt);
00147 extern char GEOS_DLL *GEOSGeomToWKT(const GEOSGeometry* g);
00148 
00149 /*
00150  * Specify whether output WKB should be 2d or 3d.
00151  * Return previously set number of dimensions.
00152  */
00153 extern int GEOS_DLL GEOS_getWKBOutputDims();
00154 extern int GEOS_DLL GEOS_setWKBOutputDims(int newDims);
00155 
00156 /*
00157  * Specify whether the WKB byte order is big or little endian. 
00158  * The return value is the previous byte order.
00159  */
00160 extern int GEOS_DLL GEOS_getWKBByteOrder();
00161 extern int GEOS_DLL GEOS_setWKBByteOrder(int byteOrder);
00162 
00163 extern GEOSGeometry GEOS_DLL *GEOSGeomFromWKB_buf(const unsigned char *wkb, size_t size);
00164 extern unsigned char GEOS_DLL *GEOSGeomToWKB_buf(const GEOSGeometry* g, size_t *size);
00165 
00166 extern GEOSGeometry GEOS_DLL *GEOSGeomFromHEX_buf(const unsigned char *hex, size_t size);
00167 extern unsigned char GEOS_DLL *GEOSGeomToHEX_buf(const GEOSGeometry* g, size_t *size);
00168 
00169 /************************************************************************
00170  *
00171  * Coordinate Sequence functions
00172  *
00173  ***********************************************************************/
00174 
00175 /*
00176  * Create a Coordinate sequence with ``size'' coordinates
00177  * of ``dims'' dimensions.
00178  * Return NULL on exception.
00179  */
00180 extern GEOSCoordSequence GEOS_DLL *GEOSCoordSeq_create(unsigned int size, unsigned int dims);
00181 
00182 /*
00183  * Clone a Coordinate Sequence.
00184  * Return NULL on exception.
00185  */
00186 extern GEOSCoordSequence GEOS_DLL *GEOSCoordSeq_clone(const GEOSCoordSequence* s);
00187 
00188 /*
00189  * Destroy a Coordinate Sequence.
00190  */
00191 extern void GEOS_DLL GEOSCoordSeq_destroy(GEOSCoordSequence* s);
00192 
00193 /*
00194  * Set ordinate values in a Coordinate Sequence.
00195  * Return 0 on exception.
00196  */
00197 extern int GEOS_DLL GEOSCoordSeq_setX(GEOSCoordSequence* s,
00198         unsigned int idx, double val);
00199 extern int GEOS_DLL GEOSCoordSeq_setY(GEOSCoordSequence* s,
00200         unsigned int idx, double val);
00201 extern int GEOS_DLL GEOSCoordSeq_setZ(GEOSCoordSequence* s,
00202         unsigned int idx, double val);
00203 extern int GEOS_DLL GEOSCoordSeq_setOrdinate(GEOSCoordSequence* s,
00204         unsigned int idx, unsigned int dim, double val);
00205 
00206 /*
00207  * Get ordinate values from a Coordinate Sequence.
00208  * Return 0 on exception.
00209  */
00210 extern int GEOS_DLL GEOSCoordSeq_getX(const GEOSCoordSequence* s,
00211         unsigned int idx, double *val);
00212 extern int GEOS_DLL GEOSCoordSeq_getY(const GEOSCoordSequence* s,
00213         unsigned int idx, double *val);
00214 extern int GEOS_DLL GEOSCoordSeq_getZ(const GEOSCoordSequence* s,
00215         unsigned int idx, double *val);
00216 extern int GEOS_DLL GEOSCoordSeq_getOrdinate(const GEOSCoordSequence* s,
00217         unsigned int idx, unsigned int dim, double *val);
00218 
00219 /*
00220  * Get size and dimensions info from a Coordinate Sequence.
00221  * Return 0 on exception.
00222  */
00223 extern int GEOS_DLL GEOSCoordSeq_getSize(const GEOSCoordSequence* s,
00224         unsigned int *size);
00225 extern int GEOS_DLL GEOSCoordSeq_getDimensions(const GEOSCoordSequence* s,
00226         unsigned int *dims);
00227 
00228 
00229 /************************************************************************
00230  *
00231  * Geometry Constructors.
00232  * GEOSCoordSequence* arguments will become ownership of the returned object.
00233  * All functions return NULL on exception.
00234  *
00235  ***********************************************************************/
00236 
00237 extern GEOSGeometry GEOS_DLL *GEOSGeom_createPoint(GEOSCoordSequence* s);
00238 extern GEOSGeometry GEOS_DLL *GEOSGeom_createLinearRing(GEOSCoordSequence* s);
00239 extern GEOSGeometry GEOS_DLL *GEOSGeom_createLineString(GEOSCoordSequence* s);
00240 
00241 /*
00242  * Second argument is an array of GEOSGeometry* objects.
00243  * The caller remains owner of the array, but pointed-to
00244  * objects become ownership of the returned GEOSGeometry.
00245  */
00246 extern GEOSGeometry GEOS_DLL *GEOSGeom_createPolygon(GEOSGeometry* shell,
00247         GEOSGeometry** holes, unsigned int nholes);
00248 extern GEOSGeometry GEOS_DLL *GEOSGeom_createCollection(int type,
00249         GEOSGeometry* *geoms, unsigned int ngeoms);
00250 
00251 extern GEOSGeometry GEOS_DLL *GEOSGeom_clone(const GEOSGeometry* g);
00252 
00253 /************************************************************************
00254  *
00255  * Memory management
00256  *
00257  ***********************************************************************/
00258 
00259 extern void GEOS_DLL GEOSGeom_destroy(GEOSGeometry* g);
00260 
00261 
00262 /************************************************************************
00263  *
00264  * Topology operations - return NULL on exception.
00265  *
00266  ***********************************************************************/
00267 
00268 extern GEOSGeometry GEOS_DLL *GEOSEnvelope(const GEOSGeometry* g1);
00269 extern GEOSGeometry GEOS_DLL *GEOSIntersection(const GEOSGeometry* g1, const GEOSGeometry* g2);
00270 extern GEOSGeometry GEOS_DLL *GEOSBuffer(const GEOSGeometry* g1,
00271         double width, int quadsegs);
00272 extern GEOSGeometry GEOS_DLL *GEOSConvexHull(const GEOSGeometry* g1);
00273 extern GEOSGeometry GEOS_DLL *GEOSDifference(const GEOSGeometry* g1, const GEOSGeometry* g2);
00274 extern GEOSGeometry GEOS_DLL *GEOSSymDifference(const GEOSGeometry* g1,
00275         const GEOSGeometry* g2);
00276 extern GEOSGeometry GEOS_DLL *GEOSBoundary(const GEOSGeometry* g1);
00277 extern GEOSGeometry GEOS_DLL *GEOSUnion(const GEOSGeometry* g1, const GEOSGeometry* g2);
00278 extern GEOSGeometry GEOS_DLL *GEOSPointOnSurface(const GEOSGeometry* g1);
00279 extern GEOSGeometry GEOS_DLL *GEOSGetCentroid(const GEOSGeometry* g);
00280 extern char GEOS_DLL *GEOSRelate(const GEOSGeometry* g1, const GEOSGeometry* g2);
00281 
00282 /*
00283  * all arguments remain ownership of the caller
00284  * (both Geometries and pointers)
00285  */
00286 extern GEOSGeometry GEOS_DLL *GEOSPolygonize(const GEOSGeometry * const geoms[],
00287         unsigned int ngeoms);
00288 
00289 extern GEOSGeometry GEOS_DLL *GEOSLineMerge(const GEOSGeometry* g);
00290 extern GEOSGeometry GEOS_DLL *GEOSSimplify(const GEOSGeometry* g1, double tolerance);
00291 extern GEOSGeometry GEOS_DLL *GEOSTopologyPreserveSimplify(const GEOSGeometry* g1,
00292         double tolerance);
00293 
00294 /************************************************************************
00295  *
00296  *  Binary predicates - return 2 on exception, 1 on true, 0 on false
00297  *
00298  ***********************************************************************/
00299 
00300 extern char GEOS_DLL GEOSRelatePattern(const GEOSGeometry* g1, const GEOSGeometry* g2,
00301         const char *pat);
00302 extern char GEOS_DLL GEOSDisjoint(const GEOSGeometry* g1, const GEOSGeometry* g2);
00303 extern char GEOS_DLL GEOSTouches(const GEOSGeometry* g1, const GEOSGeometry* g2);
00304 extern char GEOS_DLL GEOSIntersects(const GEOSGeometry* g1, const GEOSGeometry* g2);
00305 extern char GEOS_DLL GEOSCrosses(const GEOSGeometry* g1, const GEOSGeometry* g2);
00306 extern char GEOS_DLL GEOSWithin(const GEOSGeometry* g1, const GEOSGeometry* g2);
00307 extern char GEOS_DLL GEOSContains(const GEOSGeometry* g1, const GEOSGeometry* g2);
00308 extern char GEOS_DLL GEOSOverlaps(const GEOSGeometry* g1, const GEOSGeometry* g2);
00309 extern char GEOS_DLL GEOSEquals(const GEOSGeometry* g1, const GEOSGeometry* g2);
00310 extern char GEOS_DLL GEOSEqualsExact(const GEOSGeometry* g1, const GEOSGeometry* g2, double tolerance);
00311 
00312 
00313 /************************************************************************
00314  *
00315  *  Unary predicate - return 2 on exception, 1 on true, 0 on false
00316  *
00317  ***********************************************************************/
00318 
00319 extern char GEOS_DLL GEOSisEmpty(const GEOSGeometry* g1);
00320 extern char GEOS_DLL GEOSisValid(const GEOSGeometry* g1);
00321 extern char GEOS_DLL GEOSisSimple(const GEOSGeometry* g1);
00322 extern char GEOS_DLL GEOSisRing(const GEOSGeometry* g1);
00323 extern char GEOS_DLL GEOSHasZ(const GEOSGeometry* g1);
00324 
00325 
00326 /************************************************************************
00327  *
00328  *  Geometry info
00329  *
00330  ***********************************************************************/
00331 
00332 /* Return NULL on exception, result must be freed by caller. */
00333 extern char GEOS_DLL *GEOSGeomType(const GEOSGeometry* g1);
00334 
00335 /* Return -1 on exception */
00336 extern int GEOS_DLL GEOSGeomTypeId(const GEOSGeometry* g1);
00337 
00338 /* Return 0 on exception */
00339 extern int GEOS_DLL GEOSGetSRID(const GEOSGeometry* g1);
00340 
00341 extern void GEOS_DLL GEOSSetSRID(GEOSGeometry* g, int SRID);
00342 
00343 /* May be called on all geometries in GEOS 3.x, returns -1 on error and 1
00344  * for non-multi geometries. Older GEOS versions only accept 
00345  * GeometryCollections or Multi* geometries here, and are likely to crash
00346  * when feeded simple geometries, so beware if you need compatibility with
00347  * old GEOS versions.
00348  */
00349 extern int GEOS_DLL GEOSGetNumGeometries(const GEOSGeometry* g1);
00350 
00351 /*
00352  * Return NULL on exception, Geometry must be a Collection.
00353  * Returned object is a pointer to internal storage:
00354  * it must NOT be destroyed directly.
00355  */
00356 extern const GEOSGeometry GEOS_DLL *GEOSGetGeometryN(const GEOSGeometry* g, int n);
00357 
00358 /* Return -1 on exception */
00359 extern int GEOS_DLL GEOSNormalize(GEOSGeometry* g1);
00360 
00361 /* Return -1 on exception */
00362 extern int GEOS_DLL GEOSGetNumInteriorRings(const GEOSGeometry* g1);
00363 
00364 /*
00365  * Return NULL on exception, Geometry must be a Polygon.
00366  * Returned object is a pointer to internal storage:
00367  * it must NOT be destroyed directly.
00368  */
00369 extern const GEOSGeometry GEOS_DLL *GEOSGetInteriorRingN(const GEOSGeometry* g, int n);
00370 
00371 /*
00372  * Return NULL on exception, Geometry must be a Polygon.
00373  * Returned object is a pointer to internal storage:
00374  * it must NOT be destroyed directly.
00375  */
00376 extern const GEOSGeometry GEOS_DLL *GEOSGetExteriorRing(const GEOSGeometry* g);
00377 
00378 /* Return -1 on exception */
00379 extern int GEOS_DLL GEOSGetNumCoordinates(const GEOSGeometry* g1);
00380 
00381 /*
00382  * Return NULL on exception.
00383  * Geometry must be a LineString, LinearRing or Point.
00384  */
00385 extern const GEOSCoordSequence GEOS_DLL *GEOSGeom_getCoordSeq(const GEOSGeometry* g);
00386 
00387 /*
00388  * Return 0 on exception (or empty geometry)
00389  */
00390 extern int GEOS_DLL GEOSGeom_getDimensions(const GEOSGeometry* g);
00391 
00392 /************************************************************************
00393  *
00394  *  Misc functions 
00395  *
00396  ***********************************************************************/
00397 
00398 /* Return 0 on exception, 1 otherwise */
00399 extern int GEOS_DLL GEOSArea(const GEOSGeometry* g1, double *area);
00400 extern int GEOS_DLL GEOSLength(const GEOSGeometry* g1, double *length);
00401 extern int GEOS_DLL GEOSDistance(const GEOSGeometry* g1, const GEOSGeometry* g2,
00402         double *dist);
00403 
00404 
00405 
00406 /************************************************************************
00407  *
00408  * Reader and Writer APIs
00409  *
00410  ***********************************************************************/
00411 
00412 typedef struct GEOSWKTReader_t GEOSWKTReader;
00413 typedef struct GEOSWKTWriter_t GEOSWKTWriter;
00414 typedef struct GEOSWKBReader_t GEOSWKBReader;
00415 typedef struct GEOSWKBWriter_t GEOSWKBWriter;
00416 
00417 
00418 /* WKT Reader */
00419 extern GEOSWKTReader GEOS_DLL *GEOSWKTReader_create();
00420 extern void GEOS_DLL GEOSWKTReader_destroy(GEOSWKTReader* reader);
00421 extern GEOSGeometry GEOS_DLL *GEOSWKTReader_read(GEOSWKTReader* reader, const char *wkt);
00422 
00423 /* WKT Writer */
00424 extern GEOSWKTWriter GEOS_DLL *GEOSWKTWriter_create();
00425 extern void GEOS_DLL GEOSWKTWriter_destroy(GEOSWKTWriter* writer);
00426 extern char GEOS_DLL *GEOSWKTWriter_write(GEOSWKTWriter* reader, const GEOSGeometry* g);
00427 
00428 /* WKB Reader */
00429 extern GEOSWKBReader GEOS_DLL *GEOSWKBReader_create();
00430 extern void GEOS_DLL GEOSWKBReader_destroy(GEOSWKBReader* reader);
00431 extern GEOSGeometry GEOS_DLL *GEOSWKBReader_read(GEOSWKBReader* reader, const unsigned char *wkb, size_t size);
00432 extern GEOSGeometry GEOS_DLL *GEOSWKBReader_readHEX(GEOSWKBReader* reader, const unsigned char *hex, size_t size);
00433 
00434 /* WKB Writer */
00435 extern GEOSWKBWriter GEOS_DLL *GEOSWKBWriter_create();
00436 extern void GEOS_DLL GEOSWKBWriter_destroy(GEOSWKBWriter* writer);
00437 
00438 /* The owner owns the results for these two methods! */
00439 extern unsigned char GEOS_DLL *GEOSWKBWriter_write(GEOSWKBWriter* writer, const GEOSGeometry* g, size_t *size);
00440 extern unsigned char GEOS_DLL *GEOSWKBWriter_writeHEX(GEOSWKBWriter* writer, const GEOSGeometry* g, size_t *size);
00441 
00442 /* 
00443  * Specify whether output WKB should be 2d or 3d.
00444  * Return previously set number of dimensions.
00445  */
00446 extern int GEOS_DLL GEOSWKBWriter_getOutputDimension(const GEOSWKBWriter* writer);
00447 extern void GEOS_DLL GEOSWKBWriter_setOutputDimension(GEOSWKBWriter* writer, int newDimension);
00448 
00449 /*
00450  * Specify whether the WKB byte order is big or little endian. 
00451  * The return value is the previous byte order.
00452  */
00453 extern int GEOS_DLL GEOSWKBWriter_getByteOrder(const GEOSWKBWriter* writer);
00454 extern void GEOS_DLL GEOSWKBWriter_setByteOrder(GEOSWKBWriter* writer, int byteOrder);
00455 
00456 /*
00457  * Specify whether SRID values should be output. 
00458  */
00459 extern char GEOS_DLL GEOSWKBWriter_getIncludeSRID(const GEOSWKBWriter* writer);
00460 extern void GEOS_DLL GEOSWKBWriter_setIncludeSRID(GEOSWKBWriter* writer, const char writeSRID);
00461 
00462 
00463 
00464 
00465 #ifdef __cplusplus
00466 } // extern "C"
00467 #endif
00468 
00469 #endif /* #ifndef GEOS_C_H */

Generated on Fri Mar 27 04:52:46 2009 for GEOS by  doxygen 1.5.4