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 : 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
252 : GDALRasterIOGetResampleAlg(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 29379113 : inline bool ARE_REAL_EQUAL(float fVal1, float fVal2, int ulp = 2)
270 : {
271 : using std::abs;
272 57662518 : return fVal1 == fVal2 || /* Should cover infinity */
273 28283405 : abs(fVal1 - fVal2) <
274 57662518 : 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 3970949 : inline bool ARE_REAL_EQUAL(double dfVal1, double dfVal2, int ulp = 2)
280 : {
281 : using std::abs;
282 4601775 : return dfVal1 == dfVal2 || /* Should cover infinity */
283 630825 : abs(dfVal1 - dfVal2) <
284 630825 : static_cast<double>(std::numeric_limits<float>::epsilon()) *
285 4601775 : 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 **
306 : GDALDeserializeOpenOptionsFromXML(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 :
338 : std::string CPL_DLL GDALGetCompressionFormatForJPEG(VSILFILE *fp);
339 : std::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
348 : GDALGetColorInterpFromSTACCommonName(const char *pszName);
349 : const char CPL_DLL *
350 : GDALGetSTACCommonNameFromColorInterp(GDALColorInterp eInterp);
351 :
352 : std::string CPL_DLL GDALGetCacheDirectory();
353 :
354 : bool GDALDoesFileOrDatasetExist(const char *pszName,
355 : const char **ppszType = nullptr,
356 : GDALDriver **ppDriver = nullptr);
357 :
358 : std::string CPL_DLL
359 : GDALGetMessageAboutMissingPluginDriver(GDALDriver *poMissingPluginDriver);
360 :
361 : std::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 :
372 : std::vector<GDALColorAssociation> GDALLoadTextColorMap(const char *pszFilename,
373 : GDALRasterBand *poBand);
374 :
375 : namespace GDAL
376 : {
377 21736 : inline CPLErr Combine(CPLErr eErr1, CPLErr eErr2)
378 : {
379 21736 : return eErr1 == CE_None ? eErr2 : eErr1;
380 : }
381 :
382 : inline CPLErr Combine(CPLErr eErr1, int) = delete;
383 :
384 982 : inline CPLErr Combine(CPLErr eErr1, bool b)
385 : {
386 982 : return eErr1 == CE_None ? (b ? CE_None : CE_Failure) : eErr1;
387 : }
388 :
389 : } // namespace GDAL
390 :
391 : //! @endcond
392 :
393 : #endif
|
