Line data Source code
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 :
47 : //! @cond Doxygen_Suppress
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 :
67 : /** Arguments for overview resampling function. */
68 : // Should not contain any dataset/rasterband object, as this might be
69 : // read in a worker thread.
70 : struct GDALOverviewResampleArgs
71 : {
72 : //! Datatype of the source band argument
73 : GDALDataType eSrcDataType = GDT_Unknown;
74 : //! Datatype of the destination/overview band
75 : GDALDataType eOvrDataType = GDT_Unknown;
76 : //! Width in pixel of the destination/overview band
77 : int nOvrXSize = 0;
78 : //! Height in pixel of the destination/overview band
79 : int nOvrYSize = 0;
80 : //! NBITS value of the destination/overview band (or 0 if not set)
81 : int nOvrNBITS = 0;
82 : //! Factor to convert from destination X to source X
83 : // (source width divided by destination width)
84 : double dfXRatioDstToSrc = 0;
85 : //! Factor to convert from destination Y to source Y
86 : // (source height divided by destination height)
87 : double dfYRatioDstToSrc = 0;
88 : //! Sub-pixel delta to add to get source X
89 : double dfSrcXDelta = 0;
90 : //! Sub-pixel delta to add to get source Y
91 : double dfSrcYDelta = 0;
92 : //! Working data type (data type of the pChunk argument)
93 : GDALDataType eWrkDataType = GDT_Unknown;
94 : //! Array of nChunkXSize * nChunkYSize values of mask, or nullptr
95 : const GByte *pabyChunkNodataMask = nullptr;
96 : //! X offset of the source chunk in the source band
97 : int nChunkXOff = 0;
98 : //! Width in pixel of the source chunk in the source band
99 : int nChunkXSize = 0;
100 : //! Y offset of the source chunk in the source band
101 : int nChunkYOff = 0;
102 : //! Height in pixel of the source chunk in the source band
103 : int nChunkYSize = 0;
104 : //! X Offset of the destination chunk in the destination band
105 : int nDstXOff = 0;
106 : //! X Offset of the end (not included) of the destination chunk in the destination band
107 : int nDstXOff2 = 0;
108 : //! Y Offset of the destination chunk in the destination band
109 : int nDstYOff = 0;
110 : //! Y Offset of the end (not included) of the destination chunk in the destination band
111 : int nDstYOff2 = 0;
112 : //! Resampling method
113 : const char *pszResampling = nullptr;
114 : //! Whether the source band has a nodata value
115 : bool bHasNoData = false;
116 : //! Source band nodata value
117 : double dfNoDataValue = 0;
118 : //! Source color table
119 : const GDALColorTable *poColorTable = nullptr;
120 : //! Whether a single contributing source pixel at nodata should result
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 :
130 : GDALResampleFunction GDALGetResampleFunction(const char *pszResampling,
131 : int *pnRadius);
132 :
133 : std::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
141 : HFAAuxBuildOverviews(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 >,
220 : CSLConstList papszSiblingFiles,
221 : char **ppszWorldFileNameOut);
222 :
223 : std::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();
230 : CPLMutex **GDALGetphDMMutex();
231 : CPLMutex **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 : uint32_t nOffset, int bSwabflag,
241 : vsi_l_offset nTIFFHEADER,
242 : uint32_t &nExifOffset,
243 : uint32_t &nInterOffset,
244 : uint32_t &nGPSOffset);
245 :
246 : int GDALValidateOpenOptions(GDALDriverH hDriver,
247 : const char *const *papszOptionOptions);
248 : int GDALValidateOptions(const char *pszOptionList,
249 : const char *const *papszOptionsToValidate,
250 : const char *pszErrorMessageOptionType,
251 : const char *pszErrorMessageContainerName);
252 :
253 : GDALRIOResampleAlg CPL_DLL
254 : GDALRasterIOGetResampleAlg(const char *pszResampling);
255 : const char *GDALRasterIOGetResampleAlg(GDALRIOResampleAlg eResampleAlg);
256 :
257 : void GDALRasterIOExtraArgSetResampleAlg(GDALRasterIOExtraArg *psExtraArg,
258 : int nXSize, int nYSize, int nBufXSize,
259 : int nBufYSize);
260 :
261 : GDALDataset *GDALCreateOverviewDataset(GDALDataset *poDS, int nOvrLevel,
262 : bool bThisLevelOnly);
263 :
264 : // Should cover particular cases of #3573, #4183, #4506, #6578
265 : // Behavior is undefined if fVal1 or fVal2 are NaN (should be tested before
266 : // calling this function)
267 :
268 : // TODO: The expression `abs(fVal1 + fVal2)` looks strange; is this a bug?
269 : // Should this be `abs(fVal1) + abs(fVal2)` instead?
270 :
271 29379113 : inline bool ARE_REAL_EQUAL(float fVal1, float fVal2, int ulp = 2)
272 : {
273 : using std::abs;
274 57662518 : return fVal1 == fVal2 || /* Should cover infinity */
275 28283405 : abs(fVal1 - fVal2) <
276 57662518 : std::numeric_limits<float>::epsilon() * abs(fVal1 + fVal2) * ulp;
277 : }
278 :
279 : // We are using `std::numeric_limits<float>::epsilon()` for backward
280 : // compatibility
281 465246 : inline bool ARE_REAL_EQUAL(double dfVal1, double dfVal2, int ulp = 2)
282 : {
283 : using std::abs;
284 924740 : return dfVal1 == dfVal2 || /* Should cover infinity */
285 459494 : abs(dfVal1 - dfVal2) <
286 459494 : static_cast<double>(std::numeric_limits<float>::epsilon()) *
287 924740 : abs(dfVal1 + dfVal2) * ulp;
288 : }
289 :
290 : double GDALAdjustNoDataCloseToFloatMax(double dfVal);
291 :
292 : #define DIV_ROUND_UP(a, b) (((a) % (b)) == 0 ? ((a) / (b)) : (((a) / (b)) + 1))
293 :
294 : // Number of data samples that will be used to compute approximate statistics
295 : // (minimum value, maximum value, etc.)
296 : #define GDALSTAT_APPROX_NUMSAMPLES 2500
297 :
298 : void GDALSerializeGCPListToXML(CPLXMLNode *psParentNode,
299 : const std::vector<gdal::GCP> &asGCPs,
300 : const OGRSpatialReference *poGCP_SRS);
301 : void GDALDeserializeGCPListFromXML(const CPLXMLNode *psGCPList,
302 : std::vector<gdal::GCP> &asGCPs,
303 : OGRSpatialReference **ppoGCP_SRS);
304 :
305 : void GDALSerializeOpenOptionsToXML(CPLXMLNode *psParentNode,
306 : CSLConstList papszOpenOptions);
307 : char CPL_DLL **
308 : GDALDeserializeOpenOptionsFromXML(const CPLXMLNode *psParentNode);
309 :
310 : int GDALCanFileAcceptSidecarFile(const char *pszFilename);
311 :
312 : bool GDALCanReliablyUseSiblingFileList(const char *pszFilename);
313 :
314 : typedef enum
315 : {
316 : GSF_UNSIGNED_INT,
317 : GSF_SIGNED_INT,
318 : GSF_FLOATING_POINT,
319 : } GDALBufferSampleFormat;
320 :
321 : bool CPL_DLL GDALBufferHasOnlyNoData(const void *pBuffer, double dfNoDataValue,
322 : size_t nWidth, size_t nHeight,
323 : size_t nLineStride, size_t nComponents,
324 : int nBitsPerSample,
325 : GDALBufferSampleFormat nSampleFormat);
326 :
327 : bool CPL_DLL GDALCopyNoDataValue(GDALRasterBand *poDstBand,
328 : GDALRasterBand *poSrcBand,
329 : bool *pbCannotBeExactlyRepresented = nullptr);
330 :
331 : double CPL_DLL GDALGetNoDataValueCastToDouble(int64_t nVal);
332 : double CPL_DLL GDALGetNoDataValueCastToDouble(uint64_t nVal);
333 :
334 : // Remove me in GDAL 4.0. See GetMetadataItem() implementation
335 : // Internal use in GDAL only !
336 : // Declaration copied in swig/include/gdal.i
337 : void CPL_DLL GDALEnablePixelTypeSignedByteWarning(GDALRasterBandH hBand,
338 : bool b);
339 :
340 : std::string CPL_DLL GDALGetCompressionFormatForJPEG(VSILFILE *fp);
341 : std::string CPL_DLL GDALGetCompressionFormatForJPEG(const void *pBuffer,
342 : size_t nBufferSize);
343 :
344 : GDALRasterAttributeTable CPL_DLL *GDALCreateRasterAttributeTableFromMDArrays(
345 : GDALRATTableType eTableType,
346 : const std::vector<std::shared_ptr<GDALMDArray>> &apoArrays,
347 : const std::vector<GDALRATFieldUsage> &aeUsages);
348 :
349 : GDALColorInterp CPL_DLL
350 : GDALGetColorInterpFromSTACCommonName(const char *pszName);
351 : const char CPL_DLL *
352 : GDALGetSTACCommonNameFromColorInterp(GDALColorInterp eInterp);
353 :
354 : std::string CPL_DLL GDALGetCacheDirectory();
355 :
356 : bool GDALDoesFileOrDatasetExist(const char *pszName,
357 : const char **ppszType = nullptr,
358 : GDALDriver **ppDriver = nullptr);
359 :
360 : std::string CPL_DLL
361 : GDALGetMessageAboutMissingPluginDriver(GDALDriver *poMissingPluginDriver);
362 :
363 : std::string GDALPrintDriverList(int nOptions, bool bJSON);
364 :
365 : struct GDALColorAssociation
366 : {
367 : double dfVal;
368 : int nR;
369 : int nG;
370 : int nB;
371 : int nA;
372 : };
373 :
374 : std::vector<GDALColorAssociation> GDALLoadTextColorMap(const char *pszFilename,
375 : GDALRasterBand *poBand);
376 :
377 : namespace GDAL
378 : {
379 24006 : inline CPLErr Combine(CPLErr eErr1, CPLErr eErr2)
380 : {
381 24006 : return eErr1 == CE_None ? eErr2 : eErr1;
382 : }
383 :
384 : inline CPLErr Combine(CPLErr eErr1, int) = delete;
385 :
386 980 : inline CPLErr Combine(CPLErr eErr1, bool b)
387 : {
388 980 : return eErr1 == CE_None ? (b ? CE_None : CE_Failure) : eErr1;
389 : }
390 :
391 : } // namespace GDAL
392 :
393 : CPLStringList CPL_DLL GDALReadENVIHeader(VSILFILE *fpHdr);
394 : CPLStringList CPL_DLL GDALENVISplitList(const char *pszCleanInput);
395 : void CPL_DLL GDALApplyENVIHeaders(GDALDataset *poDS,
396 : const CPLStringList &aosHeaders,
397 : CSLConstList papszOptions);
398 :
399 : //! @endcond
400 :
401 : #endif
|
