//=================================================== // Oodle2 Core header // (C) Copyright 1994-2022 Epic Games Tools LLC //=================================================== #ifndef __OODLE2_H_INCLUDED__ #define __OODLE2_H_INCLUDED__ #ifndef OODLE2_PUBLIC_HEADER #define OODLE2_PUBLIC_HEADER 1 #endif #ifndef __OODLE2BASE_H_INCLUDED__ #include "oodle2base.h" #endif #ifdef _MSC_VER #pragma pack(push, Oodle, 8) #pragma warning(push) #pragma warning(disable : 4127) // conditional is constant #endif // header version : // the DLL is incompatible when MAJOR is bumped // MINOR is for internal revs and bug fixes that don't affect API compatibility #define OODLE2_VERSION_MAJOR 9 #define OODLE2_VERSION_MINOR 10 // OodleVersion string is 1 . MAJOR . MINOR // don't make it from macros cuz the doc tool has to parse the string literal #define OodleVersion "2.9.10" /* */ //----------------------------------------------------- // OodleLZ #if 0 #define OODLE_ALLOW_DEPRECATED_COMPRESSORS /* If you need to encode with the deprecated compressors, define this before including oodle2.h You may still decode with them without defining this. */ #endif // Default verbosity selection of 0 will not even log when it sees corruption typedef enum OodleLZ_Verbosity { OodleLZ_Verbosity_None = 0, OodleLZ_Verbosity_Minimal = 1, OodleLZ_Verbosity_Some = 2, OodleLZ_Verbosity_Lots = 3, OodleLZ_Verbosity_Force32 = 0x40000000 } OodleLZ_Verbosity; /* Verbosity of LZ functions LZ functions print information to the function set by $OodleCore_Plugins_SetPrintf or $OodleXLog_Printf if using OodleX. */ OO_COMPILER_ASSERT( sizeof(OodleLZ_Verbosity) == 4 ); typedef enum OodleLZ_Compressor { OodleLZ_Compressor_Invalid = -1, OodleLZ_Compressor_None = 3, // None = memcpy, pass through uncompressed bytes // NEW COMPRESSORS : OodleLZ_Compressor_Kraken = 8, // Fast decompression and high compression ratios, amazing! OodleLZ_Compressor_Leviathan = 13,// Leviathan = Kraken's big brother with higher compression, slightly slower decompression. OodleLZ_Compressor_Mermaid = 9, // Mermaid is between Kraken & Selkie - crazy fast, still decent compression. OodleLZ_Compressor_Selkie = 11, // Selkie is a super-fast relative of Mermaid. For maximum decode speed. OodleLZ_Compressor_Hydra = 12, // Hydra, the many-headed beast = Leviathan, Kraken, Mermaid, or Selkie (see $OodleLZ_About_Hydra) #ifdef OODLE_ALLOW_DEPRECATED_COMPRESSORS OodleLZ_Compressor_BitKnit = 10, // no longer supported as of Oodle 2.9.0 OodleLZ_Compressor_LZB16 = 4, // DEPRECATED but still supported OodleLZ_Compressor_LZNA = 7, // no longer supported as of Oodle 2.9.0 OodleLZ_Compressor_LZH = 0, // no longer supported as of Oodle 2.9.0 OodleLZ_Compressor_LZHLW = 1, // no longer supported as of Oodle 2.9.0 OodleLZ_Compressor_LZNIB = 2, // no longer supported as of Oodle 2.9.0 OodleLZ_Compressor_LZBLW = 5, // no longer supported as of Oodle 2.9.0 OodleLZ_Compressor_LZA = 6, // no longer supported as of Oodle 2.9.0 #endif OodleLZ_Compressor_Count = 14, OodleLZ_Compressor_Force32 = 0x40000000 } OodleLZ_Compressor; /* Selection of compression algorithm. Each compressor provides a different balance of speed vs compression ratio. New Oodle users should only use the new sea monster family of compressors. The OODLE_ALLOW_DEPRECATED_COMPRESSORS set of compressors is no longer supported as of Oodle 2.9.0 ; see $Oodle_FAQ_deprecated_compressors The sea monsters are all fuzz safe and use whole-block quantum (not the 16k quantum) ($OodleLZ_Compressor_UsesWholeBlockQuantum) If you need to encode the deprecated compressors, define $OODLE_ALLOW_DEPRECATED_COMPRESSORS before including oodle2.h See $Oodle_FAQ_WhichLZ for a quick FAQ on which compressor to use See $OodleLZ_About for discussion of how to choose a compressor. */ OO_COMPILER_ASSERT( sizeof(OodleLZ_Compressor) == 4 ); typedef enum OodleLZ_PackedRawOverlap { OodleLZ_PackedRawOverlap_No = 0, OodleLZ_PackedRawOverlap_Yes = 1, OodleLZ_PackedRawOverlap_Force32 = 0x40000000 } OodleLZ_PackedRawOverlap; /* Bool enum */ typedef enum OodleLZ_CheckCRC { OodleLZ_CheckCRC_No = 0, OodleLZ_CheckCRC_Yes = 1, OodleLZ_CheckCRC_Force32 = 0x40000000 } OodleLZ_CheckCRC; /* Bool enum for the LZ decoder - should it check CRC before decoding or not? NOTE : the CRC's in the LZH decompress checks are the CRC's of the *compressed* bytes. This allows checking the CRc prior to decompression, so corrupted data cannot be fed to the compressor. To use OodleLZ_CheckCRC_Yes, the compressed data must have been made with $(OodleLZ_CompressOptions:sendQuantumCRCs) set to true. If you want a CRC of the raw bytes, there is one optionally stored in the $OodleLZ_SeekTable and can be confirmed with $OodleLZ_CheckSeekTableCRCs */ typedef enum OodleLZ_Profile { OodleLZ_Profile_Main=0, // Main profile (all current features allowed) OodleLZ_Profile_Reduced=1, // Reduced profile (Kraken only, limited feature set) OodleLZ_Profile_Force32 = 0x40000000 } OodleLZ_Profile; /* Decode profile to target */ // Not flagged for idoc and done using a #define since it's internal (testing) use only #define OodleLZ_Profile_Internal_Custom ((OodleLZ_Profile)100) OO_COMPILER_ASSERT( sizeof(OodleLZ_Profile) == 4 ); typedef enum OodleDecompressCallbackRet { OodleDecompressCallbackRet_Continue=0, OodleDecompressCallbackRet_Cancel=1, OodleDecompressCallbackRet_Invalid=2, OodleDecompressCallbackRet_Force32 = 0x40000000 } OodleDecompressCallbackRet; /* Return value for $OodleDecompressCallback return OodleDecompressCallbackRet_Cancel to abort the in-progress decompression */ OODEFFUNC typedef OodleDecompressCallbackRet (OODLE_CALLBACK OodleDecompressCallback)(void * userdata, const OO_U8 * rawBuf,OO_SINTa rawLen,const OO_U8 * compBuf,OO_SINTa compBufferSize , OO_SINTa rawDone, OO_SINTa compUsed); /* User-provided callback for decompression $:userdata the data you passed for _pcbData_ $:rawBuf the decompressed buffer $:rawLen the total decompressed length $:compBuf the compressed buffer $:compBufferSize the total compressed length $:rawDone number of bytes in rawBuf decompressed so far $:compUsed number of bytes in compBuf consumed so far OodleDecompressCallback is called incrementally during decompression. */ typedef enum OodleLZ_CompressionLevel { OodleLZ_CompressionLevel_None=0, // don't compress, just copy raw bytes OodleLZ_CompressionLevel_SuperFast=1, // super fast mode, lower compression ratio OodleLZ_CompressionLevel_VeryFast=2, // fastest LZ mode with still decent compression ratio OodleLZ_CompressionLevel_Fast=3, // fast - good for daily use OodleLZ_CompressionLevel_Normal=4, // standard medium speed LZ mode OodleLZ_CompressionLevel_Optimal1=5, // optimal parse level 1 (faster optimal encoder) OodleLZ_CompressionLevel_Optimal2=6, // optimal parse level 2 (recommended baseline optimal encoder) OodleLZ_CompressionLevel_Optimal3=7, // optimal parse level 3 (slower optimal encoder) OodleLZ_CompressionLevel_Optimal4=8, // optimal parse level 4 (very slow optimal encoder) OodleLZ_CompressionLevel_Optimal5=9, // optimal parse level 5 (don't care about encode speed, maximum compression) OodleLZ_CompressionLevel_HyperFast1=-1, // faster than SuperFast, less compression OodleLZ_CompressionLevel_HyperFast2=-2, // faster than HyperFast1, less compression OodleLZ_CompressionLevel_HyperFast3=-3, // faster than HyperFast2, less compression OodleLZ_CompressionLevel_HyperFast4=-4, // fastest, less compression // aliases : OodleLZ_CompressionLevel_HyperFast=OodleLZ_CompressionLevel_HyperFast1, // alias hyperfast base level OodleLZ_CompressionLevel_Optimal = OodleLZ_CompressionLevel_Optimal2, // alias optimal standard level OodleLZ_CompressionLevel_Max = OodleLZ_CompressionLevel_Optimal5, // maximum compression level OodleLZ_CompressionLevel_Min = OodleLZ_CompressionLevel_HyperFast4, // fastest compression level OodleLZ_CompressionLevel_Force32 = 0x40000000, OodleLZ_CompressionLevel_Invalid = OodleLZ_CompressionLevel_Force32 } OodleLZ_CompressionLevel; /* Selection of compression encoder complexity Higher numerical value of CompressionLevel = slower compression, but smaller compressed data. The compressed stream is always decodable with the same decompressors. CompressionLevel controls the amount of work the encoder does to find the best compressed bit stream. CompressionLevel does not primary affect decode speed, it trades off encode speed for compressed bit stream quality. I recommend starting with OodleLZ_CompressionLevel_Normal, then try up or down if you want faster encoding or smaller output files. The Optimal levels are good for distribution when you compress rarely and decompress often; they provide very high compression ratios but are slow to encode. Optimal2 is the recommended level to start with of the optimal levels. Optimal4 and 5 are not recommended for common use, they are very slow and provide the maximum compression ratio, but the gain over Optimal3 is usually small. The HyperFast levels have negative numeric CompressionLevel values. They are faster than SuperFast for when you're encoder CPU time constrained or want something closer to symmetric compression vs. decompression time. The HyperFast levels are currently only available in Kraken, Mermaid & Selkie. Higher levels of HyperFast are faster to encode, eg. HyperFast4 is the fastest. The CompressionLevel does not affect decode speed much. Higher compression level does not mean slower to decode. To trade off decode speed vs ratio, use _spaceSpeedTradeoffBytes_ in $OodleLZ_CompressOptions */ OO_COMPILER_ASSERT( sizeof(OodleLZ_CompressionLevel) == 4 ); typedef enum OodleLZ_Jobify { OodleLZ_Jobify_Default=0, // Use compressor default for level of internal job usage OodleLZ_Jobify_Disable=1, // Don't use jobs at all OodleLZ_Jobify_Normal=2, // Try to balance parallelism with increased memory usage OodleLZ_Jobify_Aggressive=3, // Maximize parallelism even when doing so requires large amounts of memory OodleLZ_Jobify_Count=4, OodleLZ_Jobify_Force32 = 0x40000000, } OodleLZ_Jobify; /* Controls the amount of internal threading in $OodleLZ_Compress calls Once you install a pluggable job system via $OodleCore_Plugins_SetJobSystem, Oodle can internally break heavy-weight compression tasks into smaller jobs that can run in parallel. This can speed up compression of large blocks of data at Optimal1 and higher levels substantially. The trade-off is that running more jobs concurrently rather than sequentially can greatly increase memory requirements when there are multiple outstanding memory-intensive jobs. OodleLZ_Jobify_Default lets the compressor decide; typically compressors will default to "Normal" when a pluggable job system has been installed, and "Disable" otherwise. OodleLZ_Jobify_Disable disables use of internal jobs entirely; all compression work is done on the calling thread. This minimizes the amount of memory used, and is also appropriate when you're getting parallelism in other ways, e.g. by running OodleLZ_Compress on many threads yourself. OodleLZ_Jobify_Normal uses jobs to increase compressor parallelism and speeds up compression of large blocks of data, but avoids handing out many concurrent jobs for tasks that are memory-intensive. OodleLZ_Jobify_Aggressive will use concurrent jobs even for highly memory-intensive tasks. This can speed up things further, but at a potentially significant increase in the amount of memory used by Oodle. */ #define OODLELZ_LOCALDICTIONARYSIZE_MAX (1<<30) /* Maximum value of maxLocalDictionarySize in OodleLZ_CompressOptions */ #define OODLELZ_SPACESPEEDTRADEOFFBYTES_DEFAULT (256) /* Default value of spaceSpeedTradeoffBytes in OodleLZ_CompressOptions Changes how the encoder makes decisions in the bit stream Higher spaceSpeedTradeoffBytes favors decode speed more (larger compressed files) Lower spaceSpeedTradeoffBytes favors smaller compressed files (slower decoder) Goes in a power of 2 scale; so try 64,128 and 512,1024 (OODLELZ_SPACESPEEDTRADEOFFBYTES_DEFAULT/2) or (OODLELZ_SPACESPEEDTRADEOFFBYTES_DEFAULT*2) */ typedef OOSTRUCT OodleLZ_CompressOptions { OO_U32 unused_was_verbosity; // unused ; was verbosity (set to zero) OO_S32 minMatchLen; // minimum match length ; cannot be used to reduce a compressor's default MML, but can be higher. On some types of data, a large MML (6 or 8) is a space-speed win. OO_BOOL seekChunkReset; // whether chunks should be independent, for seeking and parallelism OO_S32 seekChunkLen; // length of independent seek chunks (if seekChunkReset) ; must be a power of 2 and >= $OODLELZ_BLOCK_LEN ; you can use $OodleLZ_MakeSeekChunkLen OodleLZ_Profile profile; // decoder profile to target (set to zero) OO_S32 dictionarySize; // sets a maximum offset for matches, if lower than the maximum the format supports. <= 0 means infinite (use whole buffer). Often power of 2 but doesn't have to be. OO_S32 spaceSpeedTradeoffBytes; // this is a number of bytes; I must gain at least this many bytes of compressed size to accept a speed-decreasing decision OO_S32 unused_was_maxHuffmansPerChunk; // unused ; was maxHuffmansPerChunk OO_BOOL sendQuantumCRCs; // should the encoder send a CRC of each compressed quantum, for integrity checks; this is necessary if you want to use OodleLZ_CheckCRC_Yes on decode OO_S32 maxLocalDictionarySize; // (Optimals) size of local dictionary before needing a long range matcher. This does not set a window size for the decoder; it's useful to limit memory use and time taken in the encoder. maxLocalDictionarySize must be a power of 2. Must be <= OODLELZ_LOCALDICTIONARYSIZE_MAX OO_BOOL makeLongRangeMatcher; // (Optimals) should the encoder find matches beyond maxLocalDictionarySize using an LRM OO_S32 matchTableSizeLog2; //(non-Optimals) when variable, sets the size of the match finder structure (often a hash table) ; use 0 for the compressor's default OodleLZ_Jobify jobify; // controls internal job usage by compressors void * jobifyUserPtr; // user pointer passed through to RunJob and WaitJob callbacks OO_S32 farMatchMinLen; // far matches must be at least this len OO_S32 farMatchOffsetLog2; // if not zero, the log2 of an offset that must meet farMatchMinLen OO_U32 reserved[4]; // reserved space for adding more options; zero these! } OodleLZ_CompressOptions; /* Options for the compressor Typically filled by calling $OodleLZ_CompressOptions_GetDefault , then individual options may be modified, like : OodleLZ_CompressOptions my_options = *OodleLZ_CompressOptions_GetDefault() To ensure you have set up the options correctly, call $OodleLZ_CompressOptions_Validate. _unused_was_verbosity_ : place holder, set to zero _minMatchLen_ : rarely useful. Default value of 0 means let the compressor decide. On some types of data, bumping this up to 4,6, or 8 can improve decode speed with little effect on compression ratio. Most of the Oodle compressors use a default MML of 4 at levels below 7, and MML 3 at levels >= 7. If you want to keep MML 4 at the higher levels, set _minMatchLen_ here to 4. _minMatchLen_ cannot be used to reduce the base MML of the compressor, only to increase it. _seekChunkReset_ must be true if you want the decode to be able to run "Wide", with pieces that can be decoded independently (not keeping previous pieces in memory for match references). _seekChunkLen_ : length of independent seek chunks (if seekChunkReset) ; must be a power of 2 and >= $OODLELZ_BLOCK_LEN ; you can use $OodleLZ_MakeSeekChunkLen _profile_ : tells the encoder to target alternate bitstream profile. Default value of zero for normal use. _dictionarySize_ : limits the encoder to partial buffer access for matches. Can be useful for decoding incrementally without keeping the entire output buffer in memory. _spaceSpeedTradeoffBytes_ is a way to trade off compression ratio for decode speed. If you make it smaller, you get more compression ratio and slower decodes. It's the number of bytes that a decision must save to be worth a slower decode. Default is 256 (OODLELZ_SPACESPEEDTRADEOFFBYTES_DEFAULT). So that means the encoder must be able to save >= 256 bytes to accept something that will slow down decoding (like adding another Huffman table). The typical range is 64-1024. Lower _spaceSpeedTradeoffBytes_ = more compression, slower decode Higher _spaceSpeedTradeoffBytes_ = less compression, faster decode _spaceSpeedTradeoffBytes_ is the primary parameter for controlling Hydra. The default value of 256 will make Hydra decodes that are just a little bit faster than Kraken. You get Kraken speeds around 200, and Mermaid speeds around 1200. At the extreme, a _spaceSpeedTradeoffBytes_ of zero would mean all you care about is compression ratio, not decode speed, you want the encoder to make the smallest possible output. (you cannot actually set zero, as zero values always mean "use default" in this struct; you never really want zero anyway) Generally _spaceSpeedTradeoffBytes_ below 16 provides diminishing gains in size with pointless decode speed loss. _spaceSpeedTradeoffBytes_ is on sort of powers of 2 scale, so you might want to experiment with 32,64,128,256,512 _spaceSpeedTradeoffBytes_ outside the range [16 - 2048] is not recommended. _unused_was_maxHuffmansPerChunk_ : place holder, set to zero _sendQuantumCRCs_ : send hashes of the compressed data to verify in the decoder; not recommended, if you need data verification, use your own system outside of Oodle. DEPRECATED, not recommended. For backwards compatibility only. _maxLocalDictionarySize_ : only applies to optimal parsers at level >= Optimal2. This limits the encoder memory use. Making it larger = more compression, higher memory use. Matches within maxLocalDictionarySize are found exactly, outside the maxLocalDictionarySize window an approximate long range matcher is used. _makeLongRangeMatcher_ : whether an LRM should be used to find matches outside the _maxLocalDictionarySize_ window (Optimal levels only) _matchTableSizeLog2_ : for non-optimal levels (level <= Normal), controls the hash table size. Making this very small can sometimes boost encoder speed. For the very fastest encoding, use the SuperFast level and change _matchTableSizeLog2_ to 12 or 13. _matchTableSizeLog2_ should usually be left zero to use the encoder's default _matchTableSizeLog2_ allows you to limit memory use of the non-Optimal encoder levels. Memory use is roughly ( 1 MB + 4 << matchTableSizeLog2 ) _jobify_ tells compressors how to use internal jobs for compression tasks. Jobs can be run in parallel using the job system plugins set with $OodleCore_Plugins_SetJobSystem. Not all compressors or compression level support jobs, but the slower ones generally do. The default value of jobify is to use a thread system if one is installed. _farMatchMinLen_ and _farMatchOffsetLog2_ can be used to tune the encoded stream for a known cache size on the decoding hardware. If set, then offsets with log2 greater or each to _farMatchOffsetLog2_ must have a minimum length of _farMatchMinLen_. For example to target a machine with a 2 MB cache, set _farMatchOffsetLog2_ to 21, and _farMatchMinLen_ to something large, like 16 or 20. Without _farMatchMinLen_ and _farMatchOffsetLog2_ set, the Oodle encoders tune for a blend of cache sizes that works well on most machines. _dictionarySize_ can also be used to tune for cache size, but cuts off all matches beyond a certain distance. That may be more appropriate when you don't want to go out of cache at all. _farMatchMinLen_ can only be used to make the standard blend target more restrictive; it can reduce the target cache size but can't make it larger (or it can raise min match len outside cache but can't make it shorter). For help on setting up OodleLZ_CompressOptions contact support at oodle@radgametools.com NOTE : fields you do not set should always be zero initialized. In particular the _reserved_ fields should be zeroed. Zero always means "use default" and is a future-portable initialization value. If you set fields to zero to mean "use default" you can call $OodleLZ_CompressOptions_Validate to change them to default values. This is done automatically internally if you don't do it explicitly. */ typedef enum OodleLZ_Decode_ThreadPhase { OodleLZ_Decode_ThreadPhase1 = 1, OodleLZ_Decode_ThreadPhase2 = 2, OodleLZ_Decode_ThreadPhaseAll = 3, OodleLZ_Decode_Unthreaded = OodleLZ_Decode_ThreadPhaseAll } OodleLZ_Decode_ThreadPhase; /* ThreadPhase for threaded Oodle decode Check $OodleLZ_Compressor_CanDecodeThreadPhased (currently only used by Kraken) See $OodleLZ_About_ThreadPhasedDecode */ typedef enum OodleLZ_FuzzSafe { OodleLZ_FuzzSafe_No = 0, OodleLZ_FuzzSafe_Yes = 1 } OodleLZ_FuzzSafe; /* OodleLZ_FuzzSafe (deprecated) About fuzz safety: Fuzz Safe decodes will not crash on corrupt data. They may or may not return failure, and produce garbage output. Fuzz safe decodes will not read out of bounds. They won't put data on the stack or previously in memory into the output buffer. As of Oodle 2.9.0 all compressors supported are fuzzsafe, so OodleLZ_FuzzSafe_Yes should always be used and this enum is deprecated. */ #define OODLELZ_BLOCK_LEN (1<<18) /* The number of raw bytes per "seek chunk" Seek chunks can be decompressed independently if $(OodleLZ_CompressOptions:seekChunkReset) is set. */ #define OODLELZ_BLOCK_MAXIMUM_EXPANSION (2) #define OODLELZ_BLOCK_MAX_COMPLEN (OODLELZ_BLOCK_LEN+OODLELZ_BLOCK_MAXIMUM_EXPANSION) /* Maximum expansion per $OODLELZ_BLOCK_LEN is 1 byte. Note that the compressed buffer must be allocated bigger than this (use $OodleLZ_GetCompressedBufferSizeNeeded) */ #define OODLELZ_QUANTUM_LEN (1<<14) /* Minimum decompression quantum (for old legacy codecs only) Deprecated. The new sea monster family of compressors use a whole block quantum (OODLELZ_BLOCK_LEN). Check $OodleLZ_Compressor_UsesWholeBlockQuantum */ // 5 byte expansion per-quantum with CRC's #define OODLELZ_QUANTUM_MAXIMUM_EXPANSION (5) #define OODLELZ_QUANTUM_MAX_COMPLEN (OODLELZ_QUANTUM_LEN+OODLELZ_QUANTUM_MAXIMUM_EXPANSION) #define OODLELZ_SEEKCHUNKLEN_MIN OODLELZ_BLOCK_LEN #define OODLELZ_SEEKCHUNKLEN_MAX (1<<29) // half GB typedef OOSTRUCT OodleLZ_DecodeSome_Out { OO_S32 decodedCount; // number of uncompressed bytes decoded OO_S32 compBufUsed; // number of compressed bytes consumed OO_S32 curQuantumRawLen; // tells you the current quantum size. you must have at least this much room available in the output buffer to be able to decode anything. OO_S32 curQuantumCompLen; // if you didn't pass in enough data, nothing will decode (decodedCount will be 0), and this will tell you how much is needed } OodleLZ_DecodeSome_Out; /* Output value of $OodleLZDecoder_DecodeSome */ //--------------------------------------------- //======================================================= typedef OOSTRUCT OodleLZ_SeekTable { OodleLZ_Compressor compressor; // which compressor was used OO_BOOL seekChunksIndependent; // are the seek chunks independent, or must they be decompressed in sequence OO_S64 totalRawLen; // total uncompressed data lenth OO_S64 totalCompLen; // sum of seekChunkCompLens OO_S32 numSeekChunks; // derived from rawLen & seekChunkLen OO_S32 seekChunkLen; // multiple of OODLELZ_BLOCK_LEN OO_U32 * seekChunkCompLens; // array of compressed lengths of seek chunks OO_U32 * rawCRCs; // crc of the raw bytes of the chunk (optional; NULL unless $OodleLZSeekTable_Flags_MakeRawCRCs was specified) } OodleLZ_SeekTable; typedef enum OodleLZSeekTable_Flags { OodleLZSeekTable_Flags_None = 0, // default OodleLZSeekTable_Flags_MakeRawCRCs = 1, // make the _rawCRCs_ member of $OodleLZ_SeekTable OodleLZSeekTable_Flags_Force32 = 0x40000000 } OodleLZSeekTable_Flags; //===================================================== typedef OOSTRUCT OodleConfigValues { OO_S32 m_OodleLZ_LW_LRM_step; // LZHLW LRM : bytes between LRM entries OO_S32 m_OodleLZ_LW_LRM_hashLength; // LZHLW LRM : bytes hashed for each LRM entries OO_S32 m_OodleLZ_LW_LRM_jumpbits; // LZHLW LRM : bits of hash used for jump table OO_S32 m_OodleLZ_Decoder_Max_Stack_Size; // if OodleLZ_Decompress needs to allocator a Decoder object, and it's smaller than this size, it's put on the stack instead of the heap OO_S32 m_OodleLZ_Small_Buffer_LZ_Fallback_Size_Unused; // deprecated OO_S32 m_OodleLZ_BackwardsCompatible_MajorVersion; // if you need to encode streams that can be read with an older version of Oodle, set this to the Oodle2 MAJOR version number that you need compatibility with. eg to be compatible with oodle 2.7.3 you would put 7 here OO_U32 m_oodle_header_version; // = OODLE_HEADER_VERSION } OodleConfigValues; /* OodleConfigValues Struct of user-settable low level config values. See $Oodle_SetConfigValues. May have different defaults per platform. */ OOFUNC1 void OOFUNC2 Oodle_GetConfigValues(OodleConfigValues * ptr); /* Get $OodleConfigValues $:ptr filled with OodleConfigValues Gets the current $OodleConfigValues. May be different per platform. */ OOFUNC1 void OOFUNC2 Oodle_SetConfigValues(const OodleConfigValues * ptr); /* Set $OodleConfigValues $:ptr your desired OodleConfigValues Sets the global $OodleConfigValues from your struct. You should call $Oodle_GetConfigValues to fill the struct, then change the values you want to change, then call $Oodle_SetConfigValues. This should generally be done before doing anything with Oodle (eg. even before OodleX_Init). Changing OodleConfigValues after Oodle has started has undefined effects. */ typedef enum Oodle_UsageWarnings { Oodle_UsageWarnings_Enabled = 0, Oodle_UsageWarnings_Disabled = 1, Oodle_UsageWarnings_Force32 = 0x40000000 } Oodle_UsageWarnings; /* Whether Oodle usage warnings are enable or disabled. */ OOFUNC1 void OOFUNC2 Oodle_SetUsageWarnings(Oodle_UsageWarnings state); /* Enables or disables Oodle usage warnings. $:state whether usage warnings should be enabled or disabled. Usage warnings are enabled by default and try to be low-noise, but in case you want to disable them, this is how. This should generally be done once at startup. Setting this state while there are Oodle calls running on other threads has undefined results. */ // function pointers to mallocs needed : OODEFFUNC typedef void * (OODLE_CALLBACK t_fp_OodleCore_Plugin_MallocAligned)( OO_SINTa bytes, OO_S32 alignment); /* Function pointer type for OodleMallocAligned $:bytes number of bytes to allocate $:alignment required alignment of returned pointer $:return pointer to memory allocated (must not be NULL) _alignment_ will always be a power of two _alignment_ will always be >= $OODLE_MALLOC_MINIMUM_ALIGNMENT */ OODEFFUNC typedef void (OODLE_CALLBACK t_fp_OodleCore_Plugin_Free)( void * ptr ); /* Function pointer type for OodleFree $:return pointer to memory to free */ OOFUNC1 void OOFUNC2 OodleCore_Plugins_SetAllocators( t_fp_OodleCore_Plugin_MallocAligned * fp_OodleMallocAligned, t_fp_OodleCore_Plugin_Free * fp_OodleFree); /* Set the function pointers for allocation needed by Oodle2 Core If these are not set, the default implementation on most platforms uses the C stdlib. On Microsoft platforms the default implementation uses HeapAlloc. These must not be changed once they are set! Set them once then don't change them. NOTE: if you are using Oodle Ext, do NOT call this. OodleX_Init will install an allocator for Oodle Core. Do not mix your own allocator with the OodleX allocator. See $OodleXAPI_Malloc. If you want to ensure that Oodle is not doing any allocations, you can call OodleCore_Plugins_SetAllocators(NULL,NULL); If you do that, then any time Oodle needs to allocate memory internally, it will stop the process. It is STRONGLY not recommended that you ship that way. You can verify that Oodle is not allocating, but then leave some fallback allocator installed when you actually ship just in case. Also note that on many consoles the standard allocation practices may not leave much heap memory for the C stdlib malloc. In this case Oodle may fail to allocate. */ OODEFFUNC typedef OO_U64 (OODLE_CALLBACK t_fp_OodleCore_Plugin_RunJob)( t_fp_Oodle_Job * fp_job, void * job_data , OO_U64 * dependencies, int num_dependencies, void * user_ptr ); /* Function pointer type for OodleCore_Plugins_SetJobSystem $:dependencies array of handles of other pending jobs. All guaranteed to be nonzero. $:num_dependencies number of dependencies. Guaranteed to be no more than OODLE_JOB_MAX_DEPENDENCIES. $:user_ptr is passed through from the OodleLZ_CompressOptions. $:return handle to the async job, or 0 if it was run synchronously RunJob will call fp_job(job_data) it may be done on a thread, or it may run the function synchronously and return 0, indicating the job is already done. The returned OO_U64 is a handle passed to WaitJob, unless it is 0, in which case WaitJob won't get called. fp_job should not run until all the dependencies are done. This function should not delete the dependencies. RunJob must be callable from within an Oodle Job, i.e. jobs may spawn their own sub-jobs directly. However, the matching WaitJob calls will only ever occur on the thread that called the internally threaded Oodle API function. See $Oodle_About_Job_Threading_Plugins */ OODEFFUNC typedef void (OODLE_CALLBACK t_fp_OodleCore_Plugin_WaitJob)( OO_U64 job_handle, void * user_ptr ); /* Function pointer type for OodleCore_Plugins_SetJobSystem $:job_handle a job handle returned from RunJob. Never 0. $:user_ptr is passed through from the OodleLZ_CompressOptions. Waits until the job specified by job_handle is done and cleans up any associated resources. Oodle will call WaitJob exactly once for every RunJob call that didn't return 0. If job_handle was already completed, this should clean it up without waiting. A handle value should not be reused by another RunJob until WaitJob has been done with that value. WaitJob will not be called from running jobs. It will be only be called from the original thread that invoked Oodle. If you are running Oodle from a worker thread, ensure that that thread is allowed to wait on other job threads. See $Oodle_About_Job_Threading_Plugins */ OOFUNC1 void OOFUNC2 OodleCore_Plugins_SetJobSystem( t_fp_OodleCore_Plugin_RunJob * fp_RunJob, t_fp_OodleCore_Plugin_WaitJob * fp_WaitJob); /* DEPRECATED use OodleCore_Plugins_SetJobSystemAndCount instead See $OodleCore_Plugins_SetJobSystemAndCount */ OOFUNC1 void OOFUNC2 OodleCore_Plugins_SetJobSystemAndCount( t_fp_OodleCore_Plugin_RunJob * fp_RunJob, t_fp_OodleCore_Plugin_WaitJob * fp_WaitJob, int target_parallelism); /* Set the function pointers for async job system needed by Oodle2 Core $:fp_RunJob pointer to RunJob function $:fp_WaitJob pointer to WaitJob function $:target_parallelism goal of number of jobs to run simultaneously If these are not set, the default implementation runs jobs synchronously on the calling thread. These must not be changed once they are set! Set them once then don't change them. _target_parallelism_ allows you to tell Oodle how many Jobs it should try to keep in flight at once. Depending on the operation it may not be able to split work into this many jobs (so fewer will be used), but it will not exceed this count. For Oodle Data LZ work, typically _target_parallelism_ is usually best at the number of hardware cores not including hyper threads). For Oodle Texture BCN encoding work, _target_parallelism_ is usually best as the full number of hyper cores. In some cases you may wish to reduce _target_parallelism_ by 1 or 2 cores to leave some of the CPU free for other work. For example on a CPU with 16 cores and 32 hardware threads, for LZ work you might set _target_parallelism_ to 15 when calling OodleCorePlugins. For BC7 encoding you might set _target_parallelism_ to 30 when calling OodleTexPlugins. NOTE : if you are using Oodle Ext, do NOT call this. OodleX_Init will install a job system for Oodle Core. Note OodleX only installs automatically to Oodle Core, not Net or Tex. See example_jobify.cpp for manual plugin. Replaces deprecated $OodleCore_Plugins_SetJobSystem See $Oodle_About_Job_Threading_Plugins */ // the main func pointer for log : OODEFFUNC typedef void (OODLE_CALLBACK t_fp_OodleCore_Plugin_Printf)(int verboseLevel,const char * file,int line,const char * fmt,...); /* Function pointer to Oodle Core printf $:verboseLevel verbosity of the message; 0-2 ; lower = more important $:file C file that sent the message $:line C line that sent the message $:fmt vararg printf format string The logging function installed here must parse varargs like printf. _verboseLevel_ may be used to omit verbose messages. */ OOFUNC1 t_fp_OodleCore_Plugin_Printf * OOFUNC2 OodleCore_Plugins_SetPrintf(t_fp_OodleCore_Plugin_Printf * fp_rrRawPrintf); /* Install the callback used by Oodle Core for logging $:fp_rrRawPrintf function pointer to your log function; may be NULL to disable all logging $:return returns the previous function pointer Use this function to install your own printf for Oodle Core. The default implementation in debug builds, if you install nothing, uses the C stdio printf for logging. On Microsoft platforms, it uses OutputDebugString and not stdio. To disable all logging, call OodleCore_Plugins_SetPrintf(NULL) WARNING : this function is NOT thread safe! It should be done only once and done in a place where the caller can guarantee thread safety. In the debug build of Oodle, you can install OodleCore_Plugin_Printf_Verbose to get more verbose logging */ OODEFFUNC typedef OO_BOOL (OODLE_CALLBACK t_fp_OodleCore_Plugin_DisplayAssertion)(const char * file,const int line,const char * function,const char * message); /* Function pointer to Oodle Core assert callback $:file C file that triggered the assert $:line C line that triggered the assert $:function C function that triggered the assert (may be NULL) $:message assert message $:return true to break execution at the assertion site, false to continue This callback is called by Oodle Core when it detects an assertion condition. This will only happen in debug builds. */ OOFUNC1 t_fp_OodleCore_Plugin_DisplayAssertion * OOFUNC2 OodleCore_Plugins_SetAssertion(t_fp_OodleCore_Plugin_DisplayAssertion * fp_rrDisplayAssertion); /* Install the callback used by Oodle Core for asserts $:fp_rrDisplayAssertion function pointer to your assert display function $:return returns the previous function pointer Use this function to install your own display for Oodle Core assertions. This will only happen in debug builds. The default implementation in debug builds, if you install nothing, uses the C stderr printf for logging, except on Microsoft platforms where it uses OutputDebugString. WARNING : this function is NOT thread safe! It should be done only once and done in a place where the caller can guarantee thread safety. */ //============================================================= OOFUNC1 void * OOFUNC2 OodleCore_Plugin_MallocAligned_Default(OO_SINTa size,OO_S32 alignment); OOFUNC1 void OOFUNC2 OodleCore_Plugin_Free_Default(void * ptr); OOFUNC1 void OOFUNC2 OodleCore_Plugin_Printf_Default(int verboseLevel,const char * file,int line,const char * fmt,...); OOFUNC1 void OOFUNC2 OodleCore_Plugin_Printf_Verbose(int verboseLevel,const char * file,int line,const char * fmt,...); OOFUNC1 OO_BOOL OOFUNC2 OodleCore_Plugin_DisplayAssertion_Default(const char * file,const int line,const char * function,const char * message); OOFUNC1 OO_U64 OOFUNC2 OodleCore_Plugin_RunJob_Default( t_fp_Oodle_Job * fp_job, void * job_data, OO_U64 * dependencies, int num_dependencies, void * user_ptr ); OOFUNC1 void OOFUNC2 OodleCore_Plugin_WaitJob_Default( OO_U64 job_handle, void * user_ptr ); //============================================================= //---------------------------------------------- // OodleLZ #define OODLELZ_FAILED (0) /* Return value of OodleLZ_Decompress on failure */ //======================================================= OOFUNC1 OO_SINTa OOFUNC2 OodleLZ_Compress(OodleLZ_Compressor compressor, const void * rawBuf,OO_SINTa rawLen,void * compBuf, OodleLZ_CompressionLevel level, const OodleLZ_CompressOptions * pOptions OODEFAULT(NULL), const void * dictionaryBase OODEFAULT(NULL), const void * lrm OODEFAULT(NULL), void * scratchMem OODEFAULT(NULL), OO_SINTa scratchSize OODEFAULT(0) ); /* Compress some data from memory to memory, synchronously, with OodleLZ $:compressor which OodleLZ variant to use in compression $:rawBuf raw data to compress $:rawLen number of bytes in rawBuf to compress $:compBuf pointer to write compressed data to. MUST be at least $OodleLZ_GetCompressedBufferSizeNeeded bytes $:level OodleLZ_CompressionLevel controls how much CPU effort is put into maximizing compression $:pOptions (optional) options; if NULL, $OodleLZ_CompressOptions_GetDefault is used $:dictionaryBase (optional) if not NULL, provides preceding data to prime the dictionary; must be contiguous with rawBuf, the data between the pointers _dictionaryBase_ and _rawBuf_ is used as the preconditioning data. The exact same precondition must be passed to encoder and decoder. $:lrm (optional) long range matcher $:scratchMem (optional) pointer to scratch memory $:scratchSize (optional) size of scratch memory (see $OodleLZ_GetCompressScratchMemBound) $:return size of compressed data written, or $OODLELZ_FAILED for failure Performs synchronous memory to memory LZ compression. In tools and when compressing large inputs in one call, consider using $OodleXLZ_Compress_AsyncAndWait (in the Oodle2 Ext lib) instead to get parallelism. Alternatively, chop the data into small fixed size chunks (we recommend at least 256KiB, i.e. 262144 bytes) and call compress on each of them, which decreases compression ratio but makes for trivial parallel compression and decompression. You can compress a large buffer in several calls by setting _dictionaryBase_ to the start of the buffer, and then making _rawBuf_ and _rawLen_ select portions of that buffer. As long as _rawLen_ is a multiple of $OODLELZ_BLOCK_LEN, the compressed chunks can simply be concatenated together. The buffer that _compBuf_ points to must have a certain minimum size that is returned by $OodleLZ_GetCompressedBufferSizeNeeded. This size is always more than _rawLen_, usually by a few bytes for every 256kb of input data. The "compressed" data can end up slightly larger than the input due to internal stream headers. If _scratchMem_ is provided, it will be used for the compressor's scratch memory needs before OodleMalloc is called. If the scratch is big enough, no malloc will be done. If the scratch is not big enough, the compress will not fail, instead OodleMalloc will be used. OodleMalloc should not return null. There is currently no way to make compress fail cleanly due to using too much memory, it must either succeed or abort the process. If _scratchSize_ is at least $OodleLZ_GetCompressScratchMemBound , additional allocations will not be needed. See $OodleLZ_About for tips on setting the compression options. If _dictionaryBase_ is provided, the backup distance from _rawBuf_ must be a multiple of $OODLELZ_BLOCK_LEN If $(OodleLZ_CompressOptions:seekChunkReset) is enabled, and _dictionaryBase_ is not NULL or _rawBuf_ , then the seek chunk boundaries are relative to _dictionaryBase_, not to _rawBuf_. */ // Decompress returns raw (decompressed) len received // Decompress returns 0 (OODLELZ_FAILED) if it detects corruption OOFUNC1 OO_SINTa OOFUNC2 OodleLZ_Decompress(const void * compBuf,OO_SINTa compBufSize,void * rawBuf,OO_SINTa rawLen, OodleLZ_FuzzSafe fuzzSafe OODEFAULT(OodleLZ_FuzzSafe_Yes), OodleLZ_CheckCRC checkCRC OODEFAULT(OodleLZ_CheckCRC_No), OodleLZ_Verbosity verbosity OODEFAULT(OodleLZ_Verbosity_None), void * decBufBase OODEFAULT(NULL), OO_SINTa decBufSize OODEFAULT(0), OodleDecompressCallback * fpCallback OODEFAULT(NULL), void * callbackUserData OODEFAULT(NULL), void * decoderMemory OODEFAULT(NULL), OO_SINTa decoderMemorySize OODEFAULT(0), OodleLZ_Decode_ThreadPhase threadPhase OODEFAULT(OodleLZ_Decode_Unthreaded) ); /* Decompress a some data from memory to memory, synchronously. $:compBuf pointer to compressed data $:compBufSize number of compressed bytes available (must be greater or equal to the number consumed) $:rawBuf pointer to output uncompressed data into $:rawLen number of uncompressed bytes to output $:fuzzSafe (optional) should the decode fail if it contains non-fuzz safe codecs? $:checkCRC (optional) if data could be corrupted and you want to know about it, pass OodleLZ_CheckCRC_Yes $:verbosity (optional) if not OodleLZ_Verbosity_None, logs some info $:decBufBase (optional) if not NULL, provides preceding data to prime the dictionary; must be contiguous with rawBuf, the data between the pointers _dictionaryBase_ and _rawBuf_ is used as the preconditioning data. The exact same precondition must be passed to encoder and decoder. The decBufBase must be a reset point. $:decBufSize (optional) size of decode buffer starting at decBufBase, if 0, _rawLen_ is assumed $:fpCallback (optional) OodleDecompressCallback to call incrementally as decode proceeds $:callbackUserData (optional) passed as userData to fpCallback $:decoderMemory (optional) pre-allocated memory for the Decoder, of size _decoderMemorySize_ $:decoderMemorySize (optional) size of the buffer at _decoderMemory_; must be at least $OodleLZDecoder_MemorySizeNeeded bytes to be used $:threadPhase (optional) for threaded decode; see $OodleLZ_About_ThreadPhasedDecode (default OodleLZ_Decode_Unthreaded) $:return the number of decompressed bytes output, $OODLELZ_FAILED (0) if none can be decompressed Decodes data encoded with any $OodleLZ_Compressor. Note : _rawLen_ must be the actual number of bytes to output, the same as the number that were encoded with the corresponding OodleLZ_Compress size. You must store this somewhere in your own header and pass it in to this call. _compBufSize_ does NOT need to be the exact number of compressed bytes, is the number of bytes available in the buffer, it must be greater or equal to the actual compressed length. Note that the new compressors (Kraken,Mermaid,Selkie,BitKnit) are all fuzz safe and you can use OodleLZ_FuzzSafe_Yes with them and no padding of the decode target buffer. If checkCRC is OodleLZ_CheckCRC_Yes, then corrupt data will be detected and the decode aborted. If checkCRC is OodleLZ_CheckCRC_No, then corruption might result in invalid data, but no detection of any error (garbage in, garbage out). If corruption is possible, _fuzzSafe_ is No and _checkCRC_ is OodleLZ_CheckCRC_No, $OodleLZ_GetDecodeBufferSize must be used to allocate _rawBuf_ large enough to prevent overrun. $OodleLZ_GetDecodeBufferSize should always be used to ensure _rawBuf_ is large enough, even when corruption is not possible (when fuzzSafe is No). _compBuf_ and _rawBuf_ are allowed to overlap for "in place" decoding, but then _rawBuf_ must be allocated to the size given by $OodleLZ_GetInPlaceDecodeBufferSize , and the compressed data must be at the end of that buffer. An easy way to take the next step to parallel decoding is with $OodleXLZ_Decompress_MakeSeekTable_Wide_Async (in the Oodle2 Ext lib) NOTE : the return value is the *total* number of decompressed bytes output so far. If rawBuf is > decBufBase, that means the initial inset of (rawBuf - decBufBase) is included! (eg. you won't just get _rawLen_) If _decBufBase_ is provided, the backup distance from _rawBuf_ must be a multiple of $OODLELZ_BLOCK_LEN About fuzz safety: OodleLZ_Decompress is guaranteed not to crash even if the data is corrupted when _fuzzSafe_ is set to OodleLZ_FuzzSafe_Yes. When _fuzzSafe_ is Yes, the target buffer (_rawBuf_ and _rawLen_) will never be overrun. Note that corrupted data might not be detected (the return value might indicate success). Fuzz Safe decodes will not crash on corrupt data. They may or may not return failure, and produce garbage output. Fuzz safe decodes will not read out of bounds. They won't put data on the stack or previously in memory into the output buffer. Fuzz safe decodes will not output more than the uncompressed size. (eg. the output buffer does not need to be padded like OodleLZ_GetDecodeBufferSize) If you ask for a fuzz safe decode and the compressor doesn't satisfy OodleLZ_Compressor_CanDecodeFuzzSafe then it will return failure. The _fuzzSafe_ argument should always be OodleLZ_FuzzSafe_Yes as of Oodle 2.9.0 ; older compressors did not support fuzz safety but they now all do. Use of OodleLZ_FuzzSafe_No is deprecated. */ //------------------------------------------- // Incremental Decoder functions : struct _OodleLZDecoder; typedef struct _OodleLZDecoder OodleLZDecoder; /* Opaque type for OodleLZDecoder See $OodleLZDecoder_Create */ OOFUNC1 OodleLZDecoder * OOFUNC2 OodleLZDecoder_Create(OodleLZ_Compressor compressor,OO_S64 rawLen,void * memory, OO_SINTa memorySize); /* Create a OodleLZDecoder $:compressor the type of data you will decode; use $OodleLZ_Compressor_Invalid if unknown $:rawLen total raw bytes of the decode (or <= 0 for any/unknown, but Reset for each buffer) $:memory (optional) provide memory for the OodleLZDecoder object (not the window) $:memorySize (optional) if memory is provided, this is its size in bytes $:return the OodleLZDecoder If memory is provided, it must be of size $OodleLZDecoder_MemorySizeNeeded. If it is NULL it will be allocated with the malloc specified by $OodleAPI_OodleCore_Plugins. Free with $OodleLZDecoder_Destroy. You should Destroy even if you passed in the memory. Providing _compressor_ lets the OodleLZDecoder be the minimum size needed for that type of data. If you pass $OodleLZ_Compressor_Invalid, then any type of data may be decoded, and the Decoder is allocated large enought to handle any of them. If you are going to pass _rawLen_ to OodleLZDecoder_Reset , then you can pass 0 to _rawLen_ here. To make a Decoder to use with many buffer sizes, pass either <= 0 (for infinite) or the largest buffer size you can see. Then call Reset() with the correct buffer size before starting to decode each buffer. See $OodleLZDecoder_DecodeSome for more. */ OOFUNC1 OO_S32 OOFUNC2 OodleLZDecoder_MemorySizeNeeded(OodleLZ_Compressor compressor OODEFAULT(OodleLZ_Compressor_Invalid), OO_SINTa rawLen OODEFAULT(-1)); /* If you want to provide the memory needed by $OodleLZDecoder_Create , this tells you how big it must be. $:compressor the type of data you will decode; use $OodleLZ_Compressor_Invalid if unknown $:rawLen should almost always be -1, which supports any size of raw data decompression $:return bytes to allocate or reserve, 0 for failure NOTE : using $OodleLZ_Compressor_Invalid lets you decode any time of compressed data. It requests as much memory as the largest compressor. This may be a *lot* more than your data needs; try to use the correct compressor type. If _rawLen_ is -1 (default) then the Decoder object created can be used on any length of raw data decompression. If _rawLen_ is specified here, then you can only use it to decode data shorter than the length you specified here. This use case is very rare, contact support for details. */ OOFUNC1 OO_S32 OOFUNC2 OodleLZ_ThreadPhased_BlockDecoderMemorySizeNeeded(void); /* Returns the size of the decoder needed for ThreadPhased decode For use with $OodleLZ_Decode_ThreadPhase See $OodleLZ_About_ThreadPhasedDecode */ OOFUNC1 void OOFUNC2 OodleLZDecoder_Destroy(OodleLZDecoder * decoder); /* Pairs with $OodleLZDecoder_Create You should always call Destroy even if you provided the memory for $OodleLZDecoder_Create */ // Reset decoder - can reset to the start of any OODLELZ_BLOCK_LEN chunk OOFUNC1 OO_BOOL OOFUNC2 OodleLZDecoder_Reset(OodleLZDecoder * decoder, OO_SINTa decPos, OO_SINTa decLen OODEFAULT(0)); /* Reset an OodleLZDecoder to restart at given pos $:decoder the OodleLZDecoder, made by $OodleLZDecoder_Create $:decPos position to reset to; must be a multiple of OODLELZ_BLOCK_LEN $:decLen (optional) if not zero, change the length of the data we expect to decode $:return true for success If you are seeking in a packed stream, you must seek to a seek chunk reset point, as was made at compress time. That is, $(OodleLZ_CompressOptions:seekChunkReset) must have been true, and _decPos_ must be a multiple of $(OodleLZ_CompressOptions:seekChunkLen) that was used at compress time. You can use $OodleLZ_GetChunkCompressor to verify that you are at a valid independent chunk start point. */ // returns false if corruption detected OOFUNC1 OO_BOOL OOFUNC2 OodleLZDecoder_DecodeSome( OodleLZDecoder * decoder, OodleLZ_DecodeSome_Out * out, // the decode sliding window : we output here & read from this for matches void * decBuf, OO_SINTa decBufPos, OO_SINTa decBufferSize, // decBufferSize should be the result of OodleLZDecoder_MakeDecodeBufferSize() OO_SINTa decBufAvail, // usually Size - Pos, but maybe less if you have pending IO flushes // compressed data : const void * compPtr, OO_SINTa compAvail, OodleLZ_FuzzSafe fuzzSafe OODEFAULT(OodleLZ_FuzzSafe_No), OodleLZ_CheckCRC checkCRC OODEFAULT(OodleLZ_CheckCRC_No), OodleLZ_Verbosity verbosity OODEFAULT(OodleLZ_Verbosity_None), OodleLZ_Decode_ThreadPhase threadPhase OODEFAULT(OodleLZ_Decode_Unthreaded) ); /* Incremental decode some LZ compressed data $:decoder the OodleLZDecoder, made by $OodleLZDecoder_Create $:out filled with results $:decBuf the decode buffer (window) $:decBufPos the current position in the buffer $:decBufferSize size of decBuf ; this must be either equal to the total decompressed size (_rawLen_ passed to $OodleLZDecoder_Create) or the result of $OodleLZDecoder_MakeValidCircularWindowSize $:decBufAvail the number of bytes available after decBufPos in decBuf ; usually (decBufferSize - decBufPos), but can be less $:compPtr pointer to compressed data to read $:compAvail number of compressed bytes available at compPtr $:fuzzSafe (optional) should the decode be fuzz safe $:checkCRC (optional) if data could be corrupted and you want to know about it, pass OodleLZ_CheckCRC_Yes $:verbosity (optional) if not OodleLZ_Verbosity_None, logs some info $:threadPhase (optional) for threaded decode; see $OodleLZ_About_ThreadPhasedDecode (default OodleLZ_Decode_Unthreaded) $:return true if success, false if invalid arguments or data is encountered Decodes data encoded with an OodleLZ compressor. Decodes an integer number of quanta; quanta are $OODLELZ_QUANTUM_LEN uncompressed bytes. _decBuf_ can either be a circular window or the whole _rawLen_ array. In either case, _decBufPos_ should be in the range [0,_decBufferSize_). If _decBuf_ is a circular window, then _decBufferSize_ should come from $OodleLZDecoder_MakeValidCircularWindowSize. (circular windows are deprecated as of 2.9.0) NOTE : all the new LZ codecs (Kraken, etc.) do not do circular windows. They can do sliding windows, see lz_test_11 in $example_lz. They should always have decBufferSize = total raw size, even if the decode buffer is smaller than that. NOTE : insufficient data provided (with _compAvail_ > 0 but not enough to decode a quantum) is a *success* case (return value of true), even though nothing is decoded. A return of false always indicates a non-recoverable error. If _decBufAvail_ or _compAvail_ is insufficient for any decompression, the "curQuantum" fields of $OodleLZ_DecodeSome_Out will tell you how much you must provide to proceed. That is, if enough compressed bytes are provided to get a quantum header, but not enough to decode a quantum, this function returns true and fills out the $OodleLZ_DecodeSome_Out structure with the size of the quantum. See $OodleLZ_Decompress about fuzz safety. NOTE : DecodeSome expect to decode either one full quantum (of len $OODLELZ_QUANTUM_LEN) or up to the length of the total buffer specified in the call to $OodleLZDecoder_Create or $OodleLZDecoder_Reset. That total buffer length must match what was use during compression (or be a seek-chunk portion thereof). That is, you cannot decompress partial streams in intervals smaller than $OODLELZ_QUANTUM_LEN except for the final partial quantum at the end of the stream. */ // pass in how much you want to alloc and it will tell you a valid size as close that as possible // the main use is just to call OodleLZDecoder_MakeDecodeBufferSize(0) to get the min size; the min size is a good size OOFUNC1 OO_S32 OOFUNC2 OodleLZDecoder_MakeValidCircularWindowSize(OodleLZ_Compressor compressor,OO_S32 minWindowSize OODEFAULT(0)); /* Get a valid "Window" size for an LZ $:compressor which compressor you will be decoding $:minWindowSize (optional) minimum size of the window NOTE: circular windows are deprecated as of 2.9.0 Most common usage is OodleLZDecoder_MakeValidCircularWindowSize(0) to get the minimum window size. Only compressors which pass $OodleLZ_Compressor_CanDecodeInCircularWindow can be decoded in a circular window. WARNING : this is NOT the size to malloc the window! you need to call $OodleLZ_GetDecodeBufferSize() and pass in the window size to get the malloc size. */ //======================================================= //======================================================= // remember if you want to IO the SeekEntries you need to make them endian-independent // see WriteOOZHeader for example #define OODLELZ_SEEKPOINTCOUNT_DEFAULT 16 OOFUNC1 OO_S32 OOFUNC2 OodleLZ_MakeSeekChunkLen(OO_S64 rawLen, OO_S32 desiredSeekPointCount); /* Compute a valid seekChunkLen $:rawLen total length of uncompressed data $:desiredSeekPointCount desired number of seek chunks $:return a valid seekChunkLen for use in $OodleLZ_CreateSeekTable Returns a seekChunkLen which is close to (rawLen/desiredSeekPointCount) but is a power of two multiple of $OODLELZ_BLOCK_LEN _desiredSeekPointCount_ = 16 is good for parallel decompression. (OODLELZ_SEEKPOINTCOUNT_DEFAULT) */ OOFUNC1 OO_S32 OOFUNC2 OodleLZ_GetNumSeekChunks(OO_S64 rawLen, OO_S32 seekChunkLen); /* Compute the number of seek chunks $:rawLen total length of uncompressed data $:seekChunkLen the length of a seek chunk (eg from $OodleLZ_MakeSeekChunkLen) $:return the number of seek chunks returns (rawLen+seekChunkLen-1)/seekChunkLen */ OOFUNC1 OO_SINTa OOFUNC2 OodleLZ_GetSeekTableMemorySizeNeeded(OO_S32 numSeekChunks,OodleLZSeekTable_Flags flags); /* Tells you the size in bytes to allocate the seekTable before calling $OodleLZ_FillSeekTable $:numSeekChunks number of seek chunks (eg from $OodleLZ_GetNumSeekChunks) $:flags options that will be passed to $OodleLZ_CreateSeekTable $:return size in bytes of memory needed for seek table If you wish to provide the memory for the seek table yourself, you may call this to get the required size, allocate the memory, and then simply point a $OodleLZ_SeekTable at your memory. Then use $OodleLZ_FillSeekTable to fill it out. Do NOT use sizeof(OodleLZ_SeekTable) ! */ OOFUNC1 OO_BOOL OOFUNC2 OodleLZ_FillSeekTable(OodleLZ_SeekTable * pTable,OodleLZSeekTable_Flags flags,OO_S32 seekChunkLen,const void * rawBuf, OO_SINTa rawLen,const void * compBuf,OO_SINTa compLen); /* scan compressed LZ stream to fill the seek table $:pTable pointer to table to be filled $:flags options $:seekChunkLen the length of a seek chunk (eg from $OodleLZ_MakeSeekChunkLen) $:rawBuf (optional) uncompressed buffer; used to compute the _rawCRCs_ member of $OodleLZ_SeekTable $:rawLen size of rawBuf $:compBuf compressed buffer $:compLen size of compBuf $:return true for success _pTable_ must be able to hold at least $OodleLZ_GetSeekTableMemorySizeNeeded _seekChunkLen_ must be a multiple of $OODLELZ_BLOCK_LEN. _seekChunkLen_ must match what was in CompressOptions when the buffer was made, or any integer multiple thereof. */ OOFUNC1 OodleLZ_SeekTable * OOFUNC2 OodleLZ_CreateSeekTable(OodleLZSeekTable_Flags flags,OO_S32 seekChunkLen,const void * rawBuf, OO_SINTa rawLen,const void * compBuf,OO_SINTa compLen); /* allocate a table, then scan compressed LZ stream to fill the seek table $:flags options $:seekChunkLen the length of a seek chunk (eg from $OodleLZ_MakeSeekChunkLen) $:rawBuf (optional) uncompressed buffer; used to compute the _rawCRCs_ member of $OodleLZ_SeekTable $:rawLen size of rawBuf $:compBuf compressed buffer $:compLen size of compBuf $:return pointer to table if succeeded, null if failed Same as $OodleLZ_FillSeekTable , but allocates the memory for you. Use $OodleLZ_FreeSeekTable to free. _seekChunkLen_ must be a multiple of $OODLELZ_BLOCK_LEN. _seekChunkLen_ must match what was in CompressOptions when the buffer was made, or any integer multiple thereof. */ OOFUNC1 void OOFUNC2 OodleLZ_FreeSeekTable(OodleLZ_SeekTable * pTable); /* Frees a table allocated by $OodleLZ_CreateSeekTable */ OOFUNC1 OO_BOOL OOFUNC2 OodleLZ_CheckSeekTableCRCs(const void * rawBuf,OO_SINTa rawLen, const OodleLZ_SeekTable * seekTable); /* Check the CRC's in seekTable vs rawBuf $:rawBuf uncompressed buffer $:rawLen size of rawBuf $:seekTable result of $OodleLZ_CreateSeekTable $:return true if the CRC's check out Note that $OodleLZ_Decompress option of $OodleLZ_CheckCRC checks the CRC of *compressed* data, this call checks the CRC of the *raw* (uncompressed) data. OodleLZ data contains a CRC of the compressed data if it was made with $(OodleLZ_CompressOptions:sendQuantumCRCs). The SeekTable contains a CRC of the raw data if it was made with $OodleLZSeekTable_Flags_MakeRawCRCs. Checking the CRC of compressed data is faster, but does not verify that the decompress succeeded. */ OOFUNC1 OO_S32 OOFUNC2 OodleLZ_FindSeekEntry( OO_S64 rawPos, const OodleLZ_SeekTable * seekTable); /* Find the seek entry that contains a raw position $:rawPos uncompressed position to look for $:seekTable result of $OodleLZ_CreateSeekTable $:return a seek entry index returns the index of the chunk that contains _rawPos_ */ OOFUNC1 OO_S64 OOFUNC2 OodleLZ_GetSeekEntryPackedPos( OO_S32 seekI , const OodleLZ_SeekTable * seekTable ); /* Get the compressed position of a seek entry $:seekI seek entry index , in [0,numSeekEntries) $:seekTable result of $OodleLZ_CreateSeekTable $:return compressed buffer position of the start of this seek entry */ //============================================================= OOFUNC1 const char * OOFUNC2 OodleLZ_CompressionLevel_GetName(OodleLZ_CompressionLevel compressSelect); /* Provides a string naming a $OodleLZ_CompressionLevel compressSelect */ OOFUNC1 const char * OOFUNC2 OodleLZ_Compressor_GetName(OodleLZ_Compressor compressor); /* Provides a string naming a $OodleLZ_Compressor compressor */ OOFUNC1 const char * OOFUNC2 OodleLZ_Jobify_GetName(OodleLZ_Jobify jobify); /* Provides a string naming a $OodleLZ_Jobify enum */ OOFUNC1 const OodleLZ_CompressOptions * OOFUNC2 OodleLZ_CompressOptions_GetDefault( OodleLZ_Compressor compressor OODEFAULT(OodleLZ_Compressor_Invalid), OodleLZ_CompressionLevel lzLevel OODEFAULT(OodleLZ_CompressionLevel_Normal)); /* Provides a pointer to default compression options $:compressor deprecated, ignored $:lzLevel deprecated, ignored Use to fill your own $OodleLZ_CompressOptions then change individual fields. */ // after you fiddle with options, call this to ensure they are allowed OOFUNC1 void OOFUNC2 OodleLZ_CompressOptions_Validate(OodleLZ_CompressOptions * pOptions); /* Clamps the values in _pOptions_ to be in valid range */ // inline functions for compressor property queries OODEFSTART OO_BOOL OodleLZ_Compressor_UsesWholeBlockQuantum(OodleLZ_Compressor compressor); /* OodleLZ_Compressor properties helper. Tells you if this compressor is "whole block quantum" ; must decode in steps of $OODLELZ_BLOCK_LEN , not $OODLELZ_QUANTUM_LEN like others. */ OO_BOOL OodleLZ_Compressor_UsesLargeWindow(OodleLZ_Compressor compressor); /* OodleLZ_Compressor properties helper. Tells you if this compressor is "LargeWindow" or not, meaning it can benefit from a Long-Range-Matcher and windows larger than $OODLELZ_BLOCK_LEN */ OO_BOOL OodleLZ_Compressor_CanDecodeInCircularWindow(OodleLZ_Compressor compressor); /* OodleLZ_Compressor properties helper. Tells you if this compressor can be decoded using a fixed size circular window. deprecated as of 2.9.0 */ OO_BOOL OodleLZ_Compressor_CanDecodeThreadPhased(OodleLZ_Compressor compressor); /* OodleLZ_Compressor properties helper. Tells you if this compressor can be used with the $OodleLZ_Decode_ThreadPhase. See $OodleLZ_About_ThreadPhasedDecode */ OO_BOOL OodleLZ_Compressor_CanDecodeInPlace(OodleLZ_Compressor compressor); /* OodleLZ_Compressor properties helper. Tells you if this compressor can be used with "in-place" decoding. This is now always true (all compressors support in-place decoding). The function is left for backward compatibility. All compressors in the future will support in-place, you don't need to check this property. */ OO_BOOL OodleLZ_Compressor_MustDecodeWithoutResets(OodleLZ_Compressor compressor); /* OodleLZ_Compressor properties helper. Tells you if this compressor must decode contiguous ranges of buffer with the same Decoder. That is, most of the compressors can be Reset and restart on any block, not just seek blocks, as long as the correct window data is provided. That is, if this returns false then the only state required across a non-reset block is the dictionary of previously decoded data. But if OodleLZ_Compressor_MustDecodeWithoutResets returns true, then you cannot do that, because the Decoder object must carry state across blocks (except reset blocks). This does not apply to seek points - you can always reset and restart decompression at a seek point. */ OO_BOOL OodleLZ_Compressor_CanDecodeFuzzSafe(OodleLZ_Compressor compressor); /* OodleLZ_Compressor properties helper. Tells you if this compressor is "fuzz safe" which means it can accept corrupted data and won't crash or overrun any buffers. */ OO_BOOL OodleLZ_Compressor_RespectsDictionarySize(OodleLZ_Compressor compressor); /* OodleLZ_Compressor properties helper. Tells you if this compressor obeys $(OodleLZ_CompressOptions:dictionarySize) which limits match references to a finite bound. (eg. for sliding window decompression). All the new codecs do (Kraken,Mermaid,Selkie,Leviathan). Some old codecs don't. */ //===================================================================== #define OODLELZ_COMPRESSOR_MASK(c) (((OO_U32)1)<<((OO_S32)(c))) // OODLELZ_COMPRESSOR_BOOLBIT : extract a value of 1 or 0 so it maps to "bool" #define OODLELZ_COMPRESSOR_BOOLBIT(s,c) (((s)>>(OO_S32)(c))&1) OOINLINEFUNC OO_BOOL OodleLZ_Compressor_IsNewLZFamily(OodleLZ_Compressor compressor) { const OO_U32 set = OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_Kraken) | OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_Leviathan) | OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_Mermaid) | OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_Selkie) | OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_Hydra); return OODLELZ_COMPRESSOR_BOOLBIT(set,compressor); } OOINLINEFUNC OO_BOOL OodleLZ_Compressor_CanDecodeFuzzSafe(OodleLZ_Compressor compressor) { #ifdef OODLE_ALLOW_DEPRECATED_COMPRESSORS const OO_U32 set = OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_None) | OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_Kraken) | OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_Leviathan) | OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_Mermaid) | OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_Selkie) | OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_Hydra) | OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_BitKnit) | OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_LZB16); return OODLELZ_COMPRESSOR_BOOLBIT(set,compressor); #else // all new compressors are fuzz safe return compressor != OodleLZ_Compressor_Invalid; #endif } OOINLINEFUNC OO_BOOL OodleLZ_Compressor_RespectsDictionarySize(OodleLZ_Compressor compressor) { #ifdef OODLE_ALLOW_DEPRECATED_COMPRESSORS const OO_U32 set = OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_None) | OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_Kraken) | OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_Leviathan) | OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_Mermaid) | OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_Selkie) | OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_Hydra) | OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_LZNA) | OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_BitKnit); return OODLELZ_COMPRESSOR_BOOLBIT(set,compressor); #else // all new compressors respect dictionarySize return compressor != OodleLZ_Compressor_Invalid; #endif } OOINLINEFUNC OO_BOOL OodleLZ_Compressor_UsesWholeBlockQuantum(OodleLZ_Compressor compressor) { return OodleLZ_Compressor_IsNewLZFamily(compressor); } OOINLINEFUNC OO_BOOL OodleLZ_Compressor_CanDecodeThreadPhased(OodleLZ_Compressor compressor) { return OodleLZ_Compressor_IsNewLZFamily(compressor); } OOINLINEFUNC OO_BOOL OodleLZ_Compressor_CanDecodeInPlace(OodleLZ_Compressor compressor) { // all compressors can now decode in place : return compressor != OodleLZ_Compressor_Invalid; } OOINLINEFUNC OO_BOOL OodleLZ_Compressor_CanDecodeInCircularWindow(OodleLZ_Compressor compressor) { #ifdef OODLE_ALLOW_DEPRECATED_COMPRESSORS const OO_U32 set = OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_LZH) | OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_LZB16); #else const OO_U32 set = 0; #endif return OODLELZ_COMPRESSOR_BOOLBIT(set,compressor); } OOINLINEFUNC OO_BOOL OodleLZ_Compressor_UsesLargeWindow(OodleLZ_Compressor compressor) { // all but LZH and LZB16 now are large window return ! OodleLZ_Compressor_CanDecodeInCircularWindow(compressor); } OOINLINEFUNC OO_BOOL OodleLZ_Compressor_MustDecodeWithoutResets(OodleLZ_Compressor compressor) { #ifdef OODLE_ALLOW_DEPRECATED_COMPRESSORS const OO_U32 set = OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_BitKnit) | OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_LZA) | OODLELZ_COMPRESSOR_MASK(OodleLZ_Compressor_LZNA); #else const OO_U32 set = 0; #endif return OODLELZ_COMPRESSOR_BOOLBIT(set,compressor); } OODEFEND //======================================================= #define OODLELZ_SCRATCH_MEM_NO_BOUND (-1) /* Scratch mem size when bound is unknown. Installed allocator may be used no matter how much scratch mem you provide. */ typedef enum OodleLZ_CompressScratchMemBoundType { OodleLZ_CompressScratchMemBoundType_WorstCase = 0, // Worst-case memory use estimate OodleLZ_CompressScratchMemBoundType_Typical = 1, // Typical memory use estimate; with this much scratch memory, allocations might still happen, but rarely. OodleLZ_CompressScratchMemBoundType_Force32 = 0x40000000, } OodleLZ_CompressScratchMemBoundType; /* Type of scratch memory bound to compute. $OodleLZ_CompressScratchMemBoundType_WorstCase provides a worst-case estimate for the amount of scratch memory required for compression. If at least this much scratch memory is provided to the compression functions, they are guaranteed to make no allocations of their own. Some compression levels don't have simple worst-case memory use guarantees and will return $OODLELZ_SCRATCH_MEM_NO_BOUND for this type of query. $OodleLZ_CompressScratchMemBoundType_Typical returns a scratch memory estimate that will be sufficient for most compression calls to not require additional memory, even when no hard guarantees exist. Even so, a good estimate may not be available, in which case $OODLELZ_SCRATCH_MEM_NO_BOUND is returned. */ OOFUNC1 OO_SINTa OOFUNC2 OodleLZ_GetCompressScratchMemBound( OodleLZ_Compressor compressor, OodleLZ_CompressionLevel level, OO_SINTa rawLen, const OodleLZ_CompressOptions * pOptions OODEFAULT(NULL) ); /* Return the maximum amount of scratch mem that will be needed by OodleLZ_Compress $:compressor which OodleLZ variant to use in compression $:level OodleLZ_CompressionLevel controls how much CPU effort is put into maximizing compression $:rawLen maximum number of bytes you will compress (plus dictionary backup) $:pOptions (optional) options; if NULL, $OodleLZ_CompressOptions_GetDefault is used If you pass scratch mem to $OodleLZ_Compress of this size, it is gauranteed to do no allocations. (normally if it runs out of scratch mem, it falls back to the installed allocator) For _rawLen_ pass at least the maximum size you will ever encode. If your data is divided into chunks, pass the chunk size. If you will encode full buffers of unbounded size, pass -1. The options must be the same as when you call $OodleLZ_Compress Some options and levels may not have simple finite bounds. Then $OODLELZ_SCRATCH_MEM_NO_BOUND is returned and the call to $OodleLZ_Compress may use the allocator even if infinite scratch memory is provided. Currently this applies to all the Optimal levels. When OODLELZ_SCRATCH_MEM_NO_BOUND is returned, you can still pass in scratch mem which will be used before going to the plugin allocator. */ OOFUNC1 OO_SINTa OOFUNC2 OodleLZ_GetCompressScratchMemBoundEx( OodleLZ_Compressor compressor, OodleLZ_CompressionLevel level, OodleLZ_CompressScratchMemBoundType boundType, OO_SINTa rawLen, const OodleLZ_CompressOptions * pOptions OODEFAULT(NULL) ); /* Return an estimate for the amount of scratch mem used by OodleLZ_Compress $:compressor which OodleLZ variant to use in compression $:level OodleLZ_CompressionLevel controls how much CPU effort is put into maximizing compression $:boundType Type of memory estimate to return. $:rawLen maximum number of bytes you will compress (plus dictionary backup) $:pOptions (optional) options; if NULL, $OodleLZ_CompressOptions_GetDefault is used Returns either a worst-case or typical scratch memory estimate for the given compressor, options and input size. When a worst-case scratch memory estimate exists, passing that much scratch memory to $OodleLZ_Compress is guaranteed to not do any allocations, provided the parameters match those of the compression call. "Typical" memory bounds are not hard guarantees but will usually not result in any extra allocations. For _rawLen_ pass at least the maximum size you will ever encode. If your data is divided into chunks, pass the chunk size. If you will encode full buffers of unbounded size, pass -1. Some options and levels may not have simple finite bounds. Then $OODLELZ_SCRATCH_MEM_NO_BOUND is returned and the call to $OodleLZ_Compress may use the allocator even if infinite scratch memory is provided. Currently this applies to all the Optimal levels. When OODLELZ_SCRATCH_MEM_NO_BOUND is returned, you can still pass in scratch mem which will be used before going to the plugin allocator. */ // get maximum expanded size for compBuf alloc : // (note this is actually larger than the maximum compressed stream, it includes trash padding) OOFUNC1 OO_SINTa OOFUNC2 OodleLZ_GetCompressedBufferSizeNeeded(OodleLZ_Compressor compressor,OO_SINTa rawSize); /* Return the size you must malloc the compressed buffer $:compressor compressor used; OodleLZ_Compressor_Invalid to make it enough for any compressor $:rawSize uncompressed size you will compress into this buffer The _compBuf_ passed to $OodleLZ_Compress must be allocated at least this big. note this is actually larger than the maximum size of a compressed stream, it includes overrun padding. */ // decBuf needs to be a little larger than rawLen, // this will tell you exactly how much : OOFUNC1 OO_SINTa OOFUNC2 OodleLZ_GetDecodeBufferSize(OodleLZ_Compressor compressor,OO_SINTa rawSize,OO_BOOL corruptionPossible); /* Get the size you must malloc the decode (raw) buffer $:compressor compressor used; OodleLZ_Compressor_Invalid to make it enough for any compressor $:rawSize uncompressed (raw) size without padding $:corruptionPossible true if it is possible for the decoder to get corrupted data $:return size of buffer to malloc; slightly larger than rawSize if padding is needed As of Oodle 2.9.0 this function is deprecated. For all new codecs you can just use the size of the uncompressed data for the decode buffer size (_rawSize_), no padding is needed. Note that LZB16 is still supported in 2.9.0 but does require padding when used in a circular window (which is deprecated). This padding is necessary for the older compressors when FuzzSafe_No is used. The old compressors and FuzzSafe_No are no longer supported. If _corruptionPossible_ is true, a slightly larger buffer size is returned. If _corruptionPossible_ is false, then you must ensure that the decoder does not get corrupted data, either by passing $OodleLZ_CheckCRC_Yes , or by your own mechanism. Note about possible overrun in LZ decoding (applies to the old non-fuzz-safe compressors) : as long as the compresseddata is not corrupted, and you decode either the entire compressed buffer, or an integer number of "seek chunks" ($OODLELZ_BLOCK_LEN), then there will be no overrun. So you can decode LZ data in place and it won't stomp any following bytes. If those conditions are not true (eg. decoding only part of a larger compressed stream, decoding around a circular window, decoding data that may be corrupted), then there may be some limited amount of overrun on decode, as returned by $OodleLZ_GetDecodeBufferSize. */ // OodleLZ_GetInPlaceDecodeBufferSize : // after compressing, ask how big the in-place buffer needs to be OOFUNC1 OO_SINTa OOFUNC2 OodleLZ_GetInPlaceDecodeBufferSize(OodleLZ_Compressor compressor,OO_SINTa compLen, OO_SINTa rawLen); /* Get the size of buffer needed for "in place" decode $:compressor compressor used; OodleLZ_Compressor_Invalid to make it enough for any compressor $:compLen compressed data length $:rawLen decompressed data length $:return size of buffer needed for "in place" decode ; slighly larger than rawLen To do an "in place" decode, allocate a buffer of this size (or larger). Read the compressed data into the end of the buffer, and decompress to the front of the buffer. The size returned here guarantees that the writes to the front of the buffer don't conflict with the reads from the end. If _compressor_ is one of the new codecs (Kraken,Mermaid,Selkie,Leviathan), the padding for in place decodes can be very small indeed. It is assumed you will be passing FuzzSafe_Yes to the decompress call. If _compLen_ is unknown, you want an in place buffer size that can accomodate any compressed data, then pass compLen = 0. See $OodleLZ_Decompress for more. */ // GetCompressedStepForRawStep is at OODLELZ_QUANTUM_LEN granularity // returns how many packed bytes to step to get the desired raw count step OOFUNC1 OO_SINTa OOFUNC2 OodleLZ_GetCompressedStepForRawStep( const void * compPtr, OO_SINTa compAvail, OO_SINTa startRawPos, OO_SINTa rawSeekBytes, OO_SINTa * pEndRawPos OODEFAULT(NULL), OO_BOOL * pIndependent OODEFAULT(NULL) ); /* How many bytes to step a compressed pointer to advance a certain uncompressed amount $:compPtr current compressed pointer $:compAvail compressed bytes available at compPtr $:startRawPos initial raw pos (corresponding to compPtr) $:rawSeekBytes the desired step in raw bytes, must be a multiple of $OODLELZ_QUANTUM_LEN or $OODLELZ_BLOCK_LEN $:pEndRawPos (optional) filled with the end raw pos actually reached $:pIndependent (optional) filled with a bool that is true if the current chunk is independent from previous $:return the number of compressed bytes to step You should try to use GetCompressedStepForRawStep only at block granularity - both _startRawPos_ and _rawSeekBytes_ should be multiples of OODLELZ_BLOCK_LEN (except at the end of the stream). As long as you do that, then *pEndRawPos will = startRawPos + rawSeekBytes. You can use it at quantum granularity (OODLELZ_QUANTUM_LEN), but there are some caveats. You cannot step quanta inside uncompressed blocks, only in normal LZ blocks. If you try to seek quanta inside an uncompressed block, you will get *pEndRawPos = the end of the block. You can only resume seeking from *pEndRawPos . returns 0 for valid not-enough-data case returns -1 for error If _compAvail_ is not the whole compressed buffer, then the returned step may be less than the amount you requested. eg. if the compressed data in _compAvail_ does not contain enough data to make a step of _rawSeekBytes_ a smaller step will be taken. NOTE : *can* return comp step > comp avail ! */ OOFUNC1 OodleLZ_Compressor OOFUNC2 OodleLZ_GetAllChunksCompressor(const void * compBuf,OO_SINTa compBufSize, OO_SINTa rawLen); /* ask who compressed all chunks in this buf chunk $:compBuf pointer to compressed data; must be the start of compressed buffer, or a step of $OODLELZ_BLOCK_LEN raw bytes $:compBufSize size of _compBuf_ $:rawLen rawlen of data in _compBuf_ $:return the $OodleLZ_Compressor used to encode this chunk returns a simple compressor (for example OodleLZ_Compressor_Kraken) if that was used on all chunks returns OodleLZ_Compressor_Hydra if different NewLZ encoders were used (for example Kraken+Mermaid) returns OodleLZ_Compressor_Count if a heterogenous mix of compressors was used (not just NewLZ) returns OodleLZ_Compressor_Invalid on error note this is only for this chunk - later chunks may have different compressors (eg. with Hydra) if you compressed all chunks the same it's up to you to store that info in your header returns OodleLZ_Compressor_Invalid if _compBufSize_ is too small or any chunk is corrupt */ OOFUNC1 OodleLZ_Compressor OOFUNC2 OodleLZ_GetFirstChunkCompressor(const void * compChunkPtr, OO_SINTa compBufAvail, OO_BOOL * pIndependent); /* ask who compressed this chunk $:compChunkPtr pointer to compressed data; must be the start of compressed buffer, or a step of $OODLELZ_BLOCK_LEN raw bytes $:compBufAvail number of bytes at _compChunkPtr_ available to read $:pIndependent (optional) filled with a bool for whether this chunk is independent of predecessors $:return the $OodleLZ_Compressor used to encode this chunk note this is only for this chunk - later chunks may have different compressors (eg. with Hydra) if you compressed all chunks the same it's up to you to store that info in your header Use $OodleLZ_GetAllChunksCompressor for data that might be mixed compressors. This replaces the deprecated function $OodleLZ_GetChunkCompressor returns OodleLZ_Compressor_Invalid if _compBufAvail_ is too small or the chunk is corrupt */ OOFUNC1 OodleLZ_Compressor OOFUNC2 OodleLZ_GetChunkCompressor(const void * compChunkPtr, OO_SINTa compBufAvail, OO_BOOL * pIndependent); /* Deprecated entry point for backwards compatibility Use $OodleLZ_GetFirstChunkCompressor or $OodleLZ_GetAllChunksCompressor */ //======================================================= #define OODLE_HEADER_VERSION ((46<<24)|(OODLE2_VERSION_MAJOR<<16)|(OODLE2_VERSION_MINOR<<8)|(OO_U32)sizeof(OodleLZ_SeekTable)) /* OODLE_HEADER_VERSION is used to ensure the Oodle header matches the lib. Don't copy the value of this macro, it will change when the header is rev'ed. This is what you pass to $OodleX_Init or $Oodle_CheckVersion */ OOFUNC1 OO_BOOL OOFUNC2 Oodle_CheckVersion(OO_U32 oodle_header_version, OO_U32 * pOodleLibVersion OODEFAULT(NULL)); /* Check the Oodle lib version against the header you are compiling with $:oodle_header_version pass $OODLE_HEADER_VERSION here $:pOodleLibVersion (optional) filled with the Oodle lib version $:return false if $OODLE_HEADER_VERSION is not compatible with this lib If you use the Oodle2 Ext lib,, $OodleX_Init does it for you. But if you want to check that you have a compatible lib before trying to Init, then use this. */ OOFUNC1 void OOFUNC2 Oodle_LogHeader(void); /* Log the Oodle version & copyright Uses the log set with $OodleCore_Plugins_SetPrintf */ // define old names so they still compile : #define OODLECORE_PLUGIN_JOB_MAX_DEPENDENCIES OODLE_JOB_MAX_DEPENDENCIES #define t_fp_OodleCore_Plugin_Job t_fp_Oodle_Job #ifdef _MSC_VER #pragma warning(pop) #pragma pack(pop, Oodle) #endif #endif // __OODLE2_H_INCLUDED__