gdal.h

Go to the documentation of this file.

/******************************************************************************
 * $Id: gdal.h,v 1.77 2004/03/10 19:18:29 warmerda Exp $
 *
 * Name:     gdal.h
 * Project:  GDAL Core
 * Purpose:  GDAL Core C/Public declarations.
 * Author:   Frank Warmerdam, warmerdam@pobox.com
 *
 ******************************************************************************
 * Copyright (c) 1998, 2002 Frank Warmerdam
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included
 * in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 ******************************************************************************
 *
 * $Log: gdal.h,v $
 * Revision 1.77  2004/03/10 19:18:29  warmerda
 * updated date
 *
 * Revision 1.76  2004/03/01 18:30:44  warmerda
 * Updated release date.
 *
 * Revision 1.75  2004/02/25 09:03:15  dron
 * Added GDALPackedDMSToDec() and GDALDecToPackedDMS() functions.
 *
 * Revision 1.74  2004/02/19 15:55:52  warmerda
 * updated to 1.2.0
 *
 * Revision 1.73  2004/02/04 21:30:12  warmerda
 * ensure GDALGetDataTypeByName is exported
 *
 * Revision 1.72  2004/01/18 16:43:37  dron
 * Added GDALGetDataTypeByName() function.
 *
 * Revision 1.71  2003/07/18 04:46:48  sperkins
 * added CPL_DLL to GDALFillRaster
 *
 * Revision 1.70  2003/06/27 20:03:11  warmerda
 * updated version to 1.1.9
 *
 * Revision 1.69  2003/06/03 19:44:00  warmerda
 * added GDALRPCInfo support
 *
 * Revision 1.68  2003/05/06 05:20:38  sperkins
 * cleaned up comments
 *
 * Revision 1.67  2003/05/06 05:13:36  sperkins
 * added Fill() and GDALFillRaster()
 *
 * Revision 1.66  2003/05/02 19:47:57  warmerda
 * added C GetBandNumber and GetBandDataset entry points
 *
 * Revision 1.65  2003/04/30 17:13:48  warmerda
 * added docs for many C functions
 *
 * Revision 1.64  2003/04/30 15:48:31  warmerda
 * Fixed email address, trimmed log messages.
 *
 * Revision 1.63  2003/04/25 19:46:13  warmerda
 * added GDALDatasetRasterIO
 *
 * Revision 1.62  2003/03/18 06:01:03  warmerda
 * Added GDALFlushCache()
 *
 * Revision 1.61  2003/02/20 18:34:12  warmerda
 * added GDALGetRasterAccess()
 *
 * Revision 1.60  2003/01/27 21:55:52  warmerda
 * various documentation improvements
 *
 * Revision 1.59  2002/12/21 17:28:35  warmerda
 * actually, lets use 1.1.8.0
 *
 * Revision 1.58  2002/12/21 17:26:43  warmerda
 * updated version to 1.1.7.5
 *
 * Revision 1.57  2002/12/05 15:46:38  warmerda
 * added GDALReadTabFile()
 *
 * Revision 1.56  2002/11/23 18:07:41  warmerda
 * added DMD_CREATIONDATATYPES
 *
 * Revision 1.55  2002/10/24 14:18:29  warmerda
 * intermediate version update
 *
 * Revision 1.54  2002/09/11 14:17:38  warmerda
 * added C GDALSetDescription()
 *
 * Revision 1.53  2002/09/06 01:29:55  warmerda
 * added C entry points for GetAccess() and GetOpenDatasets()
 *
 * Revision 1.52  2002/09/04 06:52:35  warmerda
 * added GDALDestroyDriverManager
 *
 * Revision 1.51  2002/07/09 20:33:12  warmerda
 * expand tabs
 *
 * Revision 1.50  2002/06/12 21:13:27  warmerda
 * use metadata based driver info
 *
 * Revision 1.49  2002/05/28 18:55:46  warmerda
 * added GDALOpenShared() and GDALDumpOpenDatasets
 *
 * Revision 1.48  2002/05/14 21:38:32  warmerda
 * make INST_DATA overidable with binary patch
 *
 * Revision 1.47  2002/05/06 21:37:29  warmerda
 * added GDALGCPsToGeoTransform
 *
 * Revision 1.46  2002/04/24 16:25:04  warmerda
 * Ensure that GDAL{Read,Write}WorldFile() are exported on Windows.
 *
 * Revision 1.45  2002/04/19 12:22:05  dron
 * added GDALWriteWorldFile()
 *
 * Revision 1.44  2002/04/16 13:59:33  warmerda
 * added GDALVersionInfo
 *
 * Revision 1.43  2002/04/16 13:26:08  warmerda
 * upgrade to version 1.1.7
 */

