1 /****************************************************************************** 2 * 3 * Name: gdal_priv.h 4 * Project: GDAL Core 5 * Purpose: GDAL Core C++/Private declarations. 6 * Author: Frank Warmerdam, warmerdam@pobox.com 7 * 8 ****************************************************************************** 9 * Copyright (c) 1998, Frank Warmerdam 10 * 11 * Permission is hereby granted, free of charge, to any person obtaining a 12 * copy of this software and associated documentation files (the "Software"), 13 * to deal in the Software without restriction, including without limitation 14 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 15 * and/or sell copies of the Software, and to permit persons to whom the 16 * Software is furnished to do so, subject to the following conditions: 17 * 18 * The above copyright notice and this permission notice shall be included 19 * in all copies or substantial portions of the Software. 20 * 21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 22 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 24 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 26 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 27 * DEALINGS IN THE SOFTWARE. 28 ****************************************************************************** 29 * 30 * $Log: gdal_priv.h,v $ 31 * Revision 1.1.1.1 2006/08/21 05:52:20 dsr 32 * Initial import as opencpn, GNU Automake compliant. 33 * 34 * Revision 1.1.1.1 2006/04/19 03:23:28 dsr 35 * Rename/Import to OpenCPN 36 * 37 * Revision 1.46 2003/07/27 11:01:01 dron 38 * GDALRasterBlock::IsCached() method added. 39 * 40 * Revision 1.45 2003/05/08 14:38:40 warmerda 41 * added BlockBasedFlushCache 42 * 43 * Revision 1.44 2003/05/06 05:20:38 sperkins 44 * cleaned up comments 45 * 46 * Revision 1.43 2003/05/06 05:13:36 sperkins 47 * added Fill() and GDALFillRaster() 48 * 49 * Revision 1.42 2003/04/25 19:47:57 warmerda 50 * added RasterIO on GDALDataset, added lock count on blocks 51 * 52 * Revision 1.41 2003/03/20 22:10:53 warmerda 53 * added support for reporting cache thrashing 54 * 55 * Revision 1.40 2003/03/18 06:00:57 warmerda 56 * made GDALRasterBand::FlushCache() virtual 57 * 58 * Revision 1.39 2003/01/28 16:07:30 warmerda 59 * improved documentation 60 * 61 * Revision 1.38 2002/10/21 18:05:42 warmerda 62 * added AutoSkipDrivers() method on driver manager 63 * 64 * Revision 1.37 2002/09/11 14:17:52 warmerda 65 * make SetDescription() and GetDescription() virtual 66 * 67 * Revision 1.36 2002/09/04 06:52:05 warmerda 68 * added unload driver support to GDALDriver 69 * 70 * Revision 1.35 2002/07/09 20:33:12 warmerda 71 * expand tabs 72 * 73 * Revision 1.34 2002/06/19 18:19:59 warmerda 74 * GDALOpenInfo: added bIsDirecory flag, removed VSIStatBuf 75 * 76 * Revision 1.33 2002/06/12 21:13:27 warmerda 77 * use metadata based driver info 78 * 79 * Revision 1.32 2002/05/29 15:58:26 warmerda 80 * removed GetDescription(), added SetColorInterpretation() 81 * 82 * Revision 1.31 2002/05/28 18:56:22 warmerda 83 * added shared dataset concept 84 * 85 * Revision 1.30 2002/03/01 14:29:09 warmerda 86 * added GetBand() method on GDALRasterBand 87 * 88 * Revision 1.29 2001/12/15 15:42:27 warmerda 89 * *** empty log message *** 90 * 91 * Revision 1.28 2001/11/18 00:52:15 warmerda 92 * removed GDALProjDef 93 * 94 * Revision 1.27 2001/11/16 21:36:01 warmerda 95 * added the AddBand() method on GDALDataset 96 * 97 * Revision 1.26 2001/10/17 21:47:02 warmerda 98 * added SetGCPs() on GDALDataset 99 * 100 * Revision 1.25 2001/10/02 13:15:16 warmerda 101 * added CPL_DLL for GDALDefaultOverviews 102 * 103 * Revision 1.24 2001/06/20 16:08:54 warmerda 104 * GDALDefaultOverviews now remembers ovr filename, and allows explicit setting 105 * 106 * Revision 1.23 2001/02/06 16:30:21 warmerda 107 * Added gdal_frmts.h 108 * 109 * Revision 1.22 2000/10/06 15:26:08 warmerda 110 * added SetNoDataValue, SetCategoryNames 111 * 112 * Revision 1.21 2000/07/20 13:38:26 warmerda 113 * make GetGDALDriverManager public with CPL_DLL 114 * 115 * Revision 1.20 2000/04/30 23:22:16 warmerda 116 * added CreateCopy support 117 * 118 * Revision 1.19 2000/04/21 21:55:01 warmerda 119 * majorobject updates, and overview building 120 * 121 * Revision 1.18 2000/04/04 23:44:29 warmerda 122 * added AutoLoadDrivers() to GDALDriverManager 123 * 124 * Revision 1.17 2000/03/31 13:41:24 warmerda 125 * added gcps 126 * 127 * Revision 1.16 2000/03/24 00:09:05 warmerda 128 * rewrote cache management 129 * 130 * Revision 1.15 2000/03/09 23:22:03 warmerda 131 * added GetHistogram 132 * 133 * Revision 1.14 2000/03/06 02:20:35 warmerda 134 * added colortables, overviews, etc 135 * 136 * Revision 1.12 2000/01/31 15:00:25 warmerda 137 * added some documentation 138 * 139 * Revision 1.11 2000/01/31 14:24:36 warmerda 140 * implemented dataset delete 141 * 142 * Revision 1.10 1999/11/11 21:59:07 warmerda 143 * added GetDriver() for datasets 144 * 145 * Revision 1.9 1999/10/21 13:23:45 warmerda 146 * Added a bit of driver related documentation. 147 * 148 * Revision 1.8 1999/10/21 12:04:11 warmerda 149 * Reorganized header. 150 * 151 * Revision 1.7 1999/10/01 14:44:02 warmerda 152 * added documentation 153 * 154 * Revision 1.6 1999/04/21 04:16:25 warmerda 155 * experimental docs 156 * 157 * Revision 1.5 1999/01/11 15:36:18 warmerda 158 * Added projections support, and a few other things. 159 * 160 * Revision 1.4 1998/12/31 18:54:25 warmerda 161 * Implement initial GDALRasterBlock support, and block cache 162 * 163 * Revision 1.3 1998/12/06 22:17:09 warmerda 164 * Fill out rasterio support. 165 * 166 * Revision 1.2 1998/12/03 18:34:06 warmerda 167 * Update to use CPL 168 * 169 * Revision 1.1 1998/10/18 06:15:11 warmerda 170 * Initial implementation. 171 * 172 */ 173 174 #ifndef GDAL_PRIV_H_INCLUDED 175 #define GDAL_PRIV_H_INCLUDED 176 177 /* -------------------------------------------------------------------- */ 178 /* Predeclare various classes before pulling in gdal.h, the */ 179 /* public declarations. */ 180 /* -------------------------------------------------------------------- */ 181 class GDALMajorObject; 182 class GDALDataset; 183 class GDALRasterBand; 184 class GDALDriver; 185 186 /* -------------------------------------------------------------------- */ 187 /* Pull in the public declarations. This gets the C apis, and */ 188 /* also various constants. However, we will still get to */ 189 /* provide the real class definitions for the GDAL classes. */ 190 /* -------------------------------------------------------------------- */ 191 192 #include "gdal.h" 193 #include "gdal_frmts.h" 194 #include "cpl_vsi.h" 195 #include "cpl_conv.h" 196 197 /* ******************************************************************** */ 198 /* GDALMajorObject */ 199 /* */ 200 /* Base class providing metadata, description and other */ 201 /* services shared by major objects. */ 202 /* ******************************************************************** */ 203 204 class CPL_DLL GDALMajorObject 205 { 206 protected: 207 char *pszDescription; 208 char **papszMetadata; 209 210 public: 211 GDALMajorObject(); 212 virtual ~GDALMajorObject(); 213 214 virtual const char *GetDescription() const; 215 virtual void SetDescription( const char * ); 216 217 virtual char **GetMetadata( const char * pszDomain = "" ); 218 virtual CPLErr SetMetadata( char ** papszMetadata, 219 const char * pszDomain = "" ); 220 virtual const char *GetMetadataItem( const char * pszName, 221 const char * pszDomain = "" ); 222 virtual CPLErr SetMetadataItem( const char * pszName, 223 const char * pszValue, 224 const char * pszDomain = "" ); 225 }; 226 227 /* ******************************************************************** */ 228 /* GDALDefaultOverviews */ 229 /* ******************************************************************** */ 230 class CPL_DLL GDALDefaultOverviews 231 { 232 GDALDataset *poDS; 233 GDALDataset *poODS; 234 235 char *pszOvrFilename; 236 237 public: 238 GDALDefaultOverviews(); 239 ~GDALDefaultOverviews(); 240 241 void Initialize( GDALDataset *poDS, const char *pszName = NULL, 242 int bNameIsOVR = FALSE ); IsInitialized()243 int IsInitialized() { return poDS != NULL; } 244 245 int GetOverviewCount(int); 246 GDALRasterBand *GetOverview(int,int); 247 248 CPLErr BuildOverviews( const char * pszBasename, 249 const char * pszResampling, 250 int nOverviews, int * panOverviewList, 251 int nBands, int * panBandList, 252 GDALProgressFunc pfnProgress, 253 void *pProgressData ); 254 }; 255 256 /* ******************************************************************** */ 257 /* GDALDataset */ 258 /* ******************************************************************** */ 259 260 class CPL_DLL GDALDataset : public GDALMajorObject 261 { 262 friend GDALDatasetH GDALOpen( const char *, GDALAccess); 263 friend GDALDatasetH GDALOpenShared( const char *, GDALAccess); 264 friend class GDALDriver; 265 266 protected: 267 GDALDriver *poDriver; 268 GDALAccess eAccess; 269 270 // Stored raster information. 271 int nRasterXSize; 272 int nRasterYSize; 273 int nBands; 274 GDALRasterBand **papoBands; 275 276 int nRefCount; 277 int bShared; 278 279 GDALDataset(void); 280 void RasterInitialize( int, int ); 281 void SetBand( int, GDALRasterBand * ); 282 283 GDALDefaultOverviews oOvManager; 284 285 virtual CPLErr IBuildOverviews( const char *, int, int *, 286 int, int *, GDALProgressFunc, void * ); 287 288 virtual CPLErr IRasterIO( GDALRWFlag, int, int, int, int, 289 void *, int, int, GDALDataType, 290 int, int *, int, int, int ); 291 292 CPLErr BlockBasedRasterIO( GDALRWFlag, int, int, int, int, 293 void *, int, int, GDALDataType, 294 int, int *, int, int, int ); 295 void BlockBasedFlushCache(); 296 297 friend class GDALRasterBand; 298 299 public: 300 virtual ~GDALDataset(); 301 302 int GetRasterXSize( void ); 303 int GetRasterYSize( void ); 304 int GetRasterCount( void ); 305 GDALRasterBand *GetRasterBand( int ); 306 307 virtual void FlushCache(void); 308 309 virtual const char *GetProjectionRef(void); 310 virtual CPLErr SetProjection( const char * ); 311 312 virtual CPLErr GetGeoTransform( double * ); 313 virtual CPLErr SetGeoTransform( double * ); 314 315 virtual CPLErr AddBand( GDALDataType eType, 316 char **papszOptions=NULL ); 317 318 virtual void *GetInternalHandle( const char * ); 319 virtual GDALDriver *GetDriver(void); 320 321 virtual int GetGCPCount(); 322 virtual const char *GetGCPProjection(); 323 virtual const GDAL_GCP *GetGCPs(); 324 virtual CPLErr SetGCPs( int nGCPCount, const GDAL_GCP *pasGCPList, 325 const char *pszGCPProjection ); 326 327 CPLErr RasterIO( GDALRWFlag, int, int, int, int, 328 void *, int, int, GDALDataType, 329 int, int *, int, int, int ); 330 331 int Reference(); 332 int Dereference(); GetAccess()333 GDALAccess GetAccess() { return eAccess; } 334 335 int GetShared(); 336 void MarkAsShared(); 337 338 static GDALDataset **GetOpenDatasets( int *pnDatasetCount ); 339 340 CPLErr BuildOverviews( const char *, int, int *, 341 int, int *, GDALProgressFunc, void * ); 342 }; 343 344 /* ******************************************************************** */ 345 /* GDALRasterBlock */ 346 /* ******************************************************************** */ 347 348 /*! A cached raster block ... to be documented later. */ 349 350 class CPL_DLL GDALRasterBlock 351 { 352 GDALDataType eType; 353 354 int nAge; 355 int bDirty; 356 int nLockCount; 357 358 int nXOff; 359 int nYOff; 360 361 int nXSize; 362 int nYSize; 363 364 void *pData; 365 366 GDALRasterBand *poBand; 367 368 GDALRasterBlock *poNext; 369 GDALRasterBlock *poPrevious; 370 371 public: 372 GDALRasterBlock( GDALRasterBand *, int, int ); 373 virtual ~GDALRasterBlock(); 374 375 CPLErr Internalize( void ); /* make copy of data */ 376 void Touch( void ); /* update age */ 377 void MarkDirty( void ); /* data has been modified since read */ 378 void MarkClean( void ); AddLock(void)379 void AddLock( void ) { nLockCount++; } DropLock(void)380 void DropLock( void ) { nLockCount--; } 381 382 CPLErr Write(); 383 GetDataType()384 GDALDataType GetDataType() { return eType; } GetXOff()385 int GetXOff() { return nXOff; } GetYOff()386 int GetYOff() { return nYOff; } GetXSize()387 int GetXSize() { return nXSize; } GetYSize()388 int GetYSize() { return nYSize; } GetAge()389 int GetAge() { return nAge; } GetDirty()390 int GetDirty() { return bDirty; } GetLockCount()391 int GetLockCount() { return nLockCount; } 392 GetDataRef(void)393 void *GetDataRef( void ) { return pData; } 394 GetBand()395 GDALRasterBand *GetBand() { return poBand; } 396 397 static int FlushCacheBlock(); 398 static void Verify(); 399 static int IsCached( int nXOff, int nYOff ); 400 }; 401 402 403 /* ******************************************************************** */ 404 /* GDALColorTable */ 405 /* ******************************************************************** */ 406 407 class CPL_DLL GDALColorTable 408 { 409 GDALPaletteInterp eInterp; 410 411 int nEntryCount; 412 GDALColorEntry *paoEntries; 413 414 public: 415 GDALColorTable( GDALPaletteInterp = GPI_RGB ); 416 ~GDALColorTable(); 417 418 GDALColorTable *Clone() const; 419 420 GDALPaletteInterp GetPaletteInterpretation() const; 421 422 int GetColorEntryCount() const; 423 const GDALColorEntry *GetColorEntry( int ) const; 424 int GetColorEntryAsRGB( int, GDALColorEntry * ) const; 425 void SetColorEntry( int, const GDALColorEntry * ); 426 }; 427 428 /* ******************************************************************** */ 429 /* GDALRasterBand */ 430 /* ******************************************************************** */ 431 432 //! A single raster band (or channel). 433 434 class CPL_DLL GDALRasterBand : public GDALMajorObject 435 { 436 protected: 437 GDALDataset *poDS; 438 int nBand; /* 1 based */ 439 440 int nRasterXSize; 441 int nRasterYSize; 442 443 GDALDataType eDataType; 444 GDALAccess eAccess; 445 446 /* stuff related to blocking, and raster cache */ 447 int nBlockXSize; 448 int nBlockYSize; 449 int nBlocksPerRow; 450 int nBlocksPerColumn; 451 452 GDALRasterBlock **papoBlocks; 453 454 int nBlockReads; 455 456 friend class GDALDataset; 457 friend class GDALRasterBlock; 458 459 protected: 460 virtual CPLErr IReadBlock( int, int, void * ) = 0; 461 virtual CPLErr IWriteBlock( int, int, void * ); 462 virtual CPLErr IRasterIO( GDALRWFlag, int, int, int, int, 463 void *, int, int, GDALDataType, 464 int, int ); 465 CPLErr OverviewRasterIO( GDALRWFlag, int, int, int, int, 466 void *, int, int, GDALDataType, 467 int, int ); 468 469 CPLErr AdoptBlock( int, int, GDALRasterBlock * ); 470 void InitBlockInfo(); 471 472 public: 473 GDALRasterBand(); 474 475 virtual ~GDALRasterBand(); 476 477 int GetXSize(); 478 int GetYSize(); 479 int GetBand(); 480 GDALDataset*GetDataset(); 481 482 GDALDataType GetRasterDataType( void ); 483 void GetBlockSize( int *, int * ); 484 GDALAccess GetAccess(); 485 486 CPLErr RasterIO( GDALRWFlag, int, int, int, int, 487 void *, int, int, GDALDataType, 488 int, int ); 489 CPLErr ReadBlock( int, int, void * ); 490 491 CPLErr WriteBlock( int, int, void * ); 492 493 GDALRasterBlock *GetBlockRef( int nXBlockOff, int nYBlockOff, 494 int bJustInitialize = FALSE ); 495 CPLErr FlushBlock( int = -1, int = -1 ); 496 497 // New OpengIS CV_SampleDimension stuff. 498 499 virtual CPLErr FlushCache(); 500 virtual char **GetCategoryNames(); 501 virtual double GetNoDataValue( int *pbSuccess = NULL ); 502 virtual double GetMinimum( int *pbSuccess = NULL ); 503 virtual double GetMaximum(int *pbSuccess = NULL ); 504 virtual double GetOffset( int *pbSuccess = NULL ); 505 virtual double GetScale( int *pbSuccess = NULL ); 506 virtual const char *GetUnitType(); 507 virtual GDALColorInterp GetColorInterpretation(); 508 virtual GDALColorTable *GetColorTable(); 509 virtual CPLErr Fill(double dfRealValue, double dfImaginaryValue = 0); 510 511 virtual CPLErr SetCategoryNames( char ** ); 512 virtual CPLErr SetNoDataValue( double ); 513 virtual CPLErr SetColorTable( GDALColorTable * ); 514 virtual CPLErr SetColorInterpretation( GDALColorInterp ); 515 516 virtual int HasArbitraryOverviews(); 517 virtual int GetOverviewCount(); 518 virtual GDALRasterBand *GetOverview(int); 519 virtual CPLErr BuildOverviews( const char *, int, int *, 520 GDALProgressFunc, void * ); 521 522 CPLErr GetHistogram( double dfMin, double dfMax, 523 int nBuckets, int * panHistogram, 524 int bIncludeOutOfRange, int bApproxOK, 525 GDALProgressFunc, void *pProgressData ); 526 }; 527 528 /* ******************************************************************** */ 529 /* GDALOpenInfo */ 530 /* */ 531 /* Structure of data about dataset for open functions. */ 532 /* ******************************************************************** */ 533 534 class CPL_DLL GDALOpenInfo 535 { 536 public: 537 538 GDALOpenInfo( const char * pszFile, GDALAccess eAccessIn ); 539 ~GDALOpenInfo( void ); 540 541 char *pszFilename; 542 543 GDALAccess eAccess; 544 545 int bStatOK; 546 int bIsDirectory; 547 548 FILE *fp; 549 550 int nHeaderBytes; 551 GByte *pabyHeader; 552 553 }; 554 555 /* ******************************************************************** */ 556 /* GDALDriver */ 557 /* ******************************************************************** */ 558 559 /** 560 * An instance of this class is created for each supported format, and 561 * manages information about the format. 562 * 563 * This roughly corresponds to a file format, though some 564 * drivers may be gateways to many formats through a secondary 565 * multi-library. 566 */ 567 568 class CPL_DLL GDALDriver : public GDALMajorObject 569 { 570 public: 571 GDALDriver(); 572 ~GDALDriver(); 573 574 /* -------------------------------------------------------------------- */ 575 /* Public C++ methods. */ 576 /* -------------------------------------------------------------------- */ 577 GDALDataset *Create( const char * pszName, 578 int nXSize, int nYSize, int nBands, 579 GDALDataType eType, char ** papszOptions ); 580 581 CPLErr Delete( const char * pszName ); 582 583 GDALDataset *CreateCopy( const char *, GDALDataset *, 584 int, char **, 585 GDALProgressFunc pfnProgress, 586 void * pProgressData ); 587 588 /* -------------------------------------------------------------------- */ 589 /* The following are semiprivate, not intended to be accessed */ 590 /* by anyone but the formats instantiating and populating the */ 591 /* drivers. */ 592 /* -------------------------------------------------------------------- */ 593 GDALDataset *(*pfnOpen)( GDALOpenInfo * ); 594 595 GDALDataset *(*pfnCreate)( const char * pszName, 596 int nXSize, int nYSize, int nBands, 597 GDALDataType eType, 598 char ** papszOptions ); 599 600 CPLErr (*pfnDelete)( const char * pszName ); 601 602 GDALDataset *(*pfnCreateCopy)( const char *, GDALDataset *, 603 int, char **, 604 GDALProgressFunc pfnProgress, 605 void * pProgressData ); 606 607 void *pDriverData; 608 609 void (*pfnUnloadDriver)(GDALDriver *); 610 }; 611 612 /* ******************************************************************** */ 613 /* GDALDriverManager */ 614 /* ******************************************************************** */ 615 616 /** 617 * Class for managing the registration of file format drivers. 618 * 619 * Use GetGDALDriverManager() to fetch the global singleton instance of 620 * this class. 621 */ 622 623 class CPL_DLL GDALDriverManager : public GDALMajorObject 624 { 625 int nDrivers; 626 GDALDriver **papoDrivers; 627 628 char *pszHome; 629 630 public: 631 GDALDriverManager(); 632 ~GDALDriverManager(); 633 634 int GetDriverCount( void ); 635 GDALDriver *GetDriver( int ); 636 GDALDriver *GetDriverByName( const char * ); 637 638 int RegisterDriver( GDALDriver * ); 639 void MoveDriver( GDALDriver *, int ); 640 void DeregisterDriver( GDALDriver * ); 641 642 void AutoLoadDrivers(); 643 void AutoSkipDrivers(); 644 645 const char *GetHome(); 646 void SetHome( const char * ); 647 }; 648 649 CPL_C_START 650 GDALDriverManager CPL_DLL * GetGDALDriverManager( void ); 651 CPL_C_END 652 653 /* ==================================================================== */ 654 /* An assortment of overview related stuff. */ 655 /* ==================================================================== */ 656 657 CPL_C_START 658 659 CPLErr 660 GTIFFBuildOverviews( const char * pszFilename, 661 int nBands, GDALRasterBand **papoBandList, 662 int nOverviews, int * panOverviewList, 663 const char * pszResampling, 664 GDALProgressFunc pfnProgress, void * pProgressData ); 665 666 CPLErr 667 GDALDefaultBuildOverviews( GDALDataset *hSrcDS, const char * pszBasename, 668 const char * pszResampling, 669 int nOverviews, int * panOverviewList, 670 int nBands, int * panBandList, 671 GDALProgressFunc pfnProgress, void * pProgressData); 672 673 674 CPLErr 675 GDALRegenerateOverviews( GDALRasterBand *, int, GDALRasterBand **, 676 const char *, GDALProgressFunc, void * ); 677 678 CPL_C_END 679 680 #endif /* ndef GDAL_PRIV_H_INCLUDED */ 681