Main Page Class Hierarchy Compound List File List Compound Members File Members Related Pages

# gdal.h

Go to the documentation of this file.

    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 */