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

gdal.h File Reference

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

Go to the source code of this file.

Compounds

struct  GDAL_GCP
struct  GDALColorEntry
struct  GDALOptionDefinition

Defines

#define GDAL_VERSION_NUM   1180
#define GDAL_RELEASE_DATE   20021221
#define GDAL_RELEASE_NAME   "1.1.8.0"
#define CPLE_WrongFormat   200
#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"

Typedefs

typedef void* GDALMajorObjectH
typedef void* GDALDatasetH
typedef void* GDALRasterBandH
typedef void* GDALDriverH
typedef void* GDALProjDefH
typedef void* GDALColorTableH
typedef int (* GDALProgressFunc )(double,const char *, void *)

Enumerations

enum  GDALDataType {
  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
}
enum  GDALAccess { GA_ReadOnly = 0, GA_Update = 1 }
enum  GDALRWFlag { GF_Read = 0, GF_Write = 1 }
enum  GDALColorInterp {
  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
}
enum  GDALPaletteInterp { GPI_Gray = 0, GPI_RGB = 1, GPI_CMYK = 2, GPI_HLS = 3 }

Functions

int CPL_DLL GDALGetDataTypeSize ( GDALDataType )
int CPL_DLL GDALDataTypeIsComplex ( GDALDataType )
const char CPL_DLL* GDALGetDataTypeName ( GDALDataType )
GDALDataType CPL_DLL GDALDataTypeUnion ( GDALDataType, GDALDataType )
const char CPL_DLL* GDALGetColorInterpretationName ( GDALColorInterp )
const char CPL_DLL* GDALGetPaletteInterpretationName ( GDALPaletteInterp )
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 * )
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 *, GDALAccess )
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 * )
const char CPL_DLL* GDALGetDriverShortName ( GDALDriverH )
const char CPL_DLL* GDALGetDriverLongName ( GDALDriverH )
const char CPL_DLL* GDALGetDriverHelpTopic ( GDALDriverH )
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 )
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 * )
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 )
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 )
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 )
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 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 )
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 )
const char CPL_DLL* GDALVersionInfo ( const char * )
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 * )
void CPL_DLL GDALSetCacheMax ( int nBytes )
int CPL_DLL GDALGetCacheMax ()
int CPL_DLL GDALGetCacheUsed ()
int CPL_DLL GDALFlushCacheBlock ()


Detailed Description

Public (C callable) GDAL entry points.


Typedef Documentation

typedef int (* GDALProgressFunc)(double,const char *, void *)
 

Progresss function signature, see GDALDummyProgress() for details.


Enumeration Type Documentation

enum GDALAccess
 

Flag indicating read/write, or read-only access to data.

Enumeration values:
GA_ReadOnly   Read only (no update) access
GA_Update   Read/write access.

enum GDALColorInterp
 

Types of color interpretation for raster bands.

Enumeration values:
GCI_GrayIndex   Greyscale
GCI_PaletteIndex   Paletted (see associated color table)
GCI_RedBand   Red band of RGBA image
GCI_GreenBand   Green band of RGBA image
GCI_BlueBand   Blue band of RGBA image
GCI_AlphaBand   Alpha (0=transparent, 255=opaque)
GCI_HueBand   Hue band of HLS image
GCI_SaturationBand   Saturation band of HLS image
GCI_LightnessBand   Lightness band of HLS image
GCI_CyanBand   Cyan band of CMYK image
GCI_MagentaBand   Magenta band of CMYK image
GCI_YellowBand   Yellow band of CMYK image
GCI_BlackBand   Black band of CMLY image

enum GDALDataType
 

Pixel data types

Enumeration values:
GDT_Byte   Eight bit unsigned integer
GDT_UInt16   Sixteen bit unsigned integer
GDT_Int16   Sixteen bit signed integer
GDT_UInt32   Thirty two bit unsigned integer
GDT_Int32   Thirty two bit signed integer
GDT_Float32   Thirty two bit floating point
GDT_Float64   Sixty four bit floating point
GDT_CInt16   Complex Int16
GDT_CInt32   Complex Int32
GDT_CFloat32   Complex Float32
GDT_CFloat64   Complex Float64

