-
Notifications
You must be signed in to change notification settings - Fork 0
/
Lerc_c_api.h
182 lines (144 loc) · 9.83 KB
/
Lerc_c_api.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
/*
Copyright 2016 Esri
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
A local copy of the license and additional notices are located with the
source distribution at:
http://github.com/Esri/lerc/
Contributors: Thomas Maurer
*/
#ifndef LERC_API_INCLUDE_GUARD
#define LERC_API_INCLUDE_GUARD
#ifdef __cplusplus
extern "C" {
#endif
#if defined(_MSC_VER)
#define LERCDLL_API __declspec(dllexport)
#elif __GNUC__ >= 4
#define LERCDLL_API __attribute__((visibility("default")))
#else
#define LERCDLL_API
#endif
//! C-API for LERC library
//! All output buffers must have been allocated by caller.
typedef unsigned int lerc_status;
//! Compute the buffer size in bytes required to hold the compressed input tile. Optional.
//! You can call lerc_encode(...) directly as long as the output buffer is big enough.
//! Order of raw input data is top left corner to lower right corner, row by row. This for each band.
//! Data type is { char = 0, uchar = 1, short = 2, ushort = 3, int = 4, uint = 5, float = 6, double = 7 }, see Lerc_types.h .
//! maxZErr is the max compression error per pixel allowed.
//! The image or mask of valid pixels is optional. Null pointer means all pixels are valid.
//! If not all pixels are valid, set invalid pixel bytes to 0, valid pixel bytes to 1.
//! Size of the valid / invalid pixel image is nCols x nRows.
LERCDLL_API
lerc_status lerc_computeCompressedSize(
const void* pData, // raw image data, row by row, band by band
unsigned int dataType, // char = 0, uchar = 1, short = 2, ushort = 3, int = 4, uint = 5, float = 6, double = 7
int nDim, // number of values per pixel (e.g., 3 for RGB, data is stored as [RGB, RGB, ...])
int nCols, // number of columns
int nRows, // number of rows
int nBands, // number of bands (e.g., 3 for [RRRR ..., GGGG ..., BBBB ...])
const unsigned char* pValidBytes, // null ptr if all pixels are valid; otherwise 1 byte per pixel (1 = valid, 0 = invalid)
double maxZErr, // max coding error per pixel, defines the precision
unsigned int* numBytes); // size of outgoing Lerc blob
//! Encode the input data into a compressed Lerc blob.
LERCDLL_API
lerc_status lerc_encode(
const void* pData, // raw image data, row by row, band by band
unsigned int dataType, // char = 0, uchar = 1, short = 2, ushort = 3, int = 4, uint = 5, float = 6, double = 7
int nDim, // number of values per pixel (e.g., 3 for RGB, data is stored as [RGB, RGB, ...])
int nCols, // number of columns
int nRows, // number of rows
int nBands, // number of bands (e.g., 3 for [RRRR ..., GGGG ..., BBBB ...])
const unsigned char* pValidBytes, // null ptr if all pixels are valid; otherwise 1 byte per pixel (1 = valid, 0 = invalid)
double maxZErr, // max coding error per pixel, defines the precision
unsigned char* pOutBuffer, // buffer to write to, function fails if buffer too small
unsigned int outBufferSize, // size of output buffer
unsigned int* nBytesWritten); // number of bytes written to output buffer
//! Use the 2 functions below to encode to an older version
LERCDLL_API
lerc_status lerc_computeCompressedSizeForVersion(
const void* pData, // raw image data, row by row, band by band
int version, // 2 = v2.2, 3 = v2.3, 4 = v2.4
unsigned int dataType, // char = 0, uchar = 1, short = 2, ushort = 3, int = 4, uint = 5, float = 6, double = 7
int nDim, // number of values per pixel (e.g., 3 for RGB, data is stored as [RGB, RGB, ...])
int nCols, // number of columns
int nRows, // number of rows
int nBands, // number of bands (e.g., 3 for [RRRR ..., GGGG ..., BBBB ...])
const unsigned char* pValidBytes, // null ptr if all pixels are valid; otherwise 1 byte per pixel (1 = valid, 0 = invalid)
double maxZErr, // max coding error per pixel, defines the precision
unsigned int* numBytes); // size of outgoing Lerc blob
LERCDLL_API
lerc_status lerc_encodeForVersion(
const void* pData, // raw image data, row by row, band by band
int version, // 2 = v2.2, 3 = v2.3, 4 = v2.4
unsigned int dataType, // char = 0, uchar = 1, short = 2, ushort = 3, int = 4, uint = 5, float = 6, double = 7
int nDim, // number of values per pixel (e.g., 3 for RGB, data is stored as [RGB, RGB, ...])
int nCols, // number of columns
int nRows, // number of rows
int nBands, // number of bands (e.g., 3 for [RRRR ..., GGGG ..., BBBB ...])
const unsigned char* pValidBytes, // null ptr if all pixels are valid; otherwise 1 byte per pixel (1 = valid, 0 = invalid)
double maxZErr, // max coding error per pixel, defines the precision
unsigned char* pOutBuffer, // buffer to write to, function fails if buffer too small
unsigned int outBufferSize, // size of output buffer
unsigned int* nBytesWritten); // number of bytes written to output buffer
//! Call this to get info about the compressed Lerc blob. Optional.
//! Info returned in infoArray is { version, dataType, nDim, nCols, nRows, nBands, nValidPixels, blobSize }, see Lerc_types.h .
//! Info returned in dataRangeArray is { zMin, zMax, maxZErrorUsed }, see Lerc_types.h .
//! If nDim > 1 or nBands > 1 the data range [zMin, zMax] is over all values.
// Remark on function signature. The arrays to be filled may grow in future versions. In order not to break
// existing code, the function fills these arrays only up to their allocated size.
// Remark on param blobSize. Usually it is known, either the file size of the blob written to disk,
// or the size of the blob transmitted. It should be passed accurately for 2 reasons:
// _ function finds out how many single band Lerc blobs are concatenated, if any
// _ function checks for truncated file or blob
// It is OK to pass blobSize too large as long as there is no other (valid) Lerc blob following next.
// If in doubt, check the code in Lerc::GetLercInfo(...) for the exact logic.
LERCDLL_API
lerc_status lerc_getBlobInfo(
const unsigned char* pLercBlob, // Lerc blob to decode
unsigned int blobSize, // blob size in bytes
unsigned int* infoArray, // info array with all info needed to allocate the outgoing array for calling decode
double* dataRangeArray, // quick access to overall data range [zMin, zMax] without having to decode the data
int infoArraySize, // number of elements of infoArray
int dataRangeArraySize); // number of elements of dataRangeArray
//! Decode the compressed Lerc blob into a raw data array.
//! The data array must have been allocated to size (nDim * nCols * nRows * nBands * sizeof(dataType)).
//! The valid pixels array, if not 0, must have been allocated to size (nCols * nRows).
LERCDLL_API
lerc_status lerc_decode(
const unsigned char* pLercBlob, // Lerc blob to decode
unsigned int blobSize, // blob size in bytes
unsigned char* pValidBytes, // gets filled if not null ptr, even if all valid
int nDim, // number of values per pixel (e.g., 3 for RGB, data is stored as [RGB, RGB, ...])
int nCols, // number of columns
int nRows, // number of rows
int nBands, // number of bands (e.g., 3 for [RRRR ..., GGGG ..., BBBB ...])
unsigned int dataType, // char = 0, uchar = 1, short = 2, ushort = 3, int = 4, uint = 5, float = 6, double = 7
void* pData); // outgoing data array
//! Same as above, but decode into double array independent of compressed data type.
//! Wasteful in memory, but convenient if a caller from C# or Python does not want to deal with
//! data type conversion, templating, or casting.
//! Should this api be extended to new data types that don't fit into a double such as int64,
//! then this function will fail for such compressed data types.
LERCDLL_API
lerc_status lerc_decodeToDouble(
const unsigned char* pLercBlob, // Lerc blob to decode
unsigned int blobSize, // blob size in bytes
unsigned char* pValidBytes, // gets filled if not null ptr, even if all valid
int nDim, // number of values per pixel (e.g., 3 for RGB, data is stored as [RGB, RGB, ...])
int nCols, // number of columns
int nRows, // number of rows
int nBands, // number of bands (e.g., 3 for [RRRR ..., GGGG ..., BBBB ...])
double* pData); // outgoing data array
#ifdef __cplusplus
}
#endif
#endif // LERC_API_INCLUDE_GUARD