1/* ******************************************************************
2 FSE : Finite State Entropy codec
3 Public Prototypes declaration
4 Copyright (C) 2013-2016, Yann Collet.
5
6 BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php)
7
8 Redistribution and use in source and binary forms, with or without
9 modification, are permitted provided that the following conditions are
10 met:
11
12 * Redistributions of source code must retain the above copyright
13 notice, this list of conditions and the following disclaimer.
14 * Redistributions in binary form must reproduce the above
15 copyright notice, this list of conditions and the following disclaimer
16 in the documentation and/or other materials provided with the
17 distribution.
18
19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30
31 You can contact the author at :
32 - Source repository : https://github.com/Cyan4973/FiniteStateEntropy
33****************************************************************** */
34
35#if defined (__cplusplus)
36extern "C" {
37#endif
38
39#ifndef FSE_H
40#define FSE_H
41
42
43/*-*****************************************
44* Dependencies
45******************************************/
46#include <stddef.h> /* size_t, ptrdiff_t */
47
48
49/*-*****************************************
50* FSE_PUBLIC_API : control library symbols visibility
51******************************************/
52#if defined(FSE_DLL_EXPORT) && (FSE_DLL_EXPORT==1) && defined(__GNUC__) && (__GNUC__ >= 4)
53# define FSE_PUBLIC_API __attribute__ ((visibility ("default")))
54#elif defined(FSE_DLL_EXPORT) && (FSE_DLL_EXPORT==1) /* Visual expected */
55# define FSE_PUBLIC_API __declspec(dllexport)
56#elif defined(FSE_DLL_IMPORT) && (FSE_DLL_IMPORT==1)
57# define FSE_PUBLIC_API __declspec(dllimport) /* It isn't required but allows to generate better code, saving a function pointer load from the IAT and an indirect jump.*/
58#else
59# define FSE_PUBLIC_API
60#endif
61
62/*------ Version ------*/
63#define FSE_VERSION_MAJOR 0
64#define FSE_VERSION_MINOR 9
65#define FSE_VERSION_RELEASE 0
66
67#define FSE_LIB_VERSION FSE_VERSION_MAJOR.FSE_VERSION_MINOR.FSE_VERSION_RELEASE
68#define FSE_QUOTE(str) #str
69#define FSE_EXPAND_AND_QUOTE(str) FSE_QUOTE(str)
70#define FSE_VERSION_STRING FSE_EXPAND_AND_QUOTE(FSE_LIB_VERSION)
71
72#define FSE_VERSION_NUMBER (FSE_VERSION_MAJOR *100*100 + FSE_VERSION_MINOR *100 + FSE_VERSION_RELEASE)
73FSE_PUBLIC_API unsigned FSE_versionNumber(void); /**< library version number; to be used when checking dll version */
74
75/*-****************************************
76* FSE simple functions
77******************************************/
78/*! FSE_compress() :
79 Compress content of buffer 'src', of size 'srcSize', into destination buffer 'dst'.
80 'dst' buffer must be already allocated. Compression runs faster is dstCapacity >= FSE_compressBound(srcSize).
81 @return : size of compressed data (<= dstCapacity).
82 Special values : if return == 0, srcData is not compressible => Nothing is stored within dst !!!
83 if return == 1, srcData is a single byte symbol * srcSize times. Use RLE compression instead.
84 if FSE_isError(return), compression failed (more details using FSE_getErrorName())
85*/
86FSE_PUBLIC_API size_t FSE_compress(void* dst, size_t dstCapacity,
87 const void* src, size_t srcSize);
88
89/*! FSE_decompress():
90 Decompress FSE data from buffer 'cSrc', of size 'cSrcSize',
91 into already allocated destination buffer 'dst', of size 'dstCapacity'.
92 @return : size of regenerated data (<= maxDstSize),
93 or an error code, which can be tested using FSE_isError() .
94
95 ** Important ** : FSE_decompress() does not decompress non-compressible nor RLE data !!!
96 Why ? : making this distinction requires a header.
97 Header management is intentionally delegated to the user layer, which can better manage special cases.
98*/
99FSE_PUBLIC_API size_t FSE_decompress(void* dst, size_t dstCapacity,
100 const void* cSrc, size_t cSrcSize);
101
102
103/*-*****************************************
104* Tool functions
105******************************************/
106FSE_PUBLIC_API size_t FSE_compressBound(size_t size); /* maximum compressed size */
107
108/* Error Management */
109FSE_PUBLIC_API unsigned FSE_isError(size_t code); /* tells if a return value is an error code */
110FSE_PUBLIC_API const char* FSE_getErrorName(size_t code); /* provides error code string (useful for debugging) */
111
112
113/*-*****************************************
114* FSE advanced functions
115******************************************/
116/*! FSE_compress2() :
117 Same as FSE_compress(), but allows the selection of 'maxSymbolValue' and 'tableLog'
118 Both parameters can be defined as '0' to mean : use default value
119 @return : size of compressed data
120 Special values : if return == 0, srcData is not compressible => Nothing is stored within cSrc !!!
121 if return == 1, srcData is a single byte symbol * srcSize times. Use RLE compression.
122 if FSE_isError(return), it's an error code.
123*/
124FSE_PUBLIC_API size_t FSE_compress2 (void* dst, size_t dstSize, const void* src, size_t srcSize, unsigned maxSymbolValue, unsigned tableLog);
125
126
127/*-*****************************************
128* FSE detailed API
129******************************************/
130/*!
131FSE_compress() does the following:
1321. count symbol occurrence from source[] into table count[]
1332. normalize counters so that sum(count[]) == Power_of_2 (2^tableLog)
1343. save normalized counters to memory buffer using writeNCount()
1354. build encoding table 'CTable' from normalized counters
1365. encode the data stream using encoding table 'CTable'
137
138FSE_decompress() does the following:
1391. read normalized counters with readNCount()
1402. build decoding table 'DTable' from normalized counters
1413. decode the data stream using decoding table 'DTable'
142
143The following API allows targeting specific sub-functions for advanced tasks.
144For example, it's possible to compress several blocks using the same 'CTable',
145or to save and provide normalized distribution using external method.
146*/
147
148/* *** COMPRESSION *** */
149
150/*! FSE_count():
151 Provides the precise count of each byte within a table 'count'.
152 'count' is a table of unsigned int, of minimum size (*maxSymbolValuePtr+1).
153 *maxSymbolValuePtr will be updated if detected smaller than initial value.
154 @return : the count of the most frequent symbol (which is not identified).
155 if return == srcSize, there is only one symbol.
156 Can also return an error code, which can be tested with FSE_isError(). */
157FSE_PUBLIC_API size_t FSE_count(unsigned* count, unsigned* maxSymbolValuePtr, const void* src, size_t srcSize);
158
159/*! FSE_optimalTableLog():
160 dynamically downsize 'tableLog' when conditions are met.
161 It saves CPU time, by using smaller tables, while preserving or even improving compression ratio.
162 @return : recommended tableLog (necessarily <= 'maxTableLog') */
163FSE_PUBLIC_API unsigned FSE_optimalTableLog(unsigned maxTableLog, size_t srcSize, unsigned maxSymbolValue);
164
165/*! FSE_normalizeCount():
166 normalize counts so that sum(count[]) == Power_of_2 (2^tableLog)
167 'normalizedCounter' is a table of short, of minimum size (maxSymbolValue+1).
168 @return : tableLog,
169 or an errorCode, which can be tested using FSE_isError() */
170FSE_PUBLIC_API size_t FSE_normalizeCount(short* normalizedCounter, unsigned tableLog, const unsigned* count, size_t srcSize, unsigned maxSymbolValue);
171
172/*! FSE_NCountWriteBound():
173 Provides the maximum possible size of an FSE normalized table, given 'maxSymbolValue' and 'tableLog'.
174 Typically useful for allocation purpose. */
175FSE_PUBLIC_API size_t FSE_NCountWriteBound(unsigned maxSymbolValue, unsigned tableLog);
176
177/*! FSE_writeNCount():
178 Compactly save 'normalizedCounter' into 'buffer'.
179 @return : size of the compressed table,
180 or an errorCode, which can be tested using FSE_isError(). */
181FSE_PUBLIC_API size_t FSE_writeNCount (void* buffer, size_t bufferSize, const short* normalizedCounter, unsigned maxSymbolValue, unsigned tableLog);
182
183
184/*! Constructor and Destructor of FSE_CTable.
185 Note that FSE_CTable size depends on 'tableLog' and 'maxSymbolValue' */
186typedef unsigned FSE_CTable; /* don't allocate that. It's only meant to be more restrictive than void* */
187FSE_PUBLIC_API FSE_CTable* FSE_createCTable (unsigned maxSymbolValue, unsigned tableLog);
188FSE_PUBLIC_API void FSE_freeCTable (FSE_CTable* ct);
189
190/*! FSE_buildCTable():
191 Builds `ct`, which must be already allocated, using FSE_createCTable().
192 @return : 0, or an errorCode, which can be tested using FSE_isError() */
193FSE_PUBLIC_API size_t FSE_buildCTable(FSE_CTable* ct, const short* normalizedCounter, unsigned maxSymbolValue, unsigned tableLog);
194
195/*! FSE_compress_usingCTable():
196 Compress `src` using `ct` into `dst` which must be already allocated.
197 @return : size of compressed data (<= `dstCapacity`),
198 or 0 if compressed data could not fit into `dst`,
199 or an errorCode, which can be tested using FSE_isError() */
200FSE_PUBLIC_API size_t FSE_compress_usingCTable (void* dst, size_t dstCapacity, const void* src, size_t srcSize, const FSE_CTable* ct);
201
202/*!
203Tutorial :
204----------
205The first step is to count all symbols. FSE_count() does this job very fast.
206Result will be saved into 'count', a table of unsigned int, which must be already allocated, and have 'maxSymbolValuePtr[0]+1' cells.
207'src' is a table of bytes of size 'srcSize'. All values within 'src' MUST be <= maxSymbolValuePtr[0]
208maxSymbolValuePtr[0] will be updated, with its real value (necessarily <= original value)
209FSE_count() will return the number of occurrence of the most frequent symbol.
210This can be used to know if there is a single symbol within 'src', and to quickly evaluate its compressibility.
211If there is an error, the function will return an ErrorCode (which can be tested using FSE_isError()).
212
213The next step is to normalize the frequencies.
214FSE_normalizeCount() will ensure that sum of frequencies is == 2 ^'tableLog'.
215It also guarantees a minimum of 1 to any Symbol with frequency >= 1.
216You can use 'tableLog'==0 to mean "use default tableLog value".
217If you are unsure of which tableLog value to use, you can ask FSE_optimalTableLog(),
218which will provide the optimal valid tableLog given sourceSize, maxSymbolValue, and a user-defined maximum (0 means "default").
219
220The result of FSE_normalizeCount() will be saved into a table,
221called 'normalizedCounter', which is a table of signed short.
222'normalizedCounter' must be already allocated, and have at least 'maxSymbolValue+1' cells.
223The return value is tableLog if everything proceeded as expected.
224It is 0 if there is a single symbol within distribution.
225If there is an error (ex: invalid tableLog value), the function will return an ErrorCode (which can be tested using FSE_isError()).
226
227'normalizedCounter' can be saved in a compact manner to a memory area using FSE_writeNCount().
228'buffer' must be already allocated.
229For guaranteed success, buffer size must be at least FSE_headerBound().
230The result of the function is the number of bytes written into 'buffer'.
231If there is an error, the function will return an ErrorCode (which can be tested using FSE_isError(); ex : buffer size too small).
232
233'normalizedCounter' can then be used to create the compression table 'CTable'.
234The space required by 'CTable' must be already allocated, using FSE_createCTable().
235You can then use FSE_buildCTable() to fill 'CTable'.
236If there is an error, both functions will return an ErrorCode (which can be tested using FSE_isError()).
237
238'CTable' can then be used to compress 'src', with FSE_compress_usingCTable().
239Similar to FSE_count(), the convention is that 'src' is assumed to be a table of char of size 'srcSize'
240The function returns the size of compressed data (without header), necessarily <= `dstCapacity`.
241If it returns '0', compressed data could not fit into 'dst'.
242If there is an error, the function will return an ErrorCode (which can be tested using FSE_isError()).
243*/
244
245
246/* *** DECOMPRESSION *** */
247
248/*! FSE_readNCount():
249 Read compactly saved 'normalizedCounter' from 'rBuffer'.
250 @return : size read from 'rBuffer',
251 or an errorCode, which can be tested using FSE_isError().
252 maxSymbolValuePtr[0] and tableLogPtr[0] will also be updated with their respective values */
253FSE_PUBLIC_API size_t FSE_readNCount (short* normalizedCounter, unsigned* maxSymbolValuePtr, unsigned* tableLogPtr, const void* rBuffer, size_t rBuffSize);
254
255/*! Constructor and Destructor of FSE_DTable.
256 Note that its size depends on 'tableLog' */
257typedef unsigned FSE_DTable; /* don't allocate that. It's just a way to be more restrictive than void* */
258FSE_PUBLIC_API FSE_DTable* FSE_createDTable(unsigned tableLog);
259FSE_PUBLIC_API void FSE_freeDTable(FSE_DTable* dt);
260
261/*! FSE_buildDTable():
262 Builds 'dt', which must be already allocated, using FSE_createDTable().
263 return : 0, or an errorCode, which can be tested using FSE_isError() */
264FSE_PUBLIC_API size_t FSE_buildDTable (FSE_DTable* dt, const short* normalizedCounter, unsigned maxSymbolValue, unsigned tableLog);
265
266/*! FSE_decompress_usingDTable():
267 Decompress compressed source `cSrc` of size `cSrcSize` using `dt`
268 into `dst` which must be already allocated.
269 @return : size of regenerated data (necessarily <= `dstCapacity`),
270 or an errorCode, which can be tested using FSE_isError() */
271FSE_PUBLIC_API size_t FSE_decompress_usingDTable(void* dst, size_t dstCapacity, const void* cSrc, size_t cSrcSize, const FSE_DTable* dt);
272
273/*!
274Tutorial :
275----------
276(Note : these functions only decompress FSE-compressed blocks.
277 If block is uncompressed, use memcpy() instead
278 If block is a single repeated byte, use memset() instead )
279
280The first step is to obtain the normalized frequencies of symbols.
281This can be performed by FSE_readNCount() if it was saved using FSE_writeNCount().
282'normalizedCounter' must be already allocated, and have at least 'maxSymbolValuePtr[0]+1' cells of signed short.
283In practice, that means it's necessary to know 'maxSymbolValue' beforehand,
284or size the table to handle worst case situations (typically 256).
285FSE_readNCount() will provide 'tableLog' and 'maxSymbolValue'.
286The result of FSE_readNCount() is the number of bytes read from 'rBuffer'.
287Note that 'rBufferSize' must be at least 4 bytes, even if useful information is less than that.
288If there is an error, the function will return an error code, which can be tested using FSE_isError().
289
290The next step is to build the decompression tables 'FSE_DTable' from 'normalizedCounter'.
291This is performed by the function FSE_buildDTable().
292The space required by 'FSE_DTable' must be already allocated using FSE_createDTable().
293If there is an error, the function will return an error code, which can be tested using FSE_isError().
294
295`FSE_DTable` can then be used to decompress `cSrc`, with FSE_decompress_usingDTable().
296`cSrcSize` must be strictly correct, otherwise decompression will fail.
297FSE_decompress_usingDTable() result will tell how many bytes were regenerated (<=`dstCapacity`).
298If there is an error, the function will return an error code, which can be tested using FSE_isError(). (ex: dst buffer too small)
299*/
300
301#endif /* FSE_H */
302
303#if defined(FSE_STATIC_LINKING_ONLY) && !defined(FSE_H_FSE_STATIC_LINKING_ONLY)
304#define FSE_H_FSE_STATIC_LINKING_ONLY
305
306/* *** Dependency *** */
307#include "bitstream.h"
308
309
310/* *****************************************
311* Static allocation
312*******************************************/
313/* FSE buffer bounds */
314#define FSE_NCOUNTBOUND 512
315#define FSE_BLOCKBOUND(size) (size + (size>>7))
316#define FSE_COMPRESSBOUND(size) (FSE_NCOUNTBOUND + FSE_BLOCKBOUND(size)) /* Macro version, useful for static allocation */
317
318/* It is possible to statically allocate FSE CTable/DTable as a table of FSE_CTable/FSE_DTable using below macros */
319#define FSE_CTABLE_SIZE_U32(maxTableLog, maxSymbolValue) (1 + (1<<(maxTableLog-1)) + ((maxSymbolValue+1)*2))
320#define FSE_DTABLE_SIZE_U32(maxTableLog) (1 + (1<<maxTableLog))
321
322/* or use the size to malloc() space directly. Pay attention to alignment restrictions though */
323#define FSE_CTABLE_SIZE(maxTableLog, maxSymbolValue) (FSE_CTABLE_SIZE_U32(maxTableLog, maxSymbolValue) * sizeof(FSE_CTable))
324#define FSE_DTABLE_SIZE(maxTableLog) (FSE_DTABLE_SIZE_U32(maxTableLog) * sizeof(FSE_DTable))
325
326
327/* *****************************************
328* FSE advanced API
329*******************************************/
330/* FSE_count_wksp() :
331 * Same as FSE_count(), but using an externally provided scratch buffer.
332 * `workSpace` size must be table of >= `1024` unsigned
333 */
334size_t FSE_count_wksp(unsigned* count, unsigned* maxSymbolValuePtr,
335 const void* source, size_t sourceSize, unsigned* workSpace);
336
337/** FSE_countFast() :
338 * same as FSE_count(), but blindly trusts that all byte values within src are <= *maxSymbolValuePtr
339 */
340size_t FSE_countFast(unsigned* count, unsigned* maxSymbolValuePtr, const void* src, size_t srcSize);
341
342/* FSE_countFast_wksp() :
343 * Same as FSE_countFast(), but using an externally provided scratch buffer.
344 * `workSpace` must be a table of minimum `1024` unsigned
345 */
346size_t FSE_countFast_wksp(unsigned* count, unsigned* maxSymbolValuePtr, const void* src, size_t srcSize, unsigned* workSpace);
347
348/*! FSE_count_simple() :
349 * Same as FSE_countFast(), but does not use any additional memory (not even on stack).
350 * This function is unsafe, and will segfault if any value within `src` is `> *maxSymbolValuePtr` (presuming it's also the size of `count`).
351*/
352size_t FSE_count_simple(unsigned* count, unsigned* maxSymbolValuePtr, const void* src, size_t srcSize);
353
354
355
356unsigned FSE_optimalTableLog_internal(unsigned maxTableLog, size_t srcSize, unsigned maxSymbolValue, unsigned minus);
357/**< same as FSE_optimalTableLog(), which used `minus==2` */
358
359/* FSE_compress_wksp() :
360 * Same as FSE_compress2(), but using an externally allocated scratch buffer (`workSpace`).
361 * FSE_WKSP_SIZE_U32() provides the minimum size required for `workSpace` as a table of FSE_CTable.
362 */
363#define FSE_WKSP_SIZE_U32(maxTableLog, maxSymbolValue) ( FSE_CTABLE_SIZE_U32(maxTableLog, maxSymbolValue) + ((maxTableLog > 12) ? (1 << (maxTableLog - 2)) : 1024) )
364size_t FSE_compress_wksp (void* dst, size_t dstSize, const void* src, size_t srcSize, unsigned maxSymbolValue, unsigned tableLog, void* workSpace, size_t wkspSize);
365
366size_t FSE_buildCTable_raw (FSE_CTable* ct, unsigned nbBits);
367/**< build a fake FSE_CTable, designed for a flat distribution, where each symbol uses nbBits */
368
369size_t FSE_buildCTable_rle (FSE_CTable* ct, unsigned char symbolValue);
370/**< build a fake FSE_CTable, designed to compress always the same symbolValue */
371
372/* FSE_buildCTable_wksp() :
373 * Same as FSE_buildCTable(), but using an externally allocated scratch buffer (`workSpace`).
374 * `wkspSize` must be >= `(1<<tableLog)`.
375 */
376size_t FSE_buildCTable_wksp(FSE_CTable* ct, const short* normalizedCounter, unsigned maxSymbolValue, unsigned tableLog, void* workSpace, size_t wkspSize);
377
378size_t FSE_buildDTable_raw (FSE_DTable* dt, unsigned nbBits);
379/**< build a fake FSE_DTable, designed to read a flat distribution where each symbol uses nbBits */
380
381size_t FSE_buildDTable_rle (FSE_DTable* dt, unsigned char symbolValue);
382/**< build a fake FSE_DTable, designed to always generate the same symbolValue */
383
384size_t FSE_decompress_wksp(void* dst, size_t dstCapacity, const void* cSrc, size_t cSrcSize, FSE_DTable* workSpace, unsigned maxLog);
385/**< same as FSE_decompress(), using an externally allocated `workSpace` produced with `FSE_DTABLE_SIZE_U32(maxLog)` */
386
387typedef enum {
388 FSE_repeat_none, /**< Cannot use the previous table */
389 FSE_repeat_check, /**< Can use the previous table but it must be checked */
390 FSE_repeat_valid /**< Can use the previous table and it is asumed to be valid */
391 } FSE_repeat;
392
393/* *****************************************
394* FSE symbol compression API
395*******************************************/
396/*!
397 This API consists of small unitary functions, which highly benefit from being inlined.
398 Hence their body are included in next section.
399*/
400typedef struct {
401 ptrdiff_t value;
402 const void* stateTable;
403 const void* symbolTT;
404 unsigned stateLog;
405} FSE_CState_t;
406
407static void FSE_initCState(FSE_CState_t* CStatePtr, const FSE_CTable* ct);
408
409static void FSE_encodeSymbol(BIT_CStream_t* bitC, FSE_CState_t* CStatePtr, unsigned symbol);
410
411static void FSE_flushCState(BIT_CStream_t* bitC, const FSE_CState_t* CStatePtr);
412
413/**<
414These functions are inner components of FSE_compress_usingCTable().
415They allow the creation of custom streams, mixing multiple tables and bit sources.
416
417A key property to keep in mind is that encoding and decoding are done **in reverse direction**.
418So the first symbol you will encode is the last you will decode, like a LIFO stack.
419
420You will need a few variables to track your CStream. They are :
421
422FSE_CTable ct; // Provided by FSE_buildCTable()
423BIT_CStream_t bitStream; // bitStream tracking structure
424FSE_CState_t state; // State tracking structure (can have several)
425
426
427The first thing to do is to init bitStream and state.
428 size_t errorCode = BIT_initCStream(&bitStream, dstBuffer, maxDstSize);
429 FSE_initCState(&state, ct);
430
431Note that BIT_initCStream() can produce an error code, so its result should be tested, using FSE_isError();
432You can then encode your input data, byte after byte.
433FSE_encodeSymbol() outputs a maximum of 'tableLog' bits at a time.
434Remember decoding will be done in reverse direction.
435 FSE_encodeByte(&bitStream, &state, symbol);
436
437At any time, you can also add any bit sequence.
438Note : maximum allowed nbBits is 25, for compatibility with 32-bits decoders
439 BIT_addBits(&bitStream, bitField, nbBits);
440
441The above methods don't commit data to memory, they just store it into local register, for speed.
442Local register size is 64-bits on 64-bits systems, 32-bits on 32-bits systems (size_t).
443Writing data to memory is a manual operation, performed by the flushBits function.
444 BIT_flushBits(&bitStream);
445
446Your last FSE encoding operation shall be to flush your last state value(s).
447 FSE_flushState(&bitStream, &state);
448
449Finally, you must close the bitStream.
450The function returns the size of CStream in bytes.
451If data couldn't fit into dstBuffer, it will return a 0 ( == not compressible)
452If there is an error, it returns an errorCode (which can be tested using FSE_isError()).
453 size_t size = BIT_closeCStream(&bitStream);
454*/
455
456
457/* *****************************************
458* FSE symbol decompression API
459*******************************************/
460typedef struct {
461 size_t state;
462 const void* table; /* precise table may vary, depending on U16 */
463} FSE_DState_t;
464
465
466static void FSE_initDState(FSE_DState_t* DStatePtr, BIT_DStream_t* bitD, const FSE_DTable* dt);
467
468static unsigned char FSE_decodeSymbol(FSE_DState_t* DStatePtr, BIT_DStream_t* bitD);
469
470static unsigned FSE_endOfDState(const FSE_DState_t* DStatePtr);
471
472/**<
473Let's now decompose FSE_decompress_usingDTable() into its unitary components.
474You will decode FSE-encoded symbols from the bitStream,
475and also any other bitFields you put in, **in reverse order**.
476
477You will need a few variables to track your bitStream. They are :
478
479BIT_DStream_t DStream; // Stream context
480FSE_DState_t DState; // State context. Multiple ones are possible
481FSE_DTable* DTablePtr; // Decoding table, provided by FSE_buildDTable()
482
483The first thing to do is to init the bitStream.
484 errorCode = BIT_initDStream(&DStream, srcBuffer, srcSize);
485
486You should then retrieve your initial state(s)
487(in reverse flushing order if you have several ones) :
488 errorCode = FSE_initDState(&DState, &DStream, DTablePtr);
489
490You can then decode your data, symbol after symbol.
491For information the maximum number of bits read by FSE_decodeSymbol() is 'tableLog'.
492Keep in mind that symbols are decoded in reverse order, like a LIFO stack (last in, first out).
493 unsigned char symbol = FSE_decodeSymbol(&DState, &DStream);
494
495You can retrieve any bitfield you eventually stored into the bitStream (in reverse order)
496Note : maximum allowed nbBits is 25, for 32-bits compatibility
497 size_t bitField = BIT_readBits(&DStream, nbBits);
498
499All above operations only read from local register (which size depends on size_t).
500Refueling the register from memory is manually performed by the reload method.
501 endSignal = FSE_reloadDStream(&DStream);
502
503BIT_reloadDStream() result tells if there is still some more data to read from DStream.
504BIT_DStream_unfinished : there is still some data left into the DStream.
505BIT_DStream_endOfBuffer : Dstream reached end of buffer. Its container may no longer be completely filled.
506BIT_DStream_completed : Dstream reached its exact end, corresponding in general to decompression completed.
507BIT_DStream_tooFar : Dstream went too far. Decompression result is corrupted.
508
509When reaching end of buffer (BIT_DStream_endOfBuffer), progress slowly, notably if you decode multiple symbols per loop,
510to properly detect the exact end of stream.
511After each decoded symbol, check if DStream is fully consumed using this simple test :
512 BIT_reloadDStream(&DStream) >= BIT_DStream_completed
513
514When it's done, verify decompression is fully completed, by checking both DStream and the relevant states.
515Checking if DStream has reached its end is performed by :
516 BIT_endOfDStream(&DStream);
517Check also the states. There might be some symbols left there, if some high probability ones (>50%) are possible.
518 FSE_endOfDState(&DState);
519*/
520
521
522/* *****************************************
523* FSE unsafe API
524*******************************************/
525static unsigned char FSE_decodeSymbolFast(FSE_DState_t* DStatePtr, BIT_DStream_t* bitD);
526/* faster, but works only if nbBits is always >= 1 (otherwise, result will be corrupted) */
527
528
529/* *****************************************
530* Implementation of inlined functions
531*******************************************/
532typedef struct {
533 int deltaFindState;
534 U32 deltaNbBits;
535} FSE_symbolCompressionTransform; /* total 8 bytes */
536
537MEM_STATIC void FSE_initCState(FSE_CState_t* statePtr, const FSE_CTable* ct)
538{
539 const void* ptr = ct;
540 const U16* u16ptr = (const U16*) ptr;
541 const U32 tableLog = MEM_read16(ptr);
542 statePtr->value = (ptrdiff_t)1<<tableLog;
543 statePtr->stateTable = u16ptr+2;
544 statePtr->symbolTT = ((const U32*)ct + 1 + (tableLog ? (1<<(tableLog-1)) : 1));
545 statePtr->stateLog = tableLog;
546}
547
548
549/*! FSE_initCState2() :
550* Same as FSE_initCState(), but the first symbol to include (which will be the last to be read)
551* uses the smallest state value possible, saving the cost of this symbol */
552MEM_STATIC void FSE_initCState2(FSE_CState_t* statePtr, const FSE_CTable* ct, U32 symbol)
553{
554 FSE_initCState(statePtr, ct);
555 { const FSE_symbolCompressionTransform symbolTT = ((const FSE_symbolCompressionTransform*)(statePtr->symbolTT))[symbol];
556 const U16* stateTable = (const U16*)(statePtr->stateTable);
557 U32 nbBitsOut = (U32)((symbolTT.deltaNbBits + (1<<15)) >> 16);
558 statePtr->value = (nbBitsOut << 16) - symbolTT.deltaNbBits;
559 statePtr->value = stateTable[(statePtr->value >> nbBitsOut) + symbolTT.deltaFindState];
560 }
561}
562
563MEM_STATIC void FSE_encodeSymbol(BIT_CStream_t* bitC, FSE_CState_t* statePtr, U32 symbol)
564{
565 FSE_symbolCompressionTransform const symbolTT = ((const FSE_symbolCompressionTransform*)(statePtr->symbolTT))[symbol];
566 const U16* const stateTable = (const U16*)(statePtr->stateTable);
567 U32 const nbBitsOut = (U32)((statePtr->value + symbolTT.deltaNbBits) >> 16);
568 BIT_addBits(bitC, statePtr->value, nbBitsOut);
569 statePtr->value = stateTable[ (statePtr->value >> nbBitsOut) + symbolTT.deltaFindState];
570}
571
572MEM_STATIC void FSE_flushCState(BIT_CStream_t* bitC, const FSE_CState_t* statePtr)
573{
574 BIT_addBits(bitC, statePtr->value, statePtr->stateLog);
575 BIT_flushBits(bitC);
576}
577
578
579/* ====== Decompression ====== */
580
581typedef struct {
582 U16 tableLog;
583 U16 fastMode;
584} FSE_DTableHeader; /* sizeof U32 */
585
586typedef struct
587{
588 unsigned short newState;
589 unsigned char symbol;
590 unsigned char nbBits;
591} FSE_decode_t; /* size == U32 */
592
593MEM_STATIC void FSE_initDState(FSE_DState_t* DStatePtr, BIT_DStream_t* bitD, const FSE_DTable* dt)
594{
595 const void* ptr = dt;
596 const FSE_DTableHeader* const DTableH = (const FSE_DTableHeader*)ptr;
597 DStatePtr->state = BIT_readBits(bitD, DTableH->tableLog);
598 BIT_reloadDStream(bitD);
599 DStatePtr->table = dt + 1;
600}
601
602MEM_STATIC BYTE FSE_peekSymbol(const FSE_DState_t* DStatePtr)
603{
604 FSE_decode_t const DInfo = ((const FSE_decode_t*)(DStatePtr->table))[DStatePtr->state];
605 return DInfo.symbol;
606}
607
608MEM_STATIC void FSE_updateState(FSE_DState_t* DStatePtr, BIT_DStream_t* bitD)
609{
610 FSE_decode_t const DInfo = ((const FSE_decode_t*)(DStatePtr->table))[DStatePtr->state];
611 U32 const nbBits = DInfo.nbBits;
612 size_t const lowBits = BIT_readBits(bitD, nbBits);
613 DStatePtr->state = DInfo.newState + lowBits;
614}
615
616MEM_STATIC BYTE FSE_decodeSymbol(FSE_DState_t* DStatePtr, BIT_DStream_t* bitD)
617{
618 FSE_decode_t const DInfo = ((const FSE_decode_t*)(DStatePtr->table))[DStatePtr->state];
619 U32 const nbBits = DInfo.nbBits;
620 BYTE const symbol = DInfo.symbol;
621 size_t const lowBits = BIT_readBits(bitD, nbBits);
622
623 DStatePtr->state = DInfo.newState + lowBits;
624 return symbol;
625}
626
627/*! FSE_decodeSymbolFast() :
628 unsafe, only works if no symbol has a probability > 50% */
629MEM_STATIC BYTE FSE_decodeSymbolFast(FSE_DState_t* DStatePtr, BIT_DStream_t* bitD)
630{
631 FSE_decode_t const DInfo = ((const FSE_decode_t*)(DStatePtr->table))[DStatePtr->state];
632 U32 const nbBits = DInfo.nbBits;
633 BYTE const symbol = DInfo.symbol;
634 size_t const lowBits = BIT_readBitsFast(bitD, nbBits);
635
636 DStatePtr->state = DInfo.newState + lowBits;
637 return symbol;
638}
639
640MEM_STATIC unsigned FSE_endOfDState(const FSE_DState_t* DStatePtr)
641{
642 return DStatePtr->state == 0;
643}
644
645
646
647#ifndef FSE_COMMONDEFS_ONLY
648
649/* **************************************************************
650* Tuning parameters
651****************************************************************/
652/*!MEMORY_USAGE :
653* Memory usage formula : N->2^N Bytes (examples : 10 -> 1KB; 12 -> 4KB ; 16 -> 64KB; 20 -> 1MB; etc.)
654* Increasing memory usage improves compression ratio
655* Reduced memory usage can improve speed, due to cache effect
656* Recommended max value is 14, for 16KB, which nicely fits into Intel x86 L1 cache */
657#ifndef FSE_MAX_MEMORY_USAGE
658# define FSE_MAX_MEMORY_USAGE 14
659#endif
660#ifndef FSE_DEFAULT_MEMORY_USAGE
661# define FSE_DEFAULT_MEMORY_USAGE 13
662#endif
663
664/*!FSE_MAX_SYMBOL_VALUE :
665* Maximum symbol value authorized.
666* Required for proper stack allocation */
667#ifndef FSE_MAX_SYMBOL_VALUE
668# define FSE_MAX_SYMBOL_VALUE 255
669#endif
670
671/* **************************************************************
672* template functions type & suffix
673****************************************************************/
674#define FSE_FUNCTION_TYPE BYTE
675#define FSE_FUNCTION_EXTENSION
676#define FSE_DECODE_TYPE FSE_decode_t
677
678
679#endif /* !FSE_COMMONDEFS_ONLY */
680
681
682/* ***************************************************************
683* Constants
684*****************************************************************/
685#define FSE_MAX_TABLELOG (FSE_MAX_MEMORY_USAGE-2)
686#define FSE_MAX_TABLESIZE (1U<<FSE_MAX_TABLELOG)
687#define FSE_MAXTABLESIZE_MASK (FSE_MAX_TABLESIZE-1)
688#define FSE_DEFAULT_TABLELOG (FSE_DEFAULT_MEMORY_USAGE-2)
689#define FSE_MIN_TABLELOG 5
690
691#define FSE_TABLELOG_ABSOLUTE_MAX 15
692#if FSE_MAX_TABLELOG > FSE_TABLELOG_ABSOLUTE_MAX
693# error "FSE_MAX_TABLELOG > FSE_TABLELOG_ABSOLUTE_MAX is not supported"
694#endif
695
696#define FSE_TABLESTEP(tableSize) ((tableSize>>1) + (tableSize>>3) + 3)
697
698
699#endif /* FSE_STATIC_LINKING_ONLY */
700
701
702#if defined (__cplusplus)
703}
704#endif
705