enum GDALPaletteInterp
 

Types of color interpretations for a GDALColorTable.

Enumeration values:
GPI_Gray   Grayscale (in GDALColorEntry.c1)
GPI_RGB   Red, Green, Blue and Alpha in (in c1, c2, c3 and c4)
GPI_CMYK   Cyan, Magenta, Yellow and Black (in c1, c2, c3 and c4)
GPI_HLS   Hue, Lightness and Saturation (in c1, c2, and c3)

enum GDALRWFlag
 

Read/Write flag for RasterIO() method

Enumeration values:
GF_Read   Read data
GF_Write   Write data


Function Documentation

void GDALAllRegister ( void )
 

Register all known configured GDAL drivers.

This function will drive any of the following that are configured into GDAL. Possible others as well that haven't been updated in this documentation:

  • GeoTIFF (GTiff)
  • Geosoft GXF (GXF)
  • Erdas Imagine (HFA)
  • CEOS (CEOS)
  • ELAS (ELAS)
  • Arc/Info Binary Grid (AIGrid)
  • SDTS Raster DEM (SDTS)
  • OGDI (OGDI)
  • ESRI Labelled BIL (EHdr)
  • PCI .aux Labelled Raw Raster (PAux)

void GDALComputeRasterMinMax ( GDALRasterBandH hBand,
int bApproxOK,
double adfMinMax[2] )
 

Compute the min/max values for a band.

If approximate is OK, then the band's GetMinimum()/GetMaximum() will be trusted. If it doesn't work, a subsample of blocks will be read to get an approximate min/max. If the band has a nodata value it will be excluded from the minimum and maximum.

If bApprox is FALSE, then all pixels will be read and used to compute an exact range.

Parameters:
hBand   the band to copmute the range for.
bApproxOK   TRUE if an approximate (faster) answer is OK, otherwise FALSE.
adfMinMax   the array in which the minimum (adfMinMax[0]) and the maximum (adfMinMax[1]) are returned.

GDALDataType GDALDataTypeUnion ( GDALDataType eType1,
GDALDataType eType2 )
 

Return the smallest data type that can fully express both input data types.

Parameters:
eType1  
eType2  

Returns:
a data type able to express eType1 and eType2.

void GDALDestroyDriverManager ( void )
 

Destroy the driver manager.

Incidently unloads all managed drivers.

int GDALDummyProgress ( double,
const char *,
void * )
 

Stub progress function.

Many long running operations within GDAL the option of passing a progress function. The progress function is intended to provide a way of displaying a progress indicator to the user, and for the user to terminate the process prematurely. Applications not desiring to utilize this support should normally pass GDALDummyProgress as the pfnProgress argument and NULL as the pData argument.

Applications wishing to take advantage of the progress semantics should pass a function implementing GDALProgressFunc semantics.

 typedef int (*GDALProgressFunc)(double dfComplete,
                                 const char *pszMessage, 
                                 void *pData);
 
Parameters:
dfComplete   Passed in the with ratio of the operation that is complete, and is a value between 0.0 and 1.0.
pszMessage   This is normally passed in as NULL, but will occasionally be passed in with a message about what is happening that may be displayed to the user.
pData   Application data (as passed via pData into GDAL operation).

Returns:
TRUE if the operation should continue, or FALSE if the user has requested a cancel.

