src/liblzma/api/lzma/lzma.h

   1 /**
   2  * \file        lzma/lzma.h
   3  * \brief       LZMA filter
   4  *
   5  * \author      Copyright (C) 1999-2006 Igor Pavlov
   6  * \author      Copyright (C) 2007 Lasse Collin
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2.1 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  */
  18
  19 #ifndef LZMA_H_INTERNAL
  20 #       error Never include this file directly. Use <lzma.h> instead.
  21 #endif
  22
  23
  24 /**
  25  * \brief       Filter ID
  26  *
  27  * Filter ID of the LZMA filter. This is used as lzma_options_filter.id.
  28  */
  29 #define LZMA_FILTER_LZMA        LZMA_VLI_C(0x40)
  30
  31
  32 /**
  33  * \brief       LZMA compression modes
  34  *
  35  * Currently there are only two modes. Earlier LZMA SDKs had also third
  36  * mode between fast and best.
  37  */
  38 typedef enum {
  39         LZMA_MODE_INVALID = -1,
  40                 /**<
  41                  * \brief       Invalid mode
  42                  *
  43                  * Used as array terminator in lzma_available_modes.
  44                  */
  45
  46
  47         LZMA_MODE_FAST = 0,
  48                 /**<
  49                  * \brief       Fast compression
  50                  *
  51                  * Fast mode is usually at its best when combined with
  52                  * a hash chain match finder.
  53                  */
  54
  55         LZMA_MODE_BEST = 2
  56                 /**<
  57                  * \brief       Best compression ratio
  58                  *
  59                  * This is usually notably slower than fast mode. Use this
  60                  * together with binary tree match finders to expose the
  61                  * full potential of the LZMA encoder.
  62                  */
  63 } lzma_mode;
  64
  65
  66 /**
  67  * \brief       Match finders
  68  *
  69  * Match finder has major effect on both speed and compression ratio.
  70  * Usually hash chains are faster than binary trees.
  71  */
  72 typedef enum {
  73         LZMA_MF_INVALID = -1,
  74                 /**<
  75                  * \brief       Invalid match finder ID
  76                  *
  77                  * Used as array terminator in lzma_available_match_finders.
  78                  */
  79
  80         LZMA_MF_HC3     = 0x03,
  81                 /**<
  82                  * \brief       Hash Chain with 3 bytes hashing
  83                  *
  84                  * \todo Memory requirements
  85                  *
  86                  * \note        It's possible that this match finder gets
  87                  *              removed in future. The definition will stay
  88                  *              in this header, but liblzma may return
  89                  *              LZMA_HEADER_ERROR if it is specified (just
  90                  *              like it would if the match finder had been
  91                  *              disabled at compile time).
  92                  */
  93
  94         LZMA_MF_HC4     = 0x04,
  95                 /**<
  96                  * \brief       Hash Chain with 4 bytes hashing
  97                  *
  98                  * Memory requirements: 7.5 * dictionary_size + 4 MiB
  99                  *
 100                  * \note        It's possible that this match finder gets
 101                  *              removed in future. The definition will stay
 102                  *              in this header, but liblzma may return
 103                  *              LZMA_HEADER_ERROR if it is specified (just
 104                  *              like it would if the match finder had been
 105                  *              disabled at compile time).
 106                  */
 107
 108         LZMA_MF_BT2     = 0x12,
 109                 /**<
 110                  * \brief       Binary Tree with 2 bytes hashing
 111                  *
 112                  * Memory requirements: 9.5 * dictionary_size + 4 MiB
 113                  */
 114
 115         LZMA_MF_BT3     = 0x13,
 116                 /**<
 117                  * \brief       Binary Tree with 3 bytes hashing
 118                  *
 119                  * Memory requirements: 11.5 * dictionary_size + 4 MiB
 120                  */
 121
 122         LZMA_MF_BT4     = 0x14
 123                 /**<
 124                  * \brief       Binary Tree with 4 bytes hashing
 125                  *
 126                  * Memory requirements: 11.5 * dictionary_size + 4 MiB
 127                  */
 128 } lzma_match_finder;
 129
 130
 131 /**
 132  * \brief       Options specific to the LZMA method handler
 133  */
 134 typedef struct {
 135         /**********************************
 136          * LZMA encoding/decoding options *
 137          **********************************/
 138
 139         /* These options are required in encoder and also with raw decoding. */
 140
 141         /**
 142          * \brief       Dictionary size in bytes
 143          *
 144          * Dictionary size indicates how many bytes of the recently processed
 145          * uncompressed data is kept in memory. One method to reduce size of
 146          * the uncompressed data is to store distance-length pairs, which
 147          * indicate what data to repeat from the dictionary buffer. Thus,
 148          * the bigger the dictionary, the better compression ratio usually is.
 149          *
 150          * Raw decoding: Too big dictionary does no other harm than
 151          * wasting memory. This value is ignored by lzma_raw_decode_buffer(),
 152          * because it uses the target buffer as the dictionary.
 153          */
 154         uint32_t dictionary_size;
 155 #       define LZMA_DICTIONARY_SIZE_MIN            1
 156 #       define LZMA_DICTIONARY_SIZE_MAX            (UINT32_C(1) << 30)
 157 #       define LZMA_DICTIONARY_SIZE_DEFAULT        (UINT32_C(1) << 23)
 158
 159         /**
 160          * \brief       Number of literal context bits
 161          *
 162          * How many of the highest bits of the previous uncompressed
 163          * eight-bit byte (also known as `literal') are taken into
 164          * account when predicting the bits of the next literal.
 165          *
 166          * \todo        Example
 167          */
 168         uint32_t literal_context_bits;
 169 #       define LZMA_LITERAL_CONTEXT_BITS_MIN       0
 170 #       define LZMA_LITERAL_CONTEXT_BITS_MAX       8
 171 #       define LZMA_LITERAL_CONTEXT_BITS_DEFAULT   3
 172
 173         /**
 174          * \brief       Number of literal position bits
 175          *
 176          * How many of the lowest bits of the current position (number
 177          * of bytes from the beginning of the uncompressed data) in the
 178          * uncompressed data is taken into account when predicting the
 179          * bits of the next literal (a single eight-bit byte).
 180          *
 181          * \todo        Example
 182          */
 183         uint32_t literal_pos_bits;
 184 #       define LZMA_LITERAL_POS_BITS_MIN           0
 185 #       define LZMA_LITERAL_POS_BITS_MAX           4
 186 #       define LZMA_LITERAL_POS_BITS_DEFAULT       0
 187
 188         /**
 189          * \brief       Number of position bits
 190          *
 191          * How many of the lowest bits of the current position in the
 192          * uncompressed data is taken into account when estimating
 193          * probabilities of matches. A match is a sequence of bytes for
 194          * which a matching sequence is found from the dictionary and
 195          * thus can be stored as distance-length pair.
 196          *
 197          * Example: If most of the matches occur at byte positions
 198          * of 8 * n + 3, that is, 3, 11, 19, ... set pos_bits to 3,
 199          * because 2**3 == 8.
 200          */
 201         uint32_t pos_bits;
 202 #       define LZMA_POS_BITS_MIN                   0
 203 #       define LZMA_POS_BITS_MAX                   4
 204 #       define LZMA_POS_BITS_DEFAULT               2
 205
 206         /**
 207          * \brief       Pointer to an initial dictionary
 208          *
 209          * It is possible to initialize the LZ77 history window using
 210          * a preset dictionary. Here is a good quote from zlib's
 211          * documentation; this applies to LZMA as is:
 212          *
 213          * "The dictionary should consist of strings (byte sequences) that
 214          * are likely to be encountered later in the data to be compressed,
 215          * with the most commonly used strings preferably put towards the
 216          * end of the dictionary. Using a dictionary is most useful when
 217          * the data to be compressed is short and can be predicted with
 218          * good accuracy; the data can then be compressed better than
 219          * with the default empty dictionary."
 220          * (From deflateSetDictionary() in zlib.h of zlib version 1.2.3)
 221          *
 222          * This feature should be used only in special situations.
 223          * It works correctly only with raw encoding and decoding.
 224          * Currently none of the container formats supported by
 225          * liblzma allow preset dictionary when decoding, thus if
 226          * you create a .lzma file with preset dictionary, it cannot
 227          * be decoded with the regular .lzma decoder functions.
 228          *
 229          * \todo        This feature is not implemented yet.
 230          */
 231         const uint8_t *preset_dictionary;
 232
 233         /**
 234          * \brief       Size of the preset dictionary
 235          *
 236          * Specifies the size of the preset dictionary. If the size is
 237          * bigger than dictionary_size, only the last dictionary_size
 238          * bytes are processed.
 239          *
 240          * This variable is read only when preset_dictionary is not NULL.
 241          */
 242         uint32_t preset_dictionary_size;
 243
 244         /******************************************
 245          * LZMA options needed only when encoding *
 246          ******************************************/
 247
 248         /** LZMA compression mode */
 249         lzma_mode mode;
 250
 251         /**
 252          * \brief       Number of fast bytes
 253          *
 254          * Number of fast bytes determines how many bytes the encoder
 255          * compares from the match candidates when looking for the best
 256          * match. Bigger fast bytes value usually increase both compression
 257          * ratio and time.
 258          */
 259         uint32_t fast_bytes;
 260 #       define LZMA_FAST_BYTES_MIN                 5
 261 #       define LZMA_FAST_BYTES_MAX                 273
 262 #       define LZMA_FAST_BYTES_DEFAULT             128
 263
 264         /** Match finder ID */
 265         lzma_match_finder match_finder;
 266
 267         /**
 268          * \brief       Match finder cycles
 269          *
 270          * Higher values give slightly better compression ratio but
 271          * decrease speed. Use special value 0 to let liblzma use
 272          * match-finder-dependent default value.
 273          *
 274          * \todo        Write much better description.
 275          */
 276         uint32_t match_finder_cycles;
 277
 278 } lzma_options_lzma;
 279
 280
 281 /**
 282  * \brief       Available LZMA encoding modes
 283  *
 284  * Pointer to an array containing the list of available encoding modes.
 285  *
 286  * This variable is available only if LZMA encoder has been enabled.
 287  */
 288 extern const lzma_mode *const lzma_available_modes;
 289
 290
 291 /**
 292  * \brief       Available match finders
 293  *
 294  * Pointer to an array containing the list of available match finders.
 295  * The last element is LZMA_MF_INVALID.
 296  *
 297  * This variable is available only if LZMA encoder has been enabled.
 298  */
 299 extern const lzma_match_finder *const lzma_available_match_finders;
 300
 301
 302 /**
 303  * \brief       Table of presets for the LZMA filter
 304  *
 305  * lzma_presets[0] is the fastest and lzma_preset_lzma[8] is the slowest.
 306  * These presets match the switches -1 .. -9 of the lzma command line tool
 307  *
 308  * The preset values are subject to changes between liblzma versions.
 309  *
 310  * This variable is available only if LZMA encoder has been enabled.
 311  */
 312 extern const lzma_options_lzma lzma_preset_lzma[9];