00001 /****************************************************************************** 00002 * $Id: gdal_h-source.html,v 1.11 2002/04/16 13:11:48 warmerda Exp $ 00003 * 00004 * Name: gdal.h 00005 * Project: GDAL Core 00006 * Purpose: GDAL Core C/Public declarations. 00007 * Author: Frank Warmerdam, warmerda@home.com 00008 * 00009 ****************************************************************************** 00010 * Copyright (c) 1998, Frank Warmerdam 00011 * 00012 * Permission is hereby granted, free of charge, to any person obtaining a 00013 * copy of this software and associated documentation files (the "Software"), 00014 * to deal in the Software without restriction, including without limitation 00015 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 00016 * and/or sell copies of the Software, and to permit persons to whom the 00017 * Software is furnished to do so, subject to the following conditions: 00018 * 00019 * The above copyright notice and this permission notice shall be included 00020 * in all copies or substantial portions of the Software. 00021 * 00022 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 00023 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 00024 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 00025 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 00026 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 00027 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 00028 * DEALINGS IN THE SOFTWARE. 00029 ****************************************************************************** 00030 * 00031 * $Log: gdal_h-source.html,v $ 00031 * Revision 1.11 2002/04/16 13:11:48 warmerda 00031 * updated 00031 * 00032 * Revision 1.42 2002/02/04 19:23:09 warmerda 00033 * *** empty log message *** 00034 * 00035 * Revision 1.41 2002/01/13 03:12:04 warmerda 00036 * added version/release information 00037 * 00038 * Revision 1.40 2001/12/10 17:43:22 warmerda 00039 * fixed GDALAddBand() prototype 00040 * 00041 * Revision 1.39 2001/11/18 00:52:15 warmerda 00042 * removed GDALProjDef 00043 * 00044 * Revision 1.38 2001/11/16 21:36:01 warmerda 00045 * added the AddBand() method on GDALDataset 00046 * 00047 * Revision 1.37 2001/10/17 21:47:02 warmerda 00048 * added SetGCPs() on GDALDataset 00049 * 00050 * Revision 1.36 2001/07/05 13:13:40 warmerda 00051 * added UnitType from C support 00052 * 00053 * Revision 1.35 2001/05/01 18:09:25 warmerda 00054 * added GDALReadWorldFile() 00055 * 00056 * Revision 1.34 2001/01/30 22:32:42 warmerda 00057 * added AVERAGE_MP (magnitude preserving averaging) overview resampling type 00058 * 00059 * Revision 1.33 2000/10/06 18:30:01 warmerda 00060 * Fixed CPL_DLL position for GDALGetRasterCategoryNames(). 00061 * 00062 * Revision 1.32 2000/10/06 15:23:03 warmerda 00063 * added some new functions 00064 * 00065 * Revision 1.31 2000/08/25 14:26:51 warmerda 00066 * added GDALHasArbitraryOverviews 00067 * 00068 * Revision 1.30 2000/08/18 15:24:48 warmerda 00069 * added GDALTermProgress 00070 * 00071 * Revision 1.29 2000/07/11 14:35:43 warmerda 00072 * added documentation 00073 * 00074 * Revision 1.28 2000/06/27 17:30:21 warmerda 00075 * added GDALGetRasterSampleOverview 00076 * 00077 * Revision 1.27 2000/06/26 22:17:49 warmerda 00078 * added scaled progress support 00079 * 00080 * Revision 1.26 2000/06/26 18:47:31 warmerda 00081 * added GDALBuildOverviews 00082 * 00083 * Revision 1.25 2000/06/26 15:26:21 warmerda 00084 * added GDALGetDescription 00085 * 00086 * Revision 1.24 2000/06/05 17:24:05 warmerda 00087 * added real complex support 00088 * 00089 * Revision 1.23 2000/04/30 23:22:16 warmerda 00090 * added CreateCopy support 00091 * 00092 * Revision 1.22 2000/04/26 18:25:29 warmerda 00093 * added missing CPL_DLL attributes 00094 * 00095 * Revision 1.21 2000/04/21 21:54:37 warmerda 00096 * updated metadata API 00097 * 00098 * Revision 1.20 2000/03/31 13:41:25 warmerda 00099 * added gcps 00100 * 00101 * Revision 1.19 2000/03/24 00:09:05 warmerda 00102 * rewrote cache management 00103 * 00104 * Revision 1.18 2000/03/09 23:22:03 warmerda 00105 * added GetHistogram 00106 * 00107 * Revision 1.17 2000/03/08 19:59:16 warmerda 00108 * added GDALFlushRasterCache 00109 * 00110 * Revision 1.16 2000/03/06 21:50:37 warmerda 00111 * added min/max support 00112 * 00113 * Revision 1.15 2000/03/06 02:19:56 warmerda 00114 * added lots of new functions 00115 * 00116 * Revision 1.14 2000/01/31 14:24:36 warmerda 00117 * implemented dataset delete 00118 * 00119 * Revision 1.13 1999/11/11 21:59:06 warmerda 00120 * added GetDriver() for datasets 00121 * 00122 * Revision 1.12 1999/10/21 13:23:28 warmerda 00123 * Added C callable driver related functions. 00124 * 00125 * Revision 1.11 1999/10/01 14:44:02 warmerda 00126 * added documentation 00127 * 00128 * Revision 1.10 1999/07/23 19:35:22 warmerda 00129 * added GDALSwapWords(), GDALCopyWords() 00130 * 00131 * Revision 1.9 1999/05/23 02:46:26 warmerda 00132 * Added documentation short description. 00133 * 00134 * Revision 1.8 1999/04/21 04:16:13 warmerda 00135 * experimental docs 00136 * 00137 * Revision 1.7 1999/03/02 21:09:48 warmerda 00138 * add GDALDecToDMS() 00139 * 00140 * Revision 1.6 1999/01/11 15:36:17 warmerda 00141 * Added projections support, and a few other things. 00142 * 00143 * Revision 1.5 1998/12/31 18:53:33 warmerda 00144 * Add GDALGetDriverByName 00145 * 00146 * Revision 1.4 1998/12/06 22:16:27 warmerda 00147 * Added GDALCreate(). 00148 * 00149 * Revision 1.3 1998/12/06 02:50:36 warmerda 00150 * Added three new functions. 00151 * 00152 * Revision 1.2 1998/12/03 18:34:05 warmerda 00153 * Update to use CPL 00154 * 00155 * Revision 1.1 1998/10/18 06:15:10 warmerda 00156 * Initial implementation. 00157 * 00158 */ 00159 00160 #ifndef GDAL_H_INCLUDED 00161 #define GDAL_H_INCLUDED 00162 00169 #include "cpl_port.h" 00170 #include "cpl_error.h" 00171 00172 /* -------------------------------------------------------------------- */ 00173 /* GDAL Version Information. */ 00174 /* -------------------------------------------------------------------- */ 00175 #define GDAL_VERSION_NUM 1160 00176 #define GDAL_RELEASE_DATE 20020204 00177 #define GDAL_RELEASE_NAME "1.1.6" 00178 00179 /* -------------------------------------------------------------------- */ 00180 /* Significant constants. */ 00181 /* -------------------------------------------------------------------- */ 00182 00183 CPL_C_START 00184 00186 typedef enum { 00187 GDT_Unknown = 0, GDT_Byte = 1, GDT_UInt16 = 2, GDT_Int16 = 3, GDT_UInt32 = 4, GDT_Int32 = 5, GDT_Float32 = 6, GDT_Float64 = 7, GDT_CInt16 = 8, GDT_CInt32 = 9, GDT_CFloat32 = 10, GDT_CFloat64 = 11, 00199 GDT_TypeCount = 12 /* maximum type # + 1 */ 00200 } GDALDataType; 00201 00202 int CPL_DLL GDALGetDataTypeSize( GDALDataType ); 00203 int CPL_DLL GDALDataTypeIsComplex( GDALDataType ); 00204 const char CPL_DLL *GDALGetDataTypeName( GDALDataType ); 00205 GDALDataType CPL_DLL GDALDataTypeUnion( GDALDataType, GDALDataType ); 00206 00208 typedef enum { GA_ReadOnly = 0, GA_Update = 1 00211 } GDALAccess; 00212 00214 typedef enum { GF_Read = 0, GF_Write = 1 00217 } GDALRWFlag; 00218 00220 typedef enum 00221 { 00222 GCI_Undefined=0, GCI_GrayIndex=1, GCI_PaletteIndex=2, GCI_RedBand=3, GCI_GreenBand=4, GCI_BlueBand=5, GCI_AlphaBand=6, GCI_HueBand=7, GCI_SaturationBand=8, GCI_LightnessBand=9, GCI_CyanBand=10, GCI_MagentaBand=11, GCI_YellowBand=12, GCI_BlackBand=13 00236 } GDALColorInterp; 00237 00239 const char CPL_DLL *GDALGetColorInterpretationName( GDALColorInterp ); 00240 00242 typedef enum 00243 { GPI_Gray=0, GPI_RGB=1, GPI_CMYK=2, GPI_HLS=3 00248 } GDALPaletteInterp; 00249 00251 const char CPL_DLL *GDALGetPaletteInterpretationName( GDALPaletteInterp ); 00252 00253 /* -------------------------------------------------------------------- */ 00254 /* GDAL Specific error codes. */ 00255 /* */ 00256 /* error codes 100 to 299 reserved for GDAL. */ 00257 /* -------------------------------------------------------------------- */ 00258 #define CPLE_WrongFormat 200 00259 00260 /* -------------------------------------------------------------------- */ 00261 /* Define handle types related to various internal classes. */ 00262 /* -------------------------------------------------------------------- */ 00263 typedef void *GDALMajorObjectH; 00264 typedef void *GDALDatasetH; 00265 typedef void *GDALRasterBandH; 00266 typedef void *GDALDriverH; 00267 typedef void *GDALProjDefH; 00268 typedef void *GDALColorTableH; 00269 00270 /* -------------------------------------------------------------------- */ 00271 /* Callback "progress" function. */ 00272 /* -------------------------------------------------------------------- */ 00275 typedef int (*GDALProgressFunc)(double,const char *, void *); 00276 int CPL_DLL GDALDummyProgress( double, const char *, void *); 00277 int CPL_DLL GDALTermProgress( double, const char *, void *); 00278 int CPL_DLL GDALScaledProgress( double, const char *, void *); 00279 void CPL_DLL *GDALCreateScaledProgress( double, double, 00280 GDALProgressFunc, void * ); 00281 void CPL_DLL GDALDestroyScaledProgress( void * ); 00282 00283 /* ==================================================================== */ 00284 /* Registration/driver related. */ 00285 /* ==================================================================== */ 00286 00287 void CPL_DLL GDALAllRegister( void ); 00288 00289 GDALDatasetH CPL_DLL GDALCreate( GDALDriverH hDriver, 00290 const char *, int, int, int, GDALDataType, 00291 char ** ); 00292 GDALDatasetH CPL_DLL GDALCreateCopy( GDALDriverH, const char *, GDALDatasetH, 00293 int, char **, GDALProgressFunc, void * ); 00294 00295 GDALDatasetH CPL_DLL GDALOpen( const char *, GDALAccess ); 00296 00297 GDALDriverH CPL_DLL GDALGetDriverByName( const char * ); 00298 int CPL_DLL GDALGetDriverCount(); 00299 GDALDriverH CPL_DLL GDALGetDriver( int ); 00300 int CPL_DLL GDALRegisterDriver( GDALDriverH ); 00301 void CPL_DLL GDALDeregisterDriver( GDALDriverH ); 00302 CPLErr CPL_DLL GDALDeleteDataset( GDALDriverH, const char * ); 00303 00304 const char CPL_DLL *GDALGetDriverShortName( GDALDriverH ); 00305 const char CPL_DLL *GDALGetDriverLongName( GDALDriverH ); 00306 const char CPL_DLL *GDALGetDriverHelpTopic( GDALDriverH ); 00307 00308 /* ==================================================================== */ 00309 /* GDAL_GCP */ 00310 /* ==================================================================== */ 00311 00313 typedef struct 00314 { 00316 char *pszId; 00317 00319 char *pszInfo; 00320 00322 double dfGCPPixel; 00324 double dfGCPLine; 00325 00327 double dfGCPX; 00328 00330 double dfGCPY; 00331 00333 double dfGCPZ; 00334 } GDAL_GCP; 00335 00336 void CPL_DLL GDALInitGCPs( int, GDAL_GCP * ); 00337 void CPL_DLL GDALDeinitGCPs( int, GDAL_GCP * ); 00338 GDAL_GCP CPL_DLL *GDALDuplicateGCPs( int, const GDAL_GCP * ); 00339 00340 /* ==================================================================== */ 00341 /* major objects (dataset, and, driver, drivermanager). */ 00342 /* ==================================================================== */ 00343 00344 char CPL_DLL **GDALGetMetadata( GDALMajorObjectH, const char * ); 00345 CPLErr CPL_DLL GDALSetMetadata( GDALMajorObjectH, char **, 00346 const char * ); 00347 const char CPL_DLL *GDALGetMetadataItem( GDALMajorObjectH, const char *, 00348 const char * ); 00349 CPLErr CPL_DLL GDALSetMetadataItem( GDALMajorObjectH, 00350 const char *, const char *, 00351 const char * ); 00352 const char CPL_DLL *GDALGetDescription( GDALMajorObjectH ); 00353 00354 /* ==================================================================== */ 00355 /* GDALDataset class ... normally this represents one file. */ 00356 /* ==================================================================== */ 00357 00358 GDALDriverH CPL_DLL GDALGetDatasetDriver( GDALDatasetH ); 00359 void CPL_DLL GDALClose( GDALDatasetH ); 00360 int CPL_DLL GDALGetRasterXSize( GDALDatasetH ); 00361 int CPL_DLL GDALGetRasterYSize( GDALDatasetH ); 00362 int CPL_DLL GDALGetRasterCount( GDALDatasetH ); 00363 GDALRasterBandH CPL_DLL GDALGetRasterBand( GDALDatasetH, int ); 00364 00365 CPLErr CPL_DLL GDALAddBand( GDALDatasetH hDS, GDALDataType eType, 00366 char **papszOptions ); 00367 00368 const char CPL_DLL *GDALGetProjectionRef( GDALDatasetH ); 00369 CPLErr CPL_DLL GDALSetProjection( GDALDatasetH, const char * ); 00370 CPLErr CPL_DLL GDALGetGeoTransform( GDALDatasetH, double * ); 00371 CPLErr CPL_DLL GDALSetGeoTransform( GDALDatasetH, double * ); 00372 00373 int CPL_DLL GDALGetGCPCount( GDALDatasetH ); 00374 const char CPL_DLL *GDALGetGCPProjection( GDALDatasetH ); 00375 const GDAL_GCP CPL_DLL *GDALGetGCPs( GDALDatasetH ); 00376 CPLErr CPL_DLL GDALSetGCPs( GDALDatasetH, int, const GDAL_GCP *, 00377 const char * ); 00378 00379 void CPL_DLL *GDALGetInternalHandle( GDALDatasetH, const char * ); 00380 int CPL_DLL GDALReferenceDataset( GDALDatasetH ); 00381 int CPL_DLL GDALDereferenceDataset( GDALDatasetH ); 00382 00383 CPLErr CPL_DLL GDALBuildOverviews( GDALDatasetH, const char *, int, int *, 00384 int, int *, GDALProgressFunc, void * ); 00385 00386 /* ==================================================================== */ 00387 /* GDALRasterBand ... one band/channel in a dataset. */ 00388 /* ==================================================================== */ 00389 00390 GDALDataType CPL_DLL GDALGetRasterDataType( GDALRasterBandH ); 00391 void CPL_DLL GDALGetBlockSize( GDALRasterBandH, 00392 int * pnXSize, int * pnYSize ); 00393 00394 CPLErr CPL_DLL GDALRasterIO( GDALRasterBandH hRBand, GDALRWFlag eRWFlag, 00395 int nDSXOff, int nDSYOff, 00396 int nDSXSize, int nDSYSize, 00397 void * pBuffer, int nBXSize, int nBYSize, 00398 GDALDataType eBDataType, 00399 int nPixelSpace, int nLineSpace ); 00400 CPLErr CPL_DLL GDALReadBlock( GDALRasterBandH, int, int, void * ); 00401 CPLErr CPL_DLL GDALWriteBlock( GDALRasterBandH, int, int, void * ); 00402 int CPL_DLL GDALGetRasterBandXSize( GDALRasterBandH ); 00403 int CPL_DLL GDALGetRasterBandYSize( GDALRasterBandH ); 00404 char CPL_DLL **GDALGetRasterMetadata( GDALRasterBandH ); 00405 00406 GDALColorInterp CPL_DLL GDALGetRasterColorInterpretation( GDALRasterBandH ); 00407 GDALColorTableH CPL_DLL GDALGetRasterColorTable( GDALRasterBandH ); 00408 CPLErr CPL_DLL GDALSetRasterColorTable( GDALRasterBandH, GDALColorTableH ); 00409 int CPL_DLL GDALHasArbitraryOverviews( GDALRasterBandH ); 00410 int CPL_DLL GDALGetOverviewCount( GDALRasterBandH ); 00411 GDALRasterBandH CPL_DLL GDALGetOverview( GDALRasterBandH, int ); 00412 double CPL_DLL GDALGetRasterNoDataValue( GDALRasterBandH, int * ); 00413 CPLErr CPL_DLL GDALSetRasterNoDataValue( GDALRasterBandH, double ); 00414 char CPL_DLL ** GDALGetRasterCategoryNames( GDALRasterBandH ); 00415 CPLErr CPL_DLL GDALSetRasterCategoryNames( GDALRasterBandH, char ** ); 00416 double CPL_DLL GDALGetRasterMinimum( GDALRasterBandH, int *pbSuccess ); 00417 double CPL_DLL GDALGetRasterMaximum( GDALRasterBandH, int *pbSuccess ); 00418 const char CPL_DLL *GDALGetRasterUnitType( GDALRasterBandH ); 00419 void CPL_DLL GDALComputeRasterMinMax( GDALRasterBandH hBand, int bApproxOK, 00420 double adfMinMax[2] ); 00421 CPLErr CPL_DLL GDALFlushRasterCache( GDALRasterBandH hBand ); 00422 CPLErr CPL_DLL GDALGetRasterHistogram( GDALRasterBandH hBand, 00423 double dfMin, double dfMax, 00424 int nBuckets, int *panHistogram, 00425 int bIncludeOutOfRange, int bApproxOK, 00426 GDALProgressFunc pfnProgress, 00427 void * pProgressData ); 00428 int CPL_DLL GDALGetRandomRasterSample( GDALRasterBandH, int, float * ); 00429 GDALRasterBandH CPL_DLL GDALGetRasterSampleOverview( GDALRasterBandH, int ); 00430 00431 CPLErr GDALComputeBandStats( GDALRasterBandH hBand, int nSampleStep, 00432 double *pdfMean, double *pdfStdDev, 00433 GDALProgressFunc pfnProgress, 00434 void *pProgressData ); 00435 CPLErr GDALOverviewMagnitudeCorrection( GDALRasterBandH hBaseBand, 00436 int nOverviewCount, 00437 GDALRasterBandH *pahOverviews, 00438 GDALProgressFunc pfnProgress, 00439 void *pProgressData ); 00440 00441 /* -------------------------------------------------------------------- */ 00442 /* Helper functions. */ 00443 /* -------------------------------------------------------------------- */ 00444 void CPL_DLL GDALSwapWords( void *pData, int nWordSize, int nWordCount, 00445 int nWordSkip ); 00446 void CPL_DLL 00447 GDALCopyWords( void * pSrcData, GDALDataType eSrcType, int nSrcPixelOffset, 00448 void * pDstData, GDALDataType eDstType, int nDstPixelOffset, 00449 int nWordCount ); 00450 00451 int GDALReadWorldFile( const char *pszBaseFilename, 00452 const char *pszExtension, 00453 double * padfGeoTransform ); 00454 00455 const char CPL_DLL *GDALDecToDMS( double, const char *, int ); 00456 00457 /* ==================================================================== */ 00458 /* Color tables. */ 00459 /* ==================================================================== */ 00461 typedef struct 00462 { 00464 short c1; 00465 00467 short c2; 00468 00470 short c3; 00471 00473 short c4; 00474 } GDALColorEntry; 00475 00476 GDALColorTableH CPL_DLL GDALCreateColorTable( GDALPaletteInterp ); 00477 void CPL_DLL GDALDestroyColorTable( GDALColorTableH ); 00478 GDALColorTableH CPL_DLL GDALCloneColorTable( GDALColorTableH ); 00479 GDALPaletteInterp CPL_DLL GDALGetPaletteInterpretation( GDALColorTableH ); 00480 int CPL_DLL GDALGetColorEntryCount( GDALColorTableH ); 00481 const GDALColorEntry CPL_DLL *GDALGetColorEntry( GDALColorTableH, int ); 00482 int CPL_DLL GDALGetColorEntryAsRGB( GDALColorTableH, int, GDALColorEntry *); 00483 void CPL_DLL GDALSetColorEntry( GDALColorTableH, int, const GDALColorEntry * ); 00484 00485 /* ==================================================================== */ 00486 /* GDAL Cache Management */ 00487 /* ==================================================================== */ 00488 00489 void CPL_DLL GDALSetCacheMax( int nBytes ); 00490 int CPL_DLL GDALGetCacheMax(); 00491 int CPL_DLL GDALGetCacheUsed(); 00492 int CPL_DLL GDALFlushCacheBlock(); 00493 00494 CPL_C_END 00495 00496 #endif /* ndef GDAL_H_INCLUDED */