For example, an application might implement the following simple text progress reporting mechanism, using pData to pass a default message:

 int MyTextProgress( double dfComplete, const char *pszMessage, void *pData)
 {
     if( pszMessage != NULL )
         printf( "d%% complete: s
", (int) (dfComplete*100), pszMessage ); else if( pData != NULL ) printf( "d%% complete:s
", (int) (dfComplete*100), (char *) pData ); else printf( "d%% complete.\n", (int) (dfComplete*100) ); return TRUE; }

This could be utilized with the GDALDataset::BuildOverviews() method like this:

      int       anOverviewList[3] = {2, 4, 8};

      poDataset->BuildOverviews( "NEAREST", 3, anOverviewList, 0, NULL, 
                                 MyTextProgress, "building overviews" );
 

More often that implementing custom progress functions, applications will just use existing progress functions like GDALDummyProgress(), and GDALScaledProgress(). Python scripts also can pass progress functions.

int GDALGCPsToGeoTransform ( int nGCPCount,
const GDAL_GCP * pasGCPs,
double * padfGeoTransform,
int bApproxOK )
 

Generate Geotransform from GCPs.

Given a set of GCPs perform first order fit as a geotransform.

Parameters:
nGCPCount   the number of GCPs being passed in.
pasGCPs   the list of GCP structures.
padfGeoTransform   the six double array in which the affine geotransformation will be returned.
bApproxOK   If FALSE the function will fail if the geotransform is not essentially an exact fit (within 0.25 pixel) for all GCPs.

Returns:
TRUE on success or FALSE if there aren't enough points to prepare a geotransform, or if bApproxOK is FALSE and the fit is poor.

const char * GDALGetColorInterpretationName ( GDALColorInterp eInterp )
 

Translate a GDALColorInterp into a user displayable string.

const char * GDALGetPaletteInterpretationName ( GDALPaletteInterp eInterp )
 

Translate a GDALPaletteInterp into a user displayable string.

GDALRasterBandH GDALGetRasterSampleOverview ( GDALRasterBandH hBand,
int nDesiredSamples )
 

Fetch best sampling overview.

Returns the most reduced overview of the given band that still satisfies the desired number of samples. This function can be used with zero as the number of desired samples to fetch the most reduced overview. The same band as was passed in will be returned if it has not overviews, or if none of the overviews have enough samples.

Parameters:
hBand   the band to search for overviews on.
nDesiredSamples   the returned band will have at least this many pixels.
Returns:
optimal overview or hBand itself.

GDALDatasetH GDALOpen ( const char * pszFilename,
GDALAccess eAccess )
 

Open a raster file as a GDALDataset.

See Also: GDALOpenShared()

Parameters:
pszFilename   the name of the file to access. In the case of exotic drivers this may not refer to a physical file, but instead contain information for the driver on how to access a dataset.
eAccess   the desired access, either GA_Update or GA_ReadOnly. Many drivers support only read only access.

Returns:
A GDALDatasetH handle or NULL on failure. For C++ applications this handle can be cast to a GDALDataset *.

GDALDatasetH GDALOpenShared ( const char * pszFilename,
GDALAccess eAccess )
 

Open a raster file as a GDALDataset.

This function works the same as GDALOpen(), but allows the sharing of GDALDataset handles for a dataset with other callers to GDALOpenShared().

In particular, GDALOpenShared() will first consult it's list of currently open and shared GDALDataset's, and if the GetDescription() name for one exactly matches the pszFilename passed to GDALOpenShared() it

Parameters:
pszFilename   the name of the file to access. In the case of exotic drivers this may not refer to a physical file, but instead contain information for the driver on how to access a dataset.
eAccess   the desired access, either GA_Update or GA_ReadOnly. Many drivers support only read only access.

Returns:
A GDALDatasetH handle or NULL on failure. For C++ applications this handle can be cast to a GDALDataset *.

const char * GDALVersionInfo ( const char * pszRequest )
 

Get runtime version information.

Available pszRequest values:

  • "VERSION_NUM": Returns GDAL_VERSION_NUM formatted as a string. ie. "1170"
  • "RELEASE_DATE": Returns GDAL_RELEASE_DATE formatted as a string. ie. "20020416".
  • "RELEASE_NAME": Returns the GDAL_RELEASE_NAME. ie. "1.1.7"
  • "--version": Returns one line version message suitable for use in response to --version requests. ie. "GDAL 1.1.7, released 2002/04/16"
Parameters:
pszRequest   the type of version info desired, as listed above.

Returns:
an internal string containing the requested information.


Generated at Sat Dec 21 14:02:02 2002 for GDAL by doxygen1.2.3-20001105 written by Dimitri van Heesch, © 1997-2000