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
## Defines
#define | GDAL_VERSION_NUM 1160
#define | GDAL_RELEASE_DATE 20020204
#define | GDAL_RELEASE_NAME "1.1.6"
#define | CPLE_WrongFormat 200
## 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 )
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 )
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 * )
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 )
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 * )
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 )
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 | GDALReadWorldFile ( const char *pszBaseFilename, const char *pszExtension, double * padfGeoTransform )
const char CPL_DLL* | GDALDecToDMS ( double, const char *, int )
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.

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.

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