#ifndef GDAL_H_INCLUDED
#define GDAL_H_INCLUDED

#include "cpl_port.h"
#include "cpl_error.h"

/* -------------------------------------------------------------------- */
/*      GDAL Version Information.                                       */
/* -------------------------------------------------------------------- */
#ifndef GDAL_VERSION_NUM
#  define GDAL_VERSION_NUM      1200
#endif
#ifndef GDAL_RELEASE_DATE
#  define GDAL_RELEASE_DATE     20040310
#endif
#ifndef GDAL_RELEASE_NAME
#  define GDAL_RELEASE_NAME     "1.2.0.0"
#endif

/* -------------------------------------------------------------------- */
/*      Significant constants.                                          */
/* -------------------------------------------------------------------- */

CPL_C_START

typedef enum {
    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,
    GDT_TypeCount = 12          /* maximum type # + 1 */
} GDALDataType;

int CPL_DLL GDALGetDataTypeSize( GDALDataType );
int CPL_DLL GDALDataTypeIsComplex( GDALDataType );
const char CPL_DLL *GDALGetDataTypeName( GDALDataType );
GDALDataType CPL_DLL GDALGetDataTypeByName( const char * );
GDALDataType CPL_DLL GDALDataTypeUnion( GDALDataType, GDALDataType );

typedef enum { GA_ReadOnly = 0,           GA_Update = 1
} GDALAccess;

typedef enum {   GF_Read = 0,  GF_Write = 1
} GDALRWFlag;

typedef enum
{
    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
} GDALColorInterp;

const char CPL_DLL *GDALGetColorInterpretationName( GDALColorInterp );

typedef enum 
{                      GPI_Gray=0,  GPI_RGB=1, GPI_CMYK=2,     GPI_HLS=3
} GDALPaletteInterp;

const char CPL_DLL *GDALGetPaletteInterpretationName( GDALPaletteInterp );

/* -------------------------------------------------------------------- */
/*      GDAL Specific error codes.                                      */
/*                                                                      */
/*      error codes 100 to 299 reserved for GDAL.                       */
/* -------------------------------------------------------------------- */
#define CPLE_WrongFormat        200

/* -------------------------------------------------------------------- */
/*      Define handle types related to various internal classes.        */
/* -------------------------------------------------------------------- */
typedef void *GDALMajorObjectH;
typedef void *GDALDatasetH;
typedef void *GDALRasterBandH;
typedef void *GDALDriverH;
typedef void *GDALProjDefH;
typedef void *GDALColorTableH;

/* -------------------------------------------------------------------- */
/*      Callback "progress" function.                                   */
/* -------------------------------------------------------------------- */

typedef int (*GDALProgressFunc)(double,const char *, void *);
int CPL_DLL GDALDummyProgress( double, const char *, void *);
int CPL_DLL GDALTermProgress( double, const char *, void *);
int CPL_DLL GDALScaledProgress( double, const char *, void *);
void CPL_DLL *GDALCreateScaledProgress( double, double,
                                        GDALProgressFunc, void * );
void CPL_DLL GDALDestroyScaledProgress( void * );

/* ==================================================================== */
/*      Registration/driver related.                                    */
/* ==================================================================== */

typedef struct {
    char      *pszOptionName;
    char      *pszValueType;   /* "boolean", "int", "float", "string", 
                                  "string-select" */
    char      *pszDescription;
    char      **papszOptions;
} GDALOptionDefinition;

#define GDAL_DMD_LONGNAME "DMD_LONGNAME"
#define GDAL_DMD_HELPTOPIC "DMD_HELPTOPIC"
#define GDAL_DMD_MIMETYPE "DMD_MIMETYPE"
#define GDAL_DMD_EXTENSION "DMD_EXTENSION"
#define GDAL_DMD_CREATIONOPTIONLIST "DMD_CREATIONOPTIONLIST" 
#define GDAL_DMD_CREATIONDATATYPES "DMD_CREATIONDATATYPES" 

#define GDAL_DCAP_CREATE     "DCAP_CREATE"
#define GDAL_DCAP_CREATECOPY "DCAP_CREATECOPY"

void CPL_DLL GDALAllRegister( void );

