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