GDAL

gdal_cpp_functions.h
1/******************************************************************************
2 *
3 * Name: gdal_cpp_functions.h
4 * Project: GDAL Core
5 * Purpose: Declaration of various semi-primate C++ functions
6 * Author: Frank Warmerdam, warmerdam@pobox.com
7 *
8 ******************************************************************************
9 * Copyright (c) 1998, Frank Warmerdam
10 * Copyright (c) 2007-2014, Even Rouault <even dot rouault at spatialys.com>
11 *
12 * SPDX-License-Identifier: MIT
13 ****************************************************************************/
14
15#ifndef GDAL_CPP_FUNCTIONS_H_INCLUDED
16#define GDAL_CPP_FUNCTIONS_H_INCLUDED
17
18#include "cpl_port.h"
19#include "cpl_error.h"
20#include "cpl_progress.h"
21#include "cpl_string.h"
22
23#include "gdal.h"
24#include "gdal_gcp.h"
25#include "gdal_geotransform.h"
26
27#include <cstddef>
28#include <limits>
29#include <memory>
30#include <utility>
31#include <vector>
32
33 typedef struct _CPLMutex CPLMutex;
34
35 class GDALColorTable;
36 class GDALDataset;
37 class GDALDriver;
38 class GDALMDArray;
39 class GDALRasterAttributeTable;
40 class GDALRasterBand;
41 class OGRSpatialReference;
42
43/* ==================================================================== */
44/* An assortment of overview related stuff. */
45/* ==================================================================== */
46
48/* Only exported for drivers as plugin. Signature may change */
49 CPLErr CPL_DLL GDALRegenerateOverviewsMultiBand(
50 int nBands, GDALRasterBand *const *papoSrcBands, int nOverviews,
51 GDALRasterBand *const *const *papapoOverviewBands,
52 const char *pszResampling, GDALProgressFunc pfnProgress,
53 void *pProgressData, CSLConstList papszOptions);
54
55 CPLErr CPL_DLL GDALRegenerateOverviewsMultiBand(
56 const std::vector<GDALRasterBand *> &apoSrcBands,
57 // First level of array is indexed by band (thus aapoOverviewBands.size() must be equal to apoSrcBands.size())
58 // Second level is indexed by overview
59 const std::vector<std::vector<GDALRasterBand *>> &aapoOverviewBands,
60 const char *pszResampling, GDALProgressFunc pfnProgress,
61 void *pProgressData, CSLConstList papszOptions);
62
63/************************************************************************/
64/* GDALOverviewResampleArgs */
65/************************************************************************/
66
68// Should not contain any dataset/rasterband object, as this might be
69// read in a worker thread.
70 struct GDALOverviewResampleArgs
71{
73 GDALDataType eSrcDataType = GDT_Unknown;
75 GDALDataType eOvrDataType = GDT_Unknown;
77 int nOvrXSize = 0;
79 int nOvrYSize = 0;
81 int nOvrNBITS = 0;
83 // (source width divided by destination width)
84 double dfXRatioDstToSrc = 0;
86 // (source height divided by destination height)
87 double dfYRatioDstToSrc = 0;
89 double dfSrcXDelta = 0;
91 double dfSrcYDelta = 0;
93 GDALDataType eWrkDataType = GDT_Unknown;
95 const GByte *pabyChunkNodataMask = nullptr;
97 int nChunkXOff = 0;
99 int nChunkXSize = 0;
101 int nChunkYOff = 0;
103 int nChunkYSize = 0;
105 int nDstXOff = 0;
107 int nDstXOff2 = 0;
109 int nDstYOff = 0;
111 int nDstYOff2 = 0;
113 const char *pszResampling = nullptr;
115 bool bHasNoData = false;
117 double dfNoDataValue = 0;
119 const GDALColorTable *poColorTable = nullptr;
121 // in the target pixel to be at nodata too (only taken into account by
122 // average resampling)
123 bool bPropagateNoData = false;
124};
125
126 typedef CPLErr (*GDALResampleFunction)(const GDALOverviewResampleArgs &args,
127 const void *pChunk, void **ppDstBuffer,
128 GDALDataType *peDstBufferDataType);
129
130GDALResampleFunction GDALGetResampleFunction(const char *pszResampling,
131 int *pnRadius);
132
133std::string CPL_DLL GDALGetNormalizedOvrResampling(const char *pszResampling);
134
135 GDALDataType GDALGetOvrWorkDataType(const char *pszResampling,
136 GDALDataType eSrcDataType);
137
138 CPL_C_START
139
140 CPLErr CPL_DLL
141HFAAuxBuildOverviews(const char *pszOvrFilename, GDALDataset *poParentDS,
142 GDALDataset **ppoDS, int nBands, const int *panBandList,
143 int nNewOverviews, const int *panNewOverviewList,
144 const char *pszResampling, GDALProgressFunc pfnProgress,
145 void *pProgressData, CSLConstList papszOptions);
146
147 CPLErr CPL_DLL GTIFFBuildOverviews(const char *pszFilename, int nBands,
148 GDALRasterBand *const *papoBandList,
149 int nOverviews, const int *panOverviewList,
150 const char *pszResampling,
151 GDALProgressFunc pfnProgress,
152 void *pProgressData,
153 CSLConstList papszOptions);
154
155 CPLErr CPL_DLL GTIFFBuildOverviewsEx(const char *pszFilename, int nBands,
156 GDALRasterBand *const *papoBandList,
157 int nOverviews, const int *panOverviewList,
158 const std::pair<int, int> *pasOverviewSize,
159 const char *pszResampling,
160 const char *const *papszOptions,
161 GDALProgressFunc pfnProgress,
162 void *pProgressData);
163
164 int CPL_DLL GDALBandGetBestOverviewLevel(GDALRasterBand *poBand, int &nXOff,
165 int &nYOff, int &nXSize, int &nYSize,
166 int nBufXSize, int nBufYSize)
167 CPL_WARN_DEPRECATED("Use GDALBandGetBestOverviewLevel2 instead");
168 int CPL_DLL GDALBandGetBestOverviewLevel2(GDALRasterBand *poBand, int &nXOff,
169 int &nYOff, int &nXSize, int &nYSize,
170 int nBufXSize, int nBufYSize,
171 GDALRasterIOExtraArg *psExtraArg);
172
173 int CPL_DLL GDALOvLevelAdjust(int nOvLevel, int nXSize)
174 CPL_WARN_DEPRECATED("Use GDALOvLevelAdjust2 instead");
175 int CPL_DLL GDALOvLevelAdjust2(int nOvLevel, int nXSize, int nYSize);
176 int CPL_DLL GDALComputeOvFactor(int nOvrXSize, int nRasterXSize, int nOvrYSize,
177 int nRasterYSize);
178
179 GDALDataset CPL_DLL *GDALFindAssociatedAuxFile(const char *pszBasefile,
180 GDALAccess eAccess,
181 GDALDataset *poDependentDS);
182
183/* ==================================================================== */
184/* Infrastructure to check that dataset characteristics are valid */
185/* ==================================================================== */
186
187 int CPL_DLL GDALCheckDatasetDimensions(int nXSize, int nYSize);
188 int CPL_DLL GDALCheckBandCount(int nBands, int bIsZeroAllowed);
189
190/* Internal use only */
191
192/* CPL_DLL exported, but only for in-tree drivers that can be built as plugins
193 */
194 int CPL_DLL GDALReadWorldFile2(const char *pszBaseFilename,
195 const char *pszExtension,
196 double *padfGeoTransform,
197 CSLConstList papszSiblingFiles,
198 char **ppszWorldFileNameOut);
199 int CPL_DLL GDALReadTabFile2(const char *pszBaseFilename,
200 double *padfGeoTransform, char **ppszWKT,
201 int *pnGCPCount, GDAL_GCP **ppasGCPs,
202 CSLConstList papszSiblingFiles,
203 char **ppszTabFileNameOut);
204
205 void CPL_DLL GDALCopyRasterIOExtraArg(GDALRasterIOExtraArg *psDestArg,
206 GDALRasterIOExtraArg *psSrcArg);
207
208 void CPL_DLL GDALExpandPackedBitsToByteAt0Or1(
209 const GByte *CPL_RESTRICT pabyInput, GByte *CPL_RESTRICT pabyOutput,
210 size_t nInputBits);
211
212 void CPL_DLL GDALExpandPackedBitsToByteAt0Or255(
213 const GByte *CPL_RESTRICT pabyInput, GByte *CPL_RESTRICT pabyOutput,
214 size_t nInputBits);
215
216 CPL_C_END
217
218 int CPL_DLL GDALReadWorldFile2(const char *pszBaseFilename,
219 const char *pszExtension, GDALGeoTransform &gt,
220 CSLConstList papszSiblingFiles,
221 char **ppszWorldFileNameOut);
222
223std::unique_ptr<GDALDataset> CPL_DLL
224 GDALGetThreadSafeDataset(std::unique_ptr<GDALDataset> poDS, int nScopeFlags);
225
226 GDALDataset CPL_DLL *GDALGetThreadSafeDataset(GDALDataset *poDS,
227 int nScopeFlags);
228
229 void GDALNullifyOpenDatasetsList();
230CPLMutex **GDALGetphDMMutex();
231CPLMutex **GDALGetphDLMutex();
232 void GDALNullifyProxyPoolSingleton();
233 void GDALSetResponsiblePIDForCurrentThread(GIntBig responsiblePID);
234 GIntBig GDALGetResponsiblePIDForCurrentThread();
235
236 CPLString GDALFindAssociatedFile(const char *pszBasename, const char *pszExt,
237 CSLConstList papszSiblingFiles, int nFlags);
238
239 CPLErr CPL_DLL EXIFExtractMetadata(char **&papszMetadata, void *fpL,
240 int nOffset, int bSwabflag, int nTIFFHEADER,
241 int &nExifOffset, int &nInterOffset,
242 int &nGPSOffset);
243
244 int GDALValidateOpenOptions(GDALDriverH hDriver,
245 const char *const *papszOptionOptions);
246 int GDALValidateOptions(const char *pszOptionList,
247 const char *const *papszOptionsToValidate,
248 const char *pszErrorMessageOptionType,
249 const char *pszErrorMessageContainerName);
250
251 GDALRIOResampleAlg CPL_DLL
252GDALRasterIOGetResampleAlg(const char *pszResampling);
253 const char *GDALRasterIOGetResampleAlg(GDALRIOResampleAlg eResampleAlg);
254
255 void GDALRasterIOExtraArgSetResampleAlg(GDALRasterIOExtraArg *psExtraArg,
256 int nXSize, int nYSize, int nBufXSize,
257 int nBufYSize);
258
259 GDALDataset *GDALCreateOverviewDataset(GDALDataset *poDS, int nOvrLevel,
260 bool bThisLevelOnly);
261
262// Should cover particular cases of #3573, #4183, #4506, #6578
263// Behavior is undefined if fVal1 or fVal2 are NaN (should be tested before
264// calling this function)
265
266// TODO: The expression `abs(fVal1 + fVal2)` looks strange; is this a bug?
267// Should this be `abs(fVal1) + abs(fVal2)` instead?
268
269 inline bool ARE_REAL_EQUAL(float fVal1, float fVal2, int ulp = 2)
270{
271 using std::abs;
272 return fVal1 == fVal2 || /* Should cover infinity */
273 abs(fVal1 - fVal2) <
274 std::numeric_limits<float>::epsilon() * abs(fVal1 + fVal2) * ulp;
275}
276
277// We are using `std::numeric_limits<float>::epsilon()` for backward
278// compatibility
279 inline bool ARE_REAL_EQUAL(double dfVal1, double dfVal2, int ulp = 2)
280{
281 using std::abs;
282 return dfVal1 == dfVal2 || /* Should cover infinity */
283 abs(dfVal1 - dfVal2) <
284 static_cast<double>(std::numeric_limits<float>::epsilon()) *
285 abs(dfVal1 + dfVal2) * ulp;
286}
287
288 double GDALAdjustNoDataCloseToFloatMax(double dfVal);
289
290#define DIV_ROUND_UP(a, b) (((a) % (b)) == 0 ? ((a) / (b)) : (((a) / (b)) + 1))
291
292// Number of data samples that will be used to compute approximate statistics
293// (minimum value, maximum value, etc.)
294#define GDALSTAT_APPROX_NUMSAMPLES 2500
295
296 void GDALSerializeGCPListToXML(CPLXMLNode *psParentNode,
297 const std::vector<gdal::GCP> &asGCPs,
298 const OGRSpatialReference *poGCP_SRS);
299 void GDALDeserializeGCPListFromXML(const CPLXMLNode *psGCPList,
300 std::vector<gdal::GCP> &asGCPs,
301 OGRSpatialReference **ppoGCP_SRS);
302
303 void GDALSerializeOpenOptionsToXML(CPLXMLNode *psParentNode,
304 CSLConstList papszOpenOptions);
305 char CPL_DLL **
306GDALDeserializeOpenOptionsFromXML(const CPLXMLNode *psParentNode);
307
308 int GDALCanFileAcceptSidecarFile(const char *pszFilename);
309
310 bool GDALCanReliablyUseSiblingFileList(const char *pszFilename);
311
312 typedef enum
313{
314 GSF_UNSIGNED_INT,
315 GSF_SIGNED_INT,
316 GSF_FLOATING_POINT,
317} GDALBufferSampleFormat;
318
319 bool CPL_DLL GDALBufferHasOnlyNoData(const void *pBuffer, double dfNoDataValue,
320 size_t nWidth, size_t nHeight,
321 size_t nLineStride, size_t nComponents,
322 int nBitsPerSample,
323 GDALBufferSampleFormat nSampleFormat);
324
325 bool CPL_DLL GDALCopyNoDataValue(GDALRasterBand *poDstBand,
326 GDALRasterBand *poSrcBand,
327 bool *pbCannotBeExactlyRepresented = nullptr);
328
329 double CPL_DLL GDALGetNoDataValueCastToDouble(int64_t nVal);
330 double CPL_DLL GDALGetNoDataValueCastToDouble(uint64_t nVal);
331
332// Remove me in GDAL 4.0. See GetMetadataItem() implementation
333// Internal use in GDAL only !
334// Declaration copied in swig/include/gdal.i
335 void CPL_DLL GDALEnablePixelTypeSignedByteWarning(GDALRasterBandH hBand,
336 bool b);
337
338std::string CPL_DLL GDALGetCompressionFormatForJPEG(VSILFILE *fp);
339std::string CPL_DLL GDALGetCompressionFormatForJPEG(const void *pBuffer,
340 size_t nBufferSize);
341
342 GDALRasterAttributeTable CPL_DLL *GDALCreateRasterAttributeTableFromMDArrays(
343 GDALRATTableType eTableType,
344 const std::vector<std::shared_ptr<GDALMDArray>> &apoArrays,
345 const std::vector<GDALRATFieldUsage> &aeUsages);
346
347 GDALColorInterp CPL_DLL
348GDALGetColorInterpFromSTACCommonName(const char *pszName);
349 const char CPL_DLL *
350GDALGetSTACCommonNameFromColorInterp(GDALColorInterp eInterp);
351
352std::string CPL_DLL GDALGetCacheDirectory();
353
354 bool GDALDoesFileOrDatasetExist(const char *pszName,
355 const char **ppszType = nullptr,
356 GDALDriver **ppDriver = nullptr);
357
358std::string CPL_DLL
359GDALGetMessageAboutMissingPluginDriver(GDALDriver *poMissingPluginDriver);
360
361std::string GDALPrintDriverList(int nOptions, bool bJSON);
362
363 struct GDALColorAssociation
364{
365 double dfVal;
366 int nR;
367 int nG;
368 int nB;
369 int nA;
370};
371
372std::vector<GDALColorAssociation> GDALLoadTextColorMap(const char *pszFilename,
373 GDALRasterBand *poBand);
374
375 namespace GDAL
376{
377 inline CPLErr Combine(CPLErr eErr1, CPLErr eErr2)
378{
379 return eErr1 == CE_None ? eErr2 : eErr1;
380}
381
382 inline CPLErr Combine(CPLErr eErr1, int) = delete;
383
384 inline CPLErr Combine(CPLErr eErr1, bool b)
385{
386 return eErr1 == CE_None ? (b ? CE_None : CE_Failure) : eErr1;
387}
388
389} // namespace GDAL
390
391 CPLStringList CPL_DLL GDALReadENVIHeader(VSILFILE *fpHdr);
392 CPLStringList CPL_DLL GDALENVISplitList(const char *pszCleanInput);
393 void CPL_DLL GDALApplyENVIHeaders(GDALDataset *poDS,
394 const CPLStringList &aosHeaders,
395 CSLConstList papszOptions);
396
398
399#endif
CPLStringList
String list class designed around our use of C "char**" string lists.
Definition cpl_string.h:458
CPLString
Convenient string class based on std::string.
Definition cpl_string.h:320
GDALColorTable
A color table / palette.
Definition gdal_colortable.h:32
GDALDataset
A set of associated raster bands, usually from one file.
Definition gdal_dataset.h:76
GDALDriver
Format specific driver.
Definition gdal_driver.h:63
GDALGeoTransform
Class that encapsulates a geotransform matrix.
Definition gdal_geotransform.h:42
GDALMDArray
Class modeling a multi-dimensional array.
Definition gdal_multidim.h:852
GDALRasterAttributeTable
The GDALRasterAttributeTable (or RAT) class is used to encapsulate a table used to provide attribute ...
Definition gdal_rat.h:48
GDALRasterBand
A single raster band (or channel).
Definition gdal_rasterband.h:105
OGRSpatialReference
This class represents an OpenGIS Spatial Reference System, and contains methods for converting betwee...
Definition ogr_spatialref.h:152
cpl_error.h
CPL error handling services.
CPLErr
CPLErr
Error category.
Definition cpl_error.h:37
cpl_port.h
Core portability definitions for CPL.
CPL_RESTRICT
#define CPL_RESTRICT
restrict keyword to declare that pointers do not alias
Definition cpl_port.h:916
CPL_C_END
#define CPL_C_END
Macro to end a block of C symbols.
Definition cpl_port.h:289
CPL_C_START
#define CPL_C_START
Macro to start a block of C symbols.
Definition cpl_port.h:285
CSLConstList
char ** CSLConstList
Type of a constant null-terminated list of nul terminated strings.
Definition cpl_port.h:1087
GByte
unsigned char GByte
Unsigned byte type.
Definition cpl_port.h:175
GIntBig
long long GIntBig
Large signed integer type (generally 64-bit integer type).
Definition cpl_port.h:205
cpl_string.h
Various convenience functions for working with strings and string lists.
gdal.h
Public (C callable) GDAL entry points.
GDALRATTableType
GDALRATTableType
RAT table type (thematic or athematic)
Definition gdal.h:2265
GDALAccess
GDALAccess
Definition gdal.h:120
GDALDataType
GDALDataType
Definition gdal.h:48
GDT_Unknown
@ GDT_Unknown
Definition gdal.h:49
GDALCreateRasterAttributeTableFromMDArrays
GDALRasterAttributeTableH GDALCreateRasterAttributeTableFromMDArrays(GDALRATTableType eTableType, int nArrays, const GDALMDArrayH *ahArrays, const GDALRATFieldUsage *paeUsages)
Return a virtual Raster Attribute Table from several GDALMDArray's.
Definition gdalmultidim_rat.cpp:511
GDALRIOResampleAlg
GDALRIOResampleAlg
RasterIO() resampling method.
Definition gdal.h:137
GDALGetThreadSafeDataset
GDALDatasetH GDALGetThreadSafeDataset(GDALDatasetH, int nScopeFlags, CSLConstList papszOptions)
Return a thread-safe dataset.
Definition gdalthreadsafedataset.cpp:1285
GDALColorInterp
GDALColorInterp
Types of color interpretation for raster bands.
Definition gdal.h:272
GDALDriverH
void * GDALDriverH
Opaque type used for the C bindings of the C++ GDALDriver class.
Definition gdal_fwd.h:51
GDALRasterBandH
void * GDALRasterBandH
Opaque type used for the C bindings of the C++ GDALRasterBand class.
Definition gdal_fwd.h:45
CPLXMLNode
Document node structure.
Definition cpl_minixml.h:54
GDALRasterIOExtraArg
Structure to pass extra arguments to RasterIO() method, must be initialized with INIT_RASTERIO_EXTRA_...
Definition gdal.h:170
GDAL_GCP
Ground Control Point.
Definition gdal.h:1223
VSIVirtualHandle
Virtual file handle.
Definition cpl_vsi_virtual.h:48