GDALDatasetH CPL_DLL GDALCreate( GDALDriverH hDriver,
                                 const char *, int, int, int, GDALDataType,
                                 char ** );
GDALDatasetH CPL_DLL GDALCreateCopy( GDALDriverH, const char *, GDALDatasetH,
                                     int, char **, GDALProgressFunc, void * );

GDALDatasetH CPL_DLL GDALOpen( const char *pszFilename, GDALAccess eAccess );
GDALDatasetH CPL_DLL GDALOpenShared( const char *, GDALAccess );
int          CPL_DLL GDALDumpOpenDatasets( FILE * );

GDALDriverH CPL_DLL GDALGetDriverByName( const char * );
int CPL_DLL         GDALGetDriverCount();
GDALDriverH CPL_DLL GDALGetDriver( int );
int         CPL_DLL GDALRegisterDriver( GDALDriverH );
void        CPL_DLL GDALDeregisterDriver( GDALDriverH );
void        CPL_DLL GDALDestroyDriverManager( void );
CPLErr      CPL_DLL GDALDeleteDataset( GDALDriverH, const char * );

/* The following are deprecated */
const char CPL_DLL *GDALGetDriverShortName( GDALDriverH );
const char CPL_DLL *GDALGetDriverLongName( GDALDriverH );
const char CPL_DLL *GDALGetDriverHelpTopic( GDALDriverH );

/* ==================================================================== */
/*      GDAL_GCP                                                        */
/* ==================================================================== */

typedef struct
{
    char        *pszId; 

    char        *pszInfo;

    double      dfGCPPixel;
    double      dfGCPLine;

    double      dfGCPX;

    double      dfGCPY;

    double      dfGCPZ;
} GDAL_GCP;

void CPL_DLL GDALInitGCPs( int, GDAL_GCP * );
void CPL_DLL GDALDeinitGCPs( int, GDAL_GCP * );
GDAL_GCP CPL_DLL *GDALDuplicateGCPs( int, const GDAL_GCP * );

int CPL_DLL GDALGCPsToGeoTransform( int nGCPCount, const GDAL_GCP *pasGCPs, 
                                    double *padfGeoTransform, int bApproxOK ); 
int CPL_DLL GDALInvGeoTransform( double *padfGeoTransformIn, 
                                 double *padfInvGeoTransformOut );

/* ==================================================================== */
/*      major objects (dataset, and, driver, drivermanager).            */
/* ==================================================================== */

char CPL_DLL  **GDALGetMetadata( GDALMajorObjectH, const char * );
CPLErr CPL_DLL  GDALSetMetadata( GDALMajorObjectH, char **,
                                 const char * );
const char CPL_DLL *GDALGetMetadataItem( GDALMajorObjectH, const char *, 
                                         const char * );
CPLErr CPL_DLL  GDALSetMetadataItem( GDALMajorObjectH,
                                     const char *, const char *,
                                     const char * );
const char CPL_DLL *GDALGetDescription( GDALMajorObjectH );
void       CPL_DLL  GDALSetDescription( GDALMajorObjectH, const char * );

/* ==================================================================== */
/*      GDALDataset class ... normally this represents one file.        */
/* ==================================================================== */

GDALDriverH CPL_DLL GDALGetDatasetDriver( GDALDatasetH );
void CPL_DLL   GDALClose( GDALDatasetH );
int CPL_DLL     GDALGetRasterXSize( GDALDatasetH );
int CPL_DLL     GDALGetRasterYSize( GDALDatasetH );
int CPL_DLL     GDALGetRasterCount( GDALDatasetH );
GDALRasterBandH CPL_DLL GDALGetRasterBand( GDALDatasetH, int );

CPLErr CPL_DLL  GDALAddBand( GDALDatasetH hDS, GDALDataType eType, 
                             char **papszOptions );

CPLErr CPL_DLL GDALDatasetRasterIO( 
    GDALDatasetH hDS, GDALRWFlag eRWFlag,
    int nDSXOff, int nDSYOff, int nDSXSize, int nDSYSize,
    void * pBuffer, int nBXSize, int nBYSize, GDALDataType eBDataType,
    int nBandCount, int *panBandCount, 
    int nPixelSpace, int nLineSpace, int nBandSpace);

const char CPL_DLL *GDALGetProjectionRef( GDALDatasetH );
CPLErr CPL_DLL  GDALSetProjection( GDALDatasetH, const char * );
CPLErr CPL_DLL  GDALGetGeoTransform( GDALDatasetH, double * );
CPLErr CPL_DLL  GDALSetGeoTransform( GDALDatasetH, double * );

