GDAL
gdal_proxy.h
1 /******************************************************************************
2  * $Id: gdal_proxy.h b55a33407a80673ec314b165c82f47dd02e9dc9c 2020-04-27 20:37:55 +0200 Even Rouault $
3  *
4  * Project: GDAL Core
5  * Purpose: GDAL Core C++/Private declarations
6  * Author: Even Rouault <even dot rouault at spatialys.com>
7  *
8  ******************************************************************************
9  * Copyright (c) 2008-2014, Even Rouault <even dot rouault at spatialys.com>
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 #ifndef GDAL_PROXY_H_INCLUDED
31 #define GDAL_PROXY_H_INCLUDED
32 
33 #ifndef DOXYGEN_SKIP
34 
35 #include "gdal.h"
36 
37 #ifdef __cplusplus
38 
39 #include "gdal_priv.h"
40 #include "cpl_hash_set.h"
41 
42 /* ******************************************************************** */
43 /* GDALProxyDataset */
44 /* ******************************************************************** */
45 
46 class CPL_DLL GDALProxyDataset : public GDALDataset
47 {
48  protected:
49  GDALProxyDataset() {}
50 
51  virtual GDALDataset *RefUnderlyingDataset() const = 0;
52  virtual void UnrefUnderlyingDataset(GDALDataset* poUnderlyingDataset) const;
53 
54  CPLErr IBuildOverviews( const char *, int, int *,
55  int, int *, GDALProgressFunc, void * ) override;
56  CPLErr IRasterIO( GDALRWFlag, int, int, int, int,
57  void *, int, int, GDALDataType,
58  int, int *, GSpacing, GSpacing, GSpacing,
59  GDALRasterIOExtraArg* psExtraArg ) override;
60 
61  public:
62  char **GetMetadataDomainList() override;
63  char **GetMetadata( const char * pszDomain ) override;
64  CPLErr SetMetadata( char ** papszMetadata,
65  const char * pszDomain ) override;
66  const char *GetMetadataItem( const char * pszName,
67  const char * pszDomain ) override;
68  CPLErr SetMetadataItem( const char * pszName,
69  const char * pszValue,
70  const char * pszDomain ) override;
71 
72  void FlushCache() override;
73 
74  const OGRSpatialReference* GetSpatialRef() const override;
75  CPLErr SetSpatialRef(const OGRSpatialReference* poSRS) override;
76 
77  CPLErr GetGeoTransform( double * ) override;
78  CPLErr SetGeoTransform( double * ) override;
79 
80  void *GetInternalHandle( const char * ) override;
81  GDALDriver *GetDriver() override;
82  char **GetFileList() override;
83 
84  int GetGCPCount() override;
85  const OGRSpatialReference* GetGCPSpatialRef() const override;
86  const GDAL_GCP *GetGCPs() override;
87  CPLErr SetGCPs( int nGCPCount, const GDAL_GCP *pasGCPList,
88  const OGRSpatialReference * poGCP_SRS ) override;
89 
90  CPLErr AdviseRead( int nXOff, int nYOff, int nXSize, int nYSize,
91  int nBufXSize, int nBufYSize,
92  GDALDataType eDT,
93  int nBandCount, int *panBandList,
94  char **papszOptions ) override;
95 
96  CPLErr CreateMaskBand( int nFlags ) override;
97 
98  protected:
99  const char *_GetProjectionRef(void) override;
100  CPLErr _SetProjection( const char * ) override;
101  const char *_GetGCPProjection() override;
102  CPLErr _SetGCPs( int nGCPCount, const GDAL_GCP *pasGCPList,
103  const char *pszGCPProjection ) override;
104 
105  private:
106  CPL_DISALLOW_COPY_ASSIGN(GDALProxyDataset)
107 };
108 
109 /* ******************************************************************** */
110 /* GDALProxyRasterBand */
111 /* ******************************************************************** */
112 
113 class CPL_DLL GDALProxyRasterBand : public GDALRasterBand
114 {
115  protected:
116  GDALProxyRasterBand() {}
117 
118  virtual GDALRasterBand* RefUnderlyingRasterBand() = 0;
119  virtual void UnrefUnderlyingRasterBand(GDALRasterBand* poUnderlyingRasterBand);
120 
121  CPLErr IReadBlock( int, int, void * ) override;
122  CPLErr IWriteBlock( int, int, void * ) override;
123  CPLErr IRasterIO( GDALRWFlag, int, int, int, int,
124  void *, int, int, GDALDataType,
125  GSpacing, GSpacing, GDALRasterIOExtraArg* psExtraArg ) override;
126 
127  public:
128  char **GetMetadataDomainList() override;
129  char **GetMetadata( const char * pszDomain ) override;
130  CPLErr SetMetadata( char ** papszMetadata,
131  const char * pszDomain ) override;
132  const char *GetMetadataItem( const char * pszName,
133  const char * pszDomain ) override;
134  CPLErr SetMetadataItem( const char * pszName,
135  const char * pszValue,
136  const char * pszDomain ) override;
137  CPLErr FlushCache() override;
138  char **GetCategoryNames() override;
139  double GetNoDataValue( int *pbSuccess = nullptr ) override;
140  double GetMinimum( int *pbSuccess = nullptr ) override;
141  double GetMaximum(int *pbSuccess = nullptr ) override;
142  double GetOffset( int *pbSuccess = nullptr ) override;
143  double GetScale( int *pbSuccess = nullptr ) override;
144  const char *GetUnitType() override;
145  GDALColorInterp GetColorInterpretation() override;
146  GDALColorTable *GetColorTable() override;
147  CPLErr Fill(double dfRealValue, double dfImaginaryValue = 0) override;
148 
149  CPLErr SetCategoryNames( char ** ) override;
150  CPLErr SetNoDataValue( double ) override;
151  CPLErr DeleteNoDataValue() override;
152  CPLErr SetColorTable( GDALColorTable * ) override;
153  CPLErr SetColorInterpretation( GDALColorInterp ) override;
154  CPLErr SetOffset( double ) override;
155  CPLErr SetScale( double ) override;
156  CPLErr SetUnitType( const char * ) override;
157 
158  CPLErr GetStatistics( int bApproxOK, int bForce,
159  double *pdfMin, double *pdfMax,
160  double *pdfMean, double *padfStdDev ) override;
161  CPLErr ComputeStatistics( int bApproxOK,
162  double *pdfMin, double *pdfMax,
163  double *pdfMean, double *pdfStdDev,
164  GDALProgressFunc, void *pProgressData ) override;
165  CPLErr SetStatistics( double dfMin, double dfMax,
166  double dfMean, double dfStdDev ) override;
167  CPLErr ComputeRasterMinMax( int, double* ) override;
168 
169  int HasArbitraryOverviews() override;
170  int GetOverviewCount() override;
171  GDALRasterBand *GetOverview( int ) override;
172  GDALRasterBand *GetRasterSampleOverview( GUIntBig ) override;
173  CPLErr BuildOverviews( const char *, int, int *,
174  GDALProgressFunc, void * ) override;
175 
176  CPLErr AdviseRead( int nXOff, int nYOff, int nXSize, int nYSize,
177  int nBufXSize, int nBufYSize,
178  GDALDataType eDT, char **papszOptions ) override;
179 
180  CPLErr GetHistogram( double dfMin, double dfMax,
181  int nBuckets, GUIntBig * panHistogram,
182  int bIncludeOutOfRange, int bApproxOK,
183  GDALProgressFunc, void *pProgressData ) override;
184 
185  CPLErr GetDefaultHistogram( double *pdfMin, double *pdfMax,
186  int *pnBuckets, GUIntBig ** ppanHistogram,
187  int bForce,
188  GDALProgressFunc, void *pProgressData) override;
189  CPLErr SetDefaultHistogram( double dfMin, double dfMax,
190  int nBuckets, GUIntBig *panHistogram ) override;
191 
192  GDALRasterAttributeTable *GetDefaultRAT() override;
193  CPLErr SetDefaultRAT( const GDALRasterAttributeTable * ) override;
194 
195  GDALRasterBand *GetMaskBand() override;
196  int GetMaskFlags() override;
197  CPLErr CreateMaskBand( int nFlags ) override;
198 
199  CPLVirtualMem *GetVirtualMemAuto( GDALRWFlag eRWFlag,
200  int *pnPixelSpace,
201  GIntBig *pnLineSpace,
202  char **papszOptions ) override;
203 
204  private:
205  CPL_DISALLOW_COPY_ASSIGN(GDALProxyRasterBand)
206 };
207 
208 /* ******************************************************************** */
209 /* GDALProxyPoolDataset */
210 /* ******************************************************************** */
211 
212 typedef struct _GDALProxyPoolCacheEntry GDALProxyPoolCacheEntry;
213 class GDALProxyPoolRasterBand;
214 
215 class CPL_DLL GDALProxyPoolDataset : public GDALProxyDataset
216 {
217  private:
218  GIntBig responsiblePID = -1;
219 
220  mutable char *pszProjectionRef = nullptr;
221  mutable OGRSpatialReference* m_poSRS = nullptr;
222  mutable OGRSpatialReference* m_poGCPSRS = nullptr;
223  double adfGeoTransform[6]{0,1,0,0,0,1};
224  bool bHasSrcProjection = false;
225  bool m_bHasSrcSRS = false;
226  bool bHasSrcGeoTransform = false;
227  char *pszGCPProjection = nullptr;
228  int nGCPCount = 0;
229  GDAL_GCP *pasGCPList = nullptr;
230  CPLHashSet *metadataSet = nullptr;
231  CPLHashSet *metadataItemSet = nullptr;
232 
233  mutable GDALProxyPoolCacheEntry* cacheEntry = nullptr;
234  char *m_pszOwner = nullptr;
235 
236  GDALDataset *RefUnderlyingDataset(bool bForceOpen) const;
237 
238  protected:
239  GDALDataset *RefUnderlyingDataset() const override;
240  void UnrefUnderlyingDataset(GDALDataset* poUnderlyingDataset) const override;
241 
242  friend class GDALProxyPoolRasterBand;
243 
244  public:
245  GDALProxyPoolDataset( const char* pszSourceDatasetDescription,
246  int nRasterXSize, int nRasterYSize,
247  GDALAccess eAccess = GA_ReadOnly,
248  int bShared = FALSE,
249  const char * pszProjectionRef = nullptr,
250  double * padfGeoTransform = nullptr,
251  const char* pszOwner = nullptr );
252  ~GDALProxyPoolDataset() override;
253 
254  void SetOpenOptions( char** papszOpenOptions );
255 
256  // If size (nBlockXSize&nBlockYSize) parameters is zero
257  // they will be loaded when RefUnderlyingRasterBand function is called.
258  // But in this case we cannot use them in other non-virtual methods before
259  // RefUnderlyingRasterBand fist call.
260  void AddSrcBandDescription( GDALDataType eDataType, int nBlockXSize,
261  int nBlockYSize );
262 
263  // Used by VRT SimpleSource to add a single GDALProxyPoolRasterBand while
264  // keeping all other bands initialized to a nullptr. This is under the assumption,
265  // VRT SimpleSource will not have to access any other bands than the one added.
266  void AddSrcBand(int nBand, GDALDataType eDataType, int nBlockXSize,
267  int nBlockYSize );
268  void FlushCache() override;
269 
270  const OGRSpatialReference* GetSpatialRef() const override;
271  CPLErr SetSpatialRef(const OGRSpatialReference* poSRS) override;
272 
273  const char *_GetProjectionRef() override;
274  CPLErr _SetProjection( const char * ) override;
275 
276  CPLErr GetGeoTransform( double * ) override;
277  CPLErr SetGeoTransform( double * ) override;
278 
279  // Special behavior for the following methods : they return a pointer
280  // data type, that must be cached by the proxy, so it doesn't become invalid
281  // when the underlying object get closed.
282  char **GetMetadata( const char * pszDomain ) override;
283  const char *GetMetadataItem( const char * pszName,
284  const char * pszDomain ) override;
285 
286  void *GetInternalHandle( const char * pszRequest ) override;
287 
288  const char *_GetGCPProjection() override;
289  const OGRSpatialReference* GetGCPSpatialRef() const override;
290  const GDAL_GCP *GetGCPs() override;
291 
292  private:
293  CPL_DISALLOW_COPY_ASSIGN(GDALProxyPoolDataset)
294 };
295 
296 /* ******************************************************************** */
297 /* GDALProxyPoolRasterBand */
298 /* ******************************************************************** */
299 
300 class GDALProxyPoolOverviewRasterBand;
301 class GDALProxyPoolMaskBand;
302 
303 class CPL_DLL GDALProxyPoolRasterBand : public GDALProxyRasterBand
304 {
305  private:
306  CPLHashSet *metadataSet = nullptr;
307  CPLHashSet *metadataItemSet = nullptr;
308  char *pszUnitType = nullptr;
309  char **papszCategoryNames = nullptr;
310  GDALColorTable *poColorTable = nullptr;
311 
312  int nSizeProxyOverviewRasterBand = 0;
313  GDALProxyPoolOverviewRasterBand **papoProxyOverviewRasterBand = nullptr;
314  GDALProxyPoolMaskBand *poProxyMaskBand = nullptr;
315 
316  GDALRasterBand* RefUnderlyingRasterBand( bool bForceOpen );
317 
318  protected:
319  GDALRasterBand* RefUnderlyingRasterBand() override;
320  void UnrefUnderlyingRasterBand( GDALRasterBand* poUnderlyingRasterBand )
321  override;
322 
323  friend class GDALProxyPoolOverviewRasterBand;
324  friend class GDALProxyPoolMaskBand;
325 
326  public:
327  GDALProxyPoolRasterBand( GDALProxyPoolDataset* poDS, int nBand,
328  GDALDataType eDataType,
329  int nBlockXSize, int nBlockYSize );
330  GDALProxyPoolRasterBand( GDALProxyPoolDataset* poDS,
331  GDALRasterBand* poUnderlyingRasterBand );
332  ~GDALProxyPoolRasterBand() override;
333 
334  void AddSrcMaskBandDescription( GDALDataType eDataType, int nBlockXSize,
335  int nBlockYSize );
336 
337  // Special behavior for the following methods : they return a pointer
338  // data type, that must be cached by the proxy, so it doesn't become invalid
339  // when the underlying object get closed.
340  char **GetMetadata( const char * pszDomain ) override;
341  const char *GetMetadataItem( const char * pszName,
342  const char * pszDomain ) override;
343  char **GetCategoryNames() override;
344  const char *GetUnitType() override;
345  GDALColorTable *GetColorTable() override;
346  GDALRasterBand *GetOverview( int ) override;
347  GDALRasterBand *GetRasterSampleOverview( GUIntBig nDesiredSamples ) override; // TODO
348  GDALRasterBand *GetMaskBand() override;
349 
350  CPLErr FlushCache() override;
351 
352  private:
353  CPL_DISALLOW_COPY_ASSIGN(GDALProxyPoolRasterBand)
354 };
355 
356 /* ******************************************************************** */
357 /* GDALProxyPoolOverviewRasterBand */
358 /* ******************************************************************** */
359 
360 class GDALProxyPoolOverviewRasterBand : public GDALProxyPoolRasterBand
361 {
362  private:
363  GDALProxyPoolRasterBand *poMainBand = nullptr;
364  int nOverviewBand = 0;
365 
366  GDALRasterBand *poUnderlyingMainRasterBand = nullptr;
367  int nRefCountUnderlyingMainRasterBand = 0;
368 
369  CPL_DISALLOW_COPY_ASSIGN(GDALProxyPoolOverviewRasterBand)
370 
371  protected:
372  GDALRasterBand* RefUnderlyingRasterBand() override;
373  void UnrefUnderlyingRasterBand( GDALRasterBand* poUnderlyingRasterBand )
374  override;
375 
376  public:
377  GDALProxyPoolOverviewRasterBand( GDALProxyPoolDataset* poDS,
378  GDALRasterBand* poUnderlyingOverviewBand,
379  GDALProxyPoolRasterBand* poMainBand,
380  int nOverviewBand );
381  ~GDALProxyPoolOverviewRasterBand() override;
382 };
383 
384 /* ******************************************************************** */
385 /* GDALProxyPoolMaskBand */
386 /* ******************************************************************** */
387 
388 class GDALProxyPoolMaskBand : public GDALProxyPoolRasterBand
389 {
390  private:
391  GDALProxyPoolRasterBand *poMainBand = nullptr;
392 
393  GDALRasterBand *poUnderlyingMainRasterBand = nullptr;
394  int nRefCountUnderlyingMainRasterBand = 0;
395 
396  CPL_DISALLOW_COPY_ASSIGN(GDALProxyPoolMaskBand)
397 
398  protected:
399  GDALRasterBand* RefUnderlyingRasterBand() override;
400  void UnrefUnderlyingRasterBand( GDALRasterBand* poUnderlyingRasterBand )
401  override;
402 
403  public:
404  GDALProxyPoolMaskBand( GDALProxyPoolDataset* poDS,
405  GDALRasterBand* poUnderlyingMaskBand,
406  GDALProxyPoolRasterBand* poMainBand );
407  GDALProxyPoolMaskBand( GDALProxyPoolDataset* poDS,
408  GDALProxyPoolRasterBand* poMainBand,
409  GDALDataType eDataType,
410  int nBlockXSize, int nBlockYSize );
411  ~GDALProxyPoolMaskBand() override;
412 };
413 
414 #endif
415 
416 /* ******************************************************************** */
417 /* C types and methods declarations */
418 /* ******************************************************************** */
419 
421 
422 typedef struct GDALProxyPoolDatasetHS *GDALProxyPoolDatasetH;
423 
424 GDALProxyPoolDatasetH CPL_DLL GDALProxyPoolDatasetCreate(const char* pszSourceDatasetDescription,
425  int nRasterXSize, int nRasterYSize,
426  GDALAccess eAccess, int bShared,
427  const char * pszProjectionRef,
428  double * padfGeoTransform);
429 
430 void CPL_DLL GDALProxyPoolDatasetDelete(GDALProxyPoolDatasetH hProxyPoolDataset);
431 
432 void CPL_DLL GDALProxyPoolDatasetAddSrcBandDescription( GDALProxyPoolDatasetH hProxyPoolDataset,
433  GDALDataType eDataType,
434  int nBlockXSize, int nBlockYSize);
435 
436 CPL_C_END
437 
438 #endif /* #ifndef DOXYGEN_SKIP */
439 
440 #endif /* GDAL_PROXY_H_INCLUDED */
A color table / palette.
Definition: gdal_priv.h:1021
A set of associated raster bands, usually from one file.
Definition: gdal_priv.h:340
virtual CPLErr AdviseRead(int nXOff, int nYOff, int nXSize, int nYSize, int nBufXSize, int nBufYSize, GDALDataType eDT, int nBandCount, int *panBandList, char **papszOptions)
Advise driver of upcoming read requests.
Definition: gdaldataset.cpp:2789
char ** GetMetadataDomainList() override
Fetch list of metadata domains.
Definition: gdaldataset.cpp:4248
virtual void * GetInternalHandle(const char *pszHandleName)
Fetch a format specific internally meaningful handle.
Definition: gdaldataset.cpp:1263
CPLErr BuildOverviews(const char *, int, int *, int, int *, GDALProgressFunc, void *)
Build raster overview(s)
Definition: gdaldataset.cpp:1936
virtual CPLErr CreateMaskBand(int nFlagsIn)
Adds a mask band to the dataset.
Definition: gdaldataset.cpp:3071
virtual int GetGCPCount()
Get number of GCPs.
Definition: gdaldataset.cpp:1505
virtual CPLErr GetGeoTransform(double *padfTransform)
Fetch the affine transformation coefficients.
Definition: gdaldataset.cpp:1163
virtual const OGRSpatialReference * GetGCPSpatialRef() const
Get output spatial reference system for GCPs.
Definition: gdaldataset.cpp:1602
CPLErr SetMetadata(char **papszMetadata, const char *pszDomain) override
Set metadata.
virtual CPLErr SetSpatialRef(const OGRSpatialReference *poSRS)
Set the spatial reference system for this dataset.
Definition: gdaldataset.cpp:1045
virtual GDALDriver * GetDriver(void)
Fetch the driver to which this dataset relates.
Definition: gdaldataset.cpp:1301
virtual CPLErr SetGeoTransform(double *padfTransform)
Set the affine transformation coefficients.
Definition: gdaldataset.cpp:1218
virtual CPLErr SetGCPs(int nGCPCount, const GDAL_GCP *pasGCPList, const OGRSpatialReference *poGCP_SRS)
Assign GCPs.
Definition: gdaldataset.cpp:1790
virtual const OGRSpatialReference * GetSpatialRef() const
Fetch the spatial reference for this dataset.
Definition: gdaldataset.cpp:914
CPLErr SetMetadataItem(const char *pszName, const char *pszValue, const char *pszDomain) override
Set single metadata item.
virtual void FlushCache(void)
Flush all write cached data to disk.
Definition: gdaldataset.cpp:421
void static void char ** GetMetadata(const char *pszDomain="") override
Fetch metadata.
Definition: gdaldataset.cpp:4147
virtual const GDAL_GCP * GetGCPs()
Fetch GCPs.
Definition: gdaldataset.cpp:1685
virtual char ** GetFileList(void)
Fetch files forming dataset.
Definition: gdaldataset.cpp:2950
Format specific driver.
Definition: gdal_priv.h:1483
virtual const char * GetMetadataItem(const char *pszName, const char *pszDomain="")
Fetch single metadata item.
Definition: gdalmajorobject.cpp:344
The GDALRasterAttributeTable (or RAT) class is used to encapsulate a table used to provide attribute ...
Definition: gdal_rat.h:48
A single raster band (or channel).
Definition: gdal_priv.h:1127
This class represents an OpenGIS Spatial Reference System, and contains methods for converting betwee...
Definition: ogr_spatialref.h:158
CPLErr
Error category.
Definition: cpl_error.h:53
Hash set implementation.
struct _CPLHashSet CPLHashSet
Opaque type for a hash set.
Definition: cpl_hash_set.h:52
unsigned long long GUIntBig
Large unsigned integer type (generally 64-bit unsigned integer type).
Definition: cpl_port.h:251
#define CPL_C_END
Macro to end a block of C symbols.
Definition: cpl_port.h:339
#define CPL_C_START
Macro to start a block of C symbols.
Definition: cpl_port.h:337
#define CPL_DISALLOW_COPY_ASSIGN(ClassName)
Helper to remove the copy and assignment constructors so that the compiler will not generate the defa...
Definition: cpl_port.h:1007
long long GIntBig
Large signed integer type (generally 64-bit integer type).
Definition: cpl_port.h:248
struct CPLVirtualMem CPLVirtualMem
Opaque type that represents a virtual memory mapping.
Definition: cpl_virtualmem.h:62
Public (C callable) GDAL entry points.
GIntBig GSpacing
Type to express pixel, line or band spacing.
Definition: gdal.h:286
GDALAccess
Definition: gdal.h:115
@ GA_ReadOnly
Definition: gdal.h:116
GDALDataType
Definition: gdal.h:62
GDALColorInterp
Definition: gdal.h:204
GDALRWFlag
Definition: gdal.h:121
C++ GDAL entry points.
Structure to pass extra arguments to RasterIO() method.
Definition: gdal.h:161
Ground Control Point.
Definition: gdal.h:679