--- /dev/null
+LZMA compression\r
+----------------\r
+Version: 9.35\r
+\r
+This file describes LZMA encoding and decoding functions written in C language.\r
+\r
+LZMA is an improved version of famous LZ77 compression algorithm. \r
+It was improved in way of maximum increasing of compression ratio,\r
+keeping high decompression speed and low memory requirements for \r
+decompressing.\r
+\r
+Note: you can read also LZMA Specification (lzma-specification.txt from LZMA SDK)\r
+\r
+Also you can look source code for LZMA encoding and decoding:\r
+ C/Util/Lzma/LzmaUtil.c\r
+\r
+\r
+LZMA compressed file format\r
+---------------------------\r
+Offset Size Description\r
+ 0 1 Special LZMA properties (lc,lp, pb in encoded form)\r
+ 1 4 Dictionary size (little endian)\r
+ 5 8 Uncompressed size (little endian). -1 means unknown size\r
+ 13 Compressed data\r
+\r
+\r
+\r
+ANSI-C LZMA Decoder\r
+~~~~~~~~~~~~~~~~~~~\r
+\r
+Please note that interfaces for ANSI-C code were changed in LZMA SDK 4.58.\r
+If you want to use old interfaces you can download previous version of LZMA SDK\r
+from sourceforge.net site.\r
+\r
+To use ANSI-C LZMA Decoder you need the following files:\r
+1) LzmaDec.h + LzmaDec.c + 7zTypes.h + Precomp.h + Compiler.h\r
+\r
+Look example code:\r
+ C/Util/Lzma/LzmaUtil.c\r
+\r
+\r
+Memory requirements for LZMA decoding\r
+-------------------------------------\r
+\r
+Stack usage of LZMA decoding function for local variables is not \r
+larger than 200-400 bytes.\r
+\r
+LZMA Decoder uses dictionary buffer and internal state structure.\r
+Internal state structure consumes\r
+ state_size = (4 + (1.5 << (lc + lp))) KB\r
+by default (lc=3, lp=0), state_size = 16 KB.\r
+\r
+\r
+How To decompress data\r
+----------------------\r
+\r
+LZMA Decoder (ANSI-C version) now supports 2 interfaces:\r
+1) Single-call Decompressing\r
+2) Multi-call State Decompressing (zlib-like interface)\r
+\r
+You must use external allocator:\r
+Example:\r
+void *SzAlloc(void *p, size_t size) { p = p; return malloc(size); }\r
+void SzFree(void *p, void *address) { p = p; free(address); }\r
+ISzAlloc alloc = { SzAlloc, SzFree };\r
+\r
+You can use p = p; operator to disable compiler warnings.\r
+\r
+\r
+Single-call Decompressing\r
+-------------------------\r
+When to use: RAM->RAM decompressing\r
+Compile files: LzmaDec.h + LzmaDec.c + 7zTypes.h\r
+Compile defines: no defines\r
+Memory Requirements:\r
+ - Input buffer: compressed size\r
+ - Output buffer: uncompressed size\r
+ - LZMA Internal Structures: state_size (16 KB for default settings) \r
+\r
+Interface:\r
+ int LzmaDecode(Byte *dest, SizeT *destLen, const Byte *src, SizeT *srcLen,\r
+ const Byte *propData, unsigned propSize, ELzmaFinishMode finishMode, \r
+ ELzmaStatus *status, ISzAlloc *alloc);\r
+ In: \r
+ dest - output data\r
+ destLen - output data size\r
+ src - input data\r
+ srcLen - input data size\r
+ propData - LZMA properties (5 bytes)\r
+ propSize - size of propData buffer (5 bytes)\r
+ finishMode - It has meaning only if the decoding reaches output limit (*destLen).\r
+ LZMA_FINISH_ANY - Decode just destLen bytes.\r
+ LZMA_FINISH_END - Stream must be finished after (*destLen).\r
+ You can use LZMA_FINISH_END, when you know that \r
+ current output buffer covers last bytes of stream. \r
+ alloc - Memory allocator.\r
+\r
+ Out: \r
+ destLen - processed output size \r
+ srcLen - processed input size \r
+\r
+ Output:\r
+ SZ_OK\r
+ status:\r
+ LZMA_STATUS_FINISHED_WITH_MARK\r
+ LZMA_STATUS_NOT_FINISHED \r
+ LZMA_STATUS_MAYBE_FINISHED_WITHOUT_MARK\r
+ SZ_ERROR_DATA - Data error\r
+ SZ_ERROR_MEM - Memory allocation error\r
+ SZ_ERROR_UNSUPPORTED - Unsupported properties\r
+ SZ_ERROR_INPUT_EOF - It needs more bytes in input buffer (src).\r
+\r
+ If LZMA decoder sees end_marker before reaching output limit, it returns OK result,\r
+ and output value of destLen will be less than output buffer size limit.\r
+\r
+ You can use multiple checks to test data integrity after full decompression:\r
+ 1) Check Result and "status" variable.\r
+ 2) Check that output(destLen) = uncompressedSize, if you know real uncompressedSize.\r
+ 3) Check that output(srcLen) = compressedSize, if you know real compressedSize. \r
+ You must use correct finish mode in that case. */ \r
+\r
+\r
+Multi-call State Decompressing (zlib-like interface)\r
+----------------------------------------------------\r
+\r
+When to use: file->file decompressing \r
+Compile files: LzmaDec.h + LzmaDec.c + 7zTypes.h\r
+\r
+Memory Requirements:\r
+ - Buffer for input stream: any size (for example, 16 KB)\r
+ - Buffer for output stream: any size (for example, 16 KB)\r
+ - LZMA Internal Structures: state_size (16 KB for default settings) \r
+ - LZMA dictionary (dictionary size is encoded in LZMA properties header)\r
+\r
+1) read LZMA properties (5 bytes) and uncompressed size (8 bytes, little-endian) to header:\r
+ unsigned char header[LZMA_PROPS_SIZE + 8];\r
+ ReadFile(inFile, header, sizeof(header)\r
+\r
+2) Allocate CLzmaDec structures (state + dictionary) using LZMA properties\r
+\r
+ CLzmaDec state;\r
+ LzmaDec_Constr(&state);\r
+ res = LzmaDec_Allocate(&state, header, LZMA_PROPS_SIZE, &g_Alloc);\r
+ if (res != SZ_OK)\r
+ return res;\r
+\r
+3) Init LzmaDec structure before any new LZMA stream. And call LzmaDec_DecodeToBuf in loop\r
+\r
+ LzmaDec_Init(&state);\r
+ for (;;)\r
+ {\r
+ ... \r
+ int res = LzmaDec_DecodeToBuf(CLzmaDec *p, Byte *dest, SizeT *destLen, \r
+ const Byte *src, SizeT *srcLen, ELzmaFinishMode finishMode);\r
+ ...\r
+ }\r
+\r
+\r
+4) Free all allocated structures\r
+ LzmaDec_Free(&state, &g_Alloc);\r
+\r
+Look example code:\r
+ C/Util/Lzma/LzmaUtil.c\r
+\r
+\r
+How To compress data\r
+--------------------\r
+\r
+Compile files: \r
+ 7zTypes.h\r
+ Threads.h \r
+ LzmaEnc.h\r
+ LzmaEnc.c\r
+ LzFind.h\r
+ LzFind.c\r
+ LzFindMt.h\r
+ LzFindMt.c\r
+ LzHash.h\r
+\r
+Memory Requirements:\r
+ - (dictSize * 11.5 + 6 MB) + state_size\r
+\r
+Lzma Encoder can use two memory allocators:\r
+1) alloc - for small arrays.\r
+2) allocBig - for big arrays.\r
+\r
+For example, you can use Large RAM Pages (2 MB) in allocBig allocator for \r
+better compression speed. Note that Windows has bad implementation for \r
+Large RAM Pages. \r
+It's OK to use same allocator for alloc and allocBig.\r
+\r
+\r
+Single-call Compression with callbacks\r
+--------------------------------------\r
+\r
+Look example code:\r
+ C/Util/Lzma/LzmaUtil.c\r
+\r
+When to use: file->file compressing \r
+\r
+1) you must implement callback structures for interfaces:\r
+ISeqInStream\r
+ISeqOutStream\r
+ICompressProgress\r
+ISzAlloc\r
+\r
+static void *SzAlloc(void *p, size_t size) { p = p; return MyAlloc(size); }\r
+static void SzFree(void *p, void *address) { p = p; MyFree(address); }\r
+static ISzAlloc g_Alloc = { SzAlloc, SzFree };\r
+\r
+ CFileSeqInStream inStream;\r
+ CFileSeqOutStream outStream;\r
+\r
+ inStream.funcTable.Read = MyRead;\r
+ inStream.file = inFile;\r
+ outStream.funcTable.Write = MyWrite;\r
+ outStream.file = outFile;\r
+\r
+\r
+2) Create CLzmaEncHandle object;\r
+\r
+ CLzmaEncHandle enc;\r
+\r
+ enc = LzmaEnc_Create(&g_Alloc);\r
+ if (enc == 0)\r
+ return SZ_ERROR_MEM;\r
+\r
+\r
+3) initialize CLzmaEncProps properties;\r
+\r
+ LzmaEncProps_Init(&props);\r
+\r
+ Then you can change some properties in that structure.\r
+\r
+4) Send LZMA properties to LZMA Encoder\r
+\r
+ res = LzmaEnc_SetProps(enc, &props);\r
+\r
+5) Write encoded properties to header\r
+\r
+ Byte header[LZMA_PROPS_SIZE + 8];\r
+ size_t headerSize = LZMA_PROPS_SIZE;\r
+ UInt64 fileSize;\r
+ int i;\r
+\r
+ res = LzmaEnc_WriteProperties(enc, header, &headerSize);\r
+ fileSize = MyGetFileLength(inFile);\r
+ for (i = 0; i < 8; i++)\r
+ header[headerSize++] = (Byte)(fileSize >> (8 * i));\r
+ MyWriteFileAndCheck(outFile, header, headerSize)\r
+\r
+6) Call encoding function:\r
+ res = LzmaEnc_Encode(enc, &outStream.funcTable, &inStream.funcTable, \r
+ NULL, &g_Alloc, &g_Alloc);\r
+\r
+7) Destroy LZMA Encoder Object\r
+ LzmaEnc_Destroy(enc, &g_Alloc, &g_Alloc);\r
+\r
+\r
+If callback function return some error code, LzmaEnc_Encode also returns that code\r
+or it can return the code like SZ_ERROR_READ, SZ_ERROR_WRITE or SZ_ERROR_PROGRESS.\r
+\r
+\r
+Single-call RAM->RAM Compression\r
+--------------------------------\r
+\r
+Single-call RAM->RAM Compression is similar to Compression with callbacks,\r
+but you provide pointers to buffers instead of pointers to stream callbacks:\r
+\r
+SRes LzmaEncode(Byte *dest, SizeT *destLen, const Byte *src, SizeT srcLen,\r
+ const CLzmaEncProps *props, Byte *propsEncoded, SizeT *propsSize, int writeEndMark, \r
+ ICompressProgress *progress, ISzAlloc *alloc, ISzAlloc *allocBig);\r
+\r
+Return code:\r
+ SZ_OK - OK\r
+ SZ_ERROR_MEM - Memory allocation error \r
+ SZ_ERROR_PARAM - Incorrect paramater\r
+ SZ_ERROR_OUTPUT_EOF - output buffer overflow\r
+ SZ_ERROR_THREAD - errors in multithreading functions (only for Mt version)\r
+\r
+\r
+\r
+Defines\r
+-------\r
+\r
+_LZMA_SIZE_OPT - Enable some optimizations in LZMA Decoder to get smaller executable code.\r
+\r
+_LZMA_PROB32 - It can increase the speed on some 32-bit CPUs, but memory usage for \r
+ some structures will be doubled in that case.\r
+\r
+_LZMA_UINT32_IS_ULONG - Define it if int is 16-bit on your compiler and long is 32-bit.\r
+\r
+_LZMA_NO_SYSTEM_SIZE_T - Define it if you don't want to use size_t type.\r
+\r
+\r
+_7ZIP_PPMD_SUPPPORT - Define it if you don't want to support PPMD method in AMSI-C .7z decoder.\r
+\r
+\r
+C++ LZMA Encoder/Decoder \r
+~~~~~~~~~~~~~~~~~~~~~~~~\r
+C++ LZMA code use COM-like interfaces. So if you want to use it, \r
+you can study basics of COM/OLE.\r
+C++ LZMA code is just wrapper over ANSI-C code.\r
+\r
+\r
+C++ Notes\r
+~~~~~~~~~~~~~~~~~~~~~~~~\r
+If you use some C++ code folders in 7-Zip (for example, C++ code for .7z handling),\r
+you must check that you correctly work with "new" operator.\r
+7-Zip can be compiled with MSVC 6.0 that doesn't throw "exception" from "new" operator.\r
+So 7-Zip uses "CPP\Common\NewHandler.cpp" that redefines "new" operator:\r
+operator new(size_t size)\r
+{\r
+ void *p = ::malloc(size);\r
+ if (p == 0)\r
+ throw CNewException();\r
+ return p;\r
+}\r
+If you use MSCV that throws exception for "new" operator, you can compile without \r
+"NewHandler.cpp". So standard exception will be used. Actually some code of \r
+7-Zip catches any exception in internal code and converts it to HRESULT code.\r
+So you don't need to catch CNewException, if you call COM interfaces of 7-Zip.\r
+\r
+---\r
+\r
+http://www.7-zip.org\r
+http://www.7-zip.org/sdk.html\r
+http://www.7-zip.org/support.html\r
notaz.gp2x.de / pcsx_rearmed.git / blobdiff