int CPL_DLL     GDALGetGCPCount( GDALDatasetH );
const char CPL_DLL *GDALGetGCPProjection( GDALDatasetH );
const GDAL_GCP CPL_DLL *GDALGetGCPs( GDALDatasetH );
CPLErr CPL_DLL  GDALSetGCPs( GDALDatasetH, int, const GDAL_GCP *,
                             const char * );

void CPL_DLL   *GDALGetInternalHandle( GDALDatasetH, const char * );
int CPL_DLL     GDALReferenceDataset( GDALDatasetH );
int CPL_DLL     GDALDereferenceDataset( GDALDatasetH );

CPLErr CPL_DLL  GDALBuildOverviews( GDALDatasetH, const char *, int, int *,
                                    int, int *, GDALProgressFunc, void * );
void CPL_DLL    GDALGetOpenDatasets( GDALDatasetH ***hDS, int *pnCount );
int CPL_DLL     GDALGetAccess( GDALDatasetH hDS );
void CPL_DLL    GDALFlushCache( GDALDatasetH hDS );

/* ==================================================================== */
/*      GDALRasterBand ... one band/channel in a dataset.               */
/* ==================================================================== */

GDALDataType CPL_DLL GDALGetRasterDataType( GDALRasterBandH );
void CPL_DLL    GDALGetBlockSize( GDALRasterBandH,
                                  int * pnXSize, int * pnYSize );

CPLErr CPL_DLL GDALRasterIO( GDALRasterBandH hRBand, GDALRWFlag eRWFlag,
                              int nDSXOff, int nDSYOff,
                              int nDSXSize, int nDSYSize,
                              void * pBuffer, int nBXSize, int nBYSize,
                              GDALDataType eBDataType,
                              int nPixelSpace, int nLineSpace );
CPLErr CPL_DLL GDALReadBlock( GDALRasterBandH, int, int, void * );
CPLErr CPL_DLL GDALWriteBlock( GDALRasterBandH, int, int, void * );
int CPL_DLL GDALGetRasterBandXSize( GDALRasterBandH );
int CPL_DLL GDALGetRasterBandYSize( GDALRasterBandH );
char CPL_DLL  **GDALGetRasterMetadata( GDALRasterBandH );
GDALAccess CPL_DLL GDALGetRasterAccess( GDALRasterBandH );
int CPL_DLL GDALGetBandNumber( GDALRasterBandH );
GDALDatasetH CPL_DLL GDALGetBandDataset( GDALRasterBandH );

GDALColorInterp CPL_DLL GDALGetRasterColorInterpretation( GDALRasterBandH );
CPLErr CPL_DLL GDALSetRasterColorInterpretation( GDALRasterBandH,
                                                 GDALColorInterp );
GDALColorTableH CPL_DLL GDALGetRasterColorTable( GDALRasterBandH );
CPLErr CPL_DLL GDALSetRasterColorTable( GDALRasterBandH, GDALColorTableH );
int CPL_DLL     GDALHasArbitraryOverviews( GDALRasterBandH );
int CPL_DLL             GDALGetOverviewCount( GDALRasterBandH );
GDALRasterBandH CPL_DLL GDALGetOverview( GDALRasterBandH, int );
double CPL_DLL GDALGetRasterNoDataValue( GDALRasterBandH, int * );
CPLErr CPL_DLL GDALSetRasterNoDataValue( GDALRasterBandH, double );
char CPL_DLL ** GDALGetRasterCategoryNames( GDALRasterBandH );
CPLErr CPL_DLL GDALSetRasterCategoryNames( GDALRasterBandH, char ** );
double CPL_DLL GDALGetRasterMinimum( GDALRasterBandH, int *pbSuccess );
double CPL_DLL GDALGetRasterMaximum( GDALRasterBandH, int *pbSuccess );
const char CPL_DLL *GDALGetRasterUnitType( GDALRasterBandH );
void CPL_DLL GDALComputeRasterMinMax( GDALRasterBandH hBand, int bApproxOK,
                                      double adfMinMax[2] );
CPLErr CPL_DLL GDALFlushRasterCache( GDALRasterBandH hBand );
CPLErr CPL_DLL GDALGetRasterHistogram( GDALRasterBandH hBand,
                                       double dfMin, double dfMax,
                                       int nBuckets, int *panHistogram,
                                       int bIncludeOutOfRange, int bApproxOK,
                                       GDALProgressFunc pfnProgress,
                                       void * pProgressData );
int CPL_DLL GDALGetRandomRasterSample( GDALRasterBandH, int, float * );
GDALRasterBandH CPL_DLL GDALGetRasterSampleOverview( GDALRasterBandH, int );
CPLErr CPL_DLL GDALFillRaster( GDALRasterBandH hBand, double dfRealValue,
                       double dfImaginaryValue );
CPLErr GDALComputeBandStats( GDALRasterBandH hBand, int nSampleStep, 
                             double *pdfMean, double *pdfStdDev, 
                             GDALProgressFunc pfnProgress,
                             void *pProgressData );
CPLErr GDALOverviewMagnitudeCorrection( GDALRasterBandH hBaseBand, 
                                        int nOverviewCount, 
                                        GDALRasterBandH *pahOverviews, 
                                        GDALProgressFunc pfnProgress, 
                                        void *pProgressData );

/* -------------------------------------------------------------------- */
/*      Helper functions.                                               */
/* -------------------------------------------------------------------- */
void CPL_DLL GDALSwapWords( void *pData, int nWordSize, int nWordCount,
                            int nWordSkip );
void CPL_DLL
    GDALCopyWords( void * pSrcData, GDALDataType eSrcType, int nSrcPixelOffset,
                   void * pDstData, GDALDataType eDstType, int nDstPixelOffset,
                   int nWordCount );

int CPL_DLL GDALReadWorldFile( const char *pszBaseFilename, 
                       const char *pszExtension, 
                       double * padfGeoTransform );
int CPL_DLL GDALWriteWorldFile( const char *pszBaseFilename, 
                       const char *pszExtension, 
                       double * padfGeoTransform );
int CPL_DLL GDALReadTabFile( const char *pszBaseFilename, 
                             double *padfGeoTransform, char **ppszWKT,
                             int *pnGCPCount, GDAL_GCP **ppasGCPs );

const char CPL_DLL *GDALDecToDMS( double, const char *, int );
double CPL_DLL GDALPackedDMSToDec( double );
double CPL_DLL GDALDecToPackedDMS( double );

const char CPL_DLL *GDALVersionInfo( const char * );

typedef struct { 
    double      dfLINE_OFF;
    double      dfSAMP_OFF;
    double      dfLAT_OFF;
    double      dfLONG_OFF;
    double      dfHEIGHT_OFF;

    double      dfLINE_SCALE;
    double      dfSAMP_SCALE;
    double      dfLAT_SCALE;
    double      dfLONG_SCALE;
    double      dfHEIGHT_SCALE;

    double      adfLINE_NUM_COEFF[20];
    double      adfLINE_DEN_COEFF[20];
    double      adfSAMP_NUM_COEFF[20];
    double      adfSAMP_DEN_COEFF[20];
    
    double      dfMIN_LONG;
    double      dfMIN_LAT;
    double      dfMAX_LONG;
    double      dfMAX_LAT;

} GDALRPCInfo;

int CPL_DLL GDALExtractRPCInfo( char **, GDALRPCInfo * );

/* ==================================================================== */
/*      Color tables.                                                   */
/* ==================================================================== */
typedef struct
{
    short      c1;      

    short      c2;      

    short      c3;      

    short      c4;      
} GDALColorEntry;

GDALColorTableH CPL_DLL GDALCreateColorTable( GDALPaletteInterp );
void CPL_DLL            GDALDestroyColorTable( GDALColorTableH );
GDALColorTableH CPL_DLL GDALCloneColorTable( GDALColorTableH );
GDALPaletteInterp CPL_DLL GDALGetPaletteInterpretation( GDALColorTableH );
int CPL_DLL             GDALGetColorEntryCount( GDALColorTableH );
const GDALColorEntry CPL_DLL *GDALGetColorEntry( GDALColorTableH, int );
int CPL_DLL GDALGetColorEntryAsRGB( GDALColorTableH, int, GDALColorEntry *);
void CPL_DLL GDALSetColorEntry( GDALColorTableH, int, const GDALColorEntry * );

/* ==================================================================== */
/*      GDAL Cache Management                                           */
/* ==================================================================== */

void CPL_DLL GDALSetCacheMax( int nBytes );
int CPL_DLL GDALGetCacheMax();
int CPL_DLL GDALGetCacheUsed();
int CPL_DLL GDALFlushCacheBlock();

CPL_C_END

#endif /* ndef GDAL_H_INCLUDED */

---