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 : const 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 : int GDALBandGetBestOverviewLevel(GDALRasterBand *poBand,
230 : double dfTargetDownsamplingRatio,
231 : double dfOversamplingThreshold);
232 :
233 : void GDALNullifyOpenDatasetsList();
234 : CPLMutex **GDALGetphDMMutex();
235 : CPLMutex **GDALGetphDLMutex();
236 : void GDALNullifyProxyPoolSingleton();
237 : void GDALSetResponsiblePIDForCurrentThread(GIntBig responsiblePID);
238 : GIntBig GDALGetResponsiblePIDForCurrentThread();
239 :
240 : CPLString GDALFindAssociatedFile(const char *pszBasename, const char *pszExt,
241 : CSLConstList papszSiblingFiles, int nFlags);
242 :
243 : CPLErr CPL_DLL EXIFExtractMetadata(char **&papszMetadata, void *fpL,
244 : uint32_t nOffset, int bSwabflag,
245 : vsi_l_offset nTIFFHEADER,
246 : uint32_t &nExifOffset,
247 : uint32_t &nInterOffset,
248 : uint32_t &nGPSOffset);
249 :
250 : int GDALValidateOpenOptions(GDALDriverH hDriver,
251 : const char *const *papszOptionOptions);
252 : int GDALValidateOptions(GDALDriverH hDriver, const char *pszOptionList,
253 : const char *const *papszOptionsToValidate,
254 : const char *pszErrorMessageOptionType,
255 : const char *pszErrorMessageContainerName);
256 :
257 : GDALRIOResampleAlg CPL_DLL
258 : GDALRasterIOGetResampleAlg(const char *pszResampling);
259 : const char *GDALRasterIOGetResampleAlg(GDALRIOResampleAlg eResampleAlg);
260 :
261 : void GDALRasterIOExtraArgSetResampleAlg(GDALRasterIOExtraArg *psExtraArg,
262 : int nXSize, int nYSize, int nBufXSize,
263 : int nBufYSize);
264 :
265 : GDALDataset CPL_DLL *GDALCreateOverviewDataset(GDALDataset *poDS, int nOvrLevel,
266 : bool bThisLevelOnly);
267 :
268 : // Should cover particular cases of #3573, #4183, #4506, #6578
269 : // Behavior is undefined if fVal1 or fVal2 are NaN (should be tested before
270 : // calling this function)
271 :
272 : // TODO: The expression `abs(fVal1 + fVal2)` looks strange; is this a bug?
273 : // Should this be `abs(fVal1) + abs(fVal2)` instead?
274 :
275 51704013 : inline bool ARE_REAL_EQUAL(float fVal1, float fVal2, int ulp = 2)
276 : {
277 : using std::abs;
278 82483718 : return fVal1 == fVal2 || /* Should cover infinity */
279 30779805 : abs(fVal1 - fVal2) <
280 82483718 : std::numeric_limits<float>::epsilon() * abs(fVal1 + fVal2) * ulp;
281 : }
282 :
283 : // We are using `std::numeric_limits<float>::epsilon()` for backward
284 : // compatibility
285 575297 : inline bool ARE_REAL_EQUAL(double dfVal1, double dfVal2, int ulp = 2)
286 : {
287 : using std::abs;
288 1064685 : return dfVal1 == dfVal2 || /* Should cover infinity */
289 489386 : abs(dfVal1 - dfVal2) <
290 489386 : static_cast<double>(std::numeric_limits<float>::epsilon()) *
291 1064685 : abs(dfVal1 + dfVal2) * ulp;
292 : }
293 :
294 : double GDALAdjustNoDataCloseToFloatMax(double dfVal);
295 :
296 : #define DIV_ROUND_UP(a, b) (((a) % (b)) == 0 ? ((a) / (b)) : (((a) / (b)) + 1))
297 :
298 : // Number of data samples that will be used to compute approximate statistics
299 : // (minimum value, maximum value, etc.)
300 : #define GDALSTAT_APPROX_NUMSAMPLES 2500
301 :
302 : void GDALSerializeGCPListToXML(CPLXMLNode *psParentNode,
303 : const std::vector<gdal::GCP> &asGCPs,
304 : const OGRSpatialReference *poGCP_SRS);
305 : void GDALDeserializeGCPListFromXML(const CPLXMLNode *psGCPList,
306 : std::vector<gdal::GCP> &asGCPs,
307 : OGRSpatialReference **ppoGCP_SRS);
308 :
309 : void GDALSerializeOpenOptionsToXML(CPLXMLNode *psParentNode,
310 : CSLConstList papszOpenOptions);
311 : char CPL_DLL **
312 : GDALDeserializeOpenOptionsFromXML(const CPLXMLNode *psParentNode);
313 :
314 : int GDALCanFileAcceptSidecarFile(const char *pszFilename);
315 :
316 : bool GDALCanReliablyUseSiblingFileList(const char *pszFilename);
317 :
318 : typedef enum
319 : {
320 : GSF_UNSIGNED_INT,
321 : GSF_SIGNED_INT,
322 : GSF_FLOATING_POINT,
323 : } GDALBufferSampleFormat;
324 :
325 : bool CPL_DLL GDALBufferHasOnlyNoData(const void *pBuffer, double dfNoDataValue,
326 : size_t nWidth, size_t nHeight,
327 : size_t nLineStride, size_t nComponents,
328 : int nBitsPerSample,
329 : GDALBufferSampleFormat nSampleFormat);
330 :
331 : bool CPL_DLL GDALCopyNoDataValue(GDALRasterBand *poDstBand,
332 : GDALRasterBand *poSrcBand,
333 : bool *pbCannotBeExactlyRepresented = nullptr);
334 :
335 : double CPL_DLL GDALGetNoDataValueCastToDouble(int64_t nVal);
336 : double CPL_DLL GDALGetNoDataValueCastToDouble(uint64_t nVal);
337 :
338 : // Remove me in GDAL 4.0. See GetMetadataItem() implementation
339 : // Internal use in GDAL only !
340 : // Declaration copied in swig/include/gdal.i
341 : void CPL_DLL GDALEnablePixelTypeSignedByteWarning(GDALRasterBandH hBand,
342 : bool b);
343 :
344 : std::string CPL_DLL GDALGetCompressionFormatForJPEG(VSILFILE *fp);
345 : std::string CPL_DLL GDALGetCompressionFormatForJPEG(const void *pBuffer,
346 : size_t nBufferSize);
347 :
348 : GDALRasterAttributeTable CPL_DLL *GDALCreateRasterAttributeTableFromMDArrays(
349 : GDALRATTableType eTableType,
350 : const std::vector<std::shared_ptr<GDALMDArray>> &apoArrays,
351 : const std::vector<GDALRATFieldUsage> &aeUsages);
352 :
353 : GDALColorInterp CPL_DLL
354 : GDALGetColorInterpFromSTACCommonName(const char *pszName);
355 : const char CPL_DLL *
356 : GDALGetSTACCommonNameFromColorInterp(GDALColorInterp eInterp);
357 :
358 : std::string CPL_DLL GDALGetCacheDirectory();
359 :
360 : bool GDALDoesFileOrDatasetExist(const char *pszName,
361 : const char **ppszType = nullptr,
362 : GDALDriver **ppDriver = nullptr);
363 :
364 : std::string CPL_DLL
365 : GDALGetMessageAboutMissingPluginDriver(GDALDriver *poMissingPluginDriver);
366 :
367 : std::string GDALPrintDriverList(int nOptions, bool bJSON);
368 :
369 : struct GDALColorAssociation
370 : {
371 : double dfVal;
372 : int nR;
373 : int nG;
374 : int nB;
375 : int nA;
376 : };
377 :
378 : std::vector<GDALColorAssociation> GDALLoadTextColorMap(const char *pszFilename,
379 : GDALRasterBand *poBand);
380 :
381 : namespace GDAL
382 : {
383 24400 : inline CPLErr Combine(CPLErr eErr1, CPLErr eErr2)
384 : {
385 24400 : return eErr1 == CE_None ? eErr2 : eErr1;
386 : }
387 :
388 : inline CPLErr Combine(CPLErr eErr1, int) = delete;
389 :
390 1122 : inline CPLErr Combine(CPLErr eErr1, bool b)
391 : {
392 1122 : return eErr1 == CE_None ? (b ? CE_None : CE_Failure) : eErr1;
393 : }
394 :
395 : } // namespace GDAL
396 :
397 : CPLStringList CPL_DLL GDALReadENVIHeader(VSILFILE *fpHdr);
398 : CPLStringList CPL_DLL GDALENVISplitList(const char *pszCleanInput);
399 : void CPL_DLL GDALApplyENVIHeaders(GDALDataset *poDS,
400 : const CPLStringList &aosHeaders,
401 : CSLConstList papszOptions);
402 :
403 : class GDALAsyncReader;
404 :
405 : GDALAsyncReader *
406 : GDALGetDefaultAsyncReader(GDALDataset *poDS, int nXOff, int nYOff, int nXSize,
407 : int nYSize, void *pBuf, int nBufXSize, int nBufYSize,
408 : GDALDataType eBufType, int nBandCount,
409 : int *panBandMap, int nPixelSpace, int nLineSpace,
410 : int nBandSpace, CSLConstList papszOptions);
411 :
412 : //! @endcond
413 :
414 : #endif
|
