src/liblzma/api/lzma/subblock.h

   1 /**
   2  * \file        lzma/subblock.h
   3  * \brief       Subblock 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 Subblock filter. This is used as lzma_options_filter.id.
  28  */
  29 #define LZMA_FILTER_SUBBLOCK    LZMA_VLI_C(0x01)
  30
  31
  32 /**
  33  * \brief       Subfilter mode
  34  *
  35  * See lzma_options_subblock.subfilter_mode for details.
  36  */
  37 typedef enum {
  38         LZMA_SUBFILTER_NONE,
  39                 /**<
  40                  * No Subfilter is in use.
  41                  */
  42
  43         LZMA_SUBFILTER_SET,
  44                 /**<
  45                  * New Subfilter has been requested to be initialized.
  46                  */
  47
  48         LZMA_SUBFILTER_RUN,
  49                 /**<
  50                  * Subfilter is active.
  51                  */
  52
  53         LZMA_SUBFILTER_FINISH
  54                 /**<
  55                  * Subfilter has been requested to be finished.
  56                  */
  57 } lzma_subfilter_mode;
  58
  59
  60 /**
  61  * \brief       Options for the Subblock filter
  62  *
  63  * Specifying options for the Subblock filter is optional: if the pointer
  64  * options is NULL, no subfilters are allowed and the default value is used
  65  * for subblock_data_size.
  66  */
  67 typedef struct {
  68         /* Options for encoder and decoder */
  69
  70         /**
  71          * \brief       Allowing subfilters
  72          *
  73          * If this true, subfilters are allowed.
  74          *
  75          * In the encoder, if this is set to false, subfilter_mode and
  76          * subfilter_options are completely ignored.
  77          */
  78         lzma_bool allow_subfilters;
  79
  80         /* Options for encoder only */
  81
  82         /**
  83          * \brief       Alignment
  84          *
  85          * The Subblock filter encapsulates the input data into Subblocks.
  86          * Each Subblock has a header which takes a few bytes of space.
  87          * When the output of the Subblock encoder is fed to another filter
  88          * that takes advantage of the alignment of the input data (e.g. LZMA),
  89          * the Subblock filter can add padding to keep the actual data parts
  90          * in the Subblocks aligned correctly.
  91          *
  92          * The alignment should be a positive integer. Subblock filter will
  93          * add enough padding between Subblocks so that this is true for
  94          * every payload byte:
  95          * input_offset % alignment == output_offset % alignment
  96          *
  97          * The Subblock filter assumes that the first output byte will be
  98          * written to a position in the output stream that is properly
  99          * aligned. This requirement is automatically met when the start
 100          * offset of the Stream or Block is correctly told to Block or
 101          * Stream encoder.
 102          */
 103         uint32_t alignment;
 104 #       define LZMA_SUBBLOCK_ALIGNMENT_MIN 1
 105 #       define LZMA_SUBBLOCK_ALIGNMENT_MAX 32
 106 #       define LZMA_SUBBLOCK_ALIGNMENT_DEFAULT 4
 107
 108         /**
 109          * \brief       Size of the Subblock Data part of each Subblock
 110          *
 111          * This value is re-read every time a new Subblock is started.
 112          *
 113          * Bigger values
 114          *   - save a few bytes of space;
 115          *   - increase latency in the encoder (but no effect for decoding);
 116          *   - decrease memory locality (increased cache pollution) in the
 117          *     encoder (no effect in decoding).
 118          */
 119         uint32_t subblock_data_size;
 120 #       define LZMA_SUBBLOCK_DATA_SIZE_MIN 1
 121 #       define LZMA_SUBBLOCK_DATA_SIZE_MAX (UINT32_C(1) << 28)
 122 #       define LZMA_SUBBLOCK_DATA_SIZE_DEFAULT 4096
 123
 124         /**
 125          * \brief       Run-length encoder remote control
 126          *
 127          * The Subblock filter has an internal run-length encoder (RLE). It
 128          * can be useful when the data includes byte sequences that repeat
 129          * very many times. The RLE can be used also when a Subfilter is
 130          * in use; the RLE will be applied to the output of the Subfilter.
 131          *
 132          * Note that in contrast to traditional RLE, this RLE is intended to
 133          * be used only when there's a lot of data to be repeated. If the
 134          * input data has e.g. 500 bytes of NULs now and then, this RLE
 135          * is probably useless, because plain LZMA should provide better
 136          * results.
 137          *
 138          * Due to above reasons, it was decided to keep the implementation
 139          * of the RLE very simple. When the rle variable is non-zero, it
 140          * subblock_data_size must be a multiple of rle. Once the Subblock
 141          * encoder has got subblock_data_size bytes of input, it will check
 142          * if the whole buffer of the last subblock_data_size can be
 143          * represented with repeats of chunks having size of rle bytes.
 144          *
 145          * If there are consecutive identical buffers of subblock_data_size
 146          * bytes, they will be encoded using a single repeat entry if
 147          * possible.
 148          *
 149          * If need arises, more advanced RLE can be implemented later
 150          * without breaking API or ABI.
 151          */
 152         uint32_t rle;
 153 #       define LZMA_SUBBLOCK_RLE_OFF 0
 154 #       define LZMA_SUBBLOCK_RLE_MIN 1
 155 #       define LZMA_SUBBLOCK_RLE_MAX 256
 156
 157         /**
 158          * \brief       Subfilter remote control
 159          *
 160          * When the Subblock filter is initialized, this variable must be
 161          * LZMA_SUBFILTER_NONE or LZMA_SUBFILTER_SET.
 162          *
 163          * When subfilter_mode is LZMA_SUBFILTER_NONE, the application may
 164          * put Subfilter options to subfilter_options structure, and then
 165          * set subfilter_mode to LZMA_SUBFILTER_SET. No new input data will
 166          * be read until the Subfilter has been enabled. Once the Subfilter
 167          * has been enabled, liblzma will set subfilter_mode to
 168          * LZMA_SUBFILTER_RUN.
 169          *
 170          * When subfilter_mode is LZMA_SUBFILTER_RUN, the application may
 171          * set subfilter_mode to LZMA_SUBFILTER_FINISH. All the input
 172          * currently available will be encoded before unsetting the
 173          * Subfilter. Application must not change the amount of available
 174          * input until the Subfilter has finished. Once the Subfilter has
 175          * finished, liblzma will set subfilter_mode to LZMA_SUBFILTER_NONE.
 176          *
 177          * If the intent is to have Subfilter enabled to the very end of
 178          * the data, it is not needed to separately disable Subfilter with
 179          * LZMA_SUBFILTER_FINISH. Using LZMA_FINISH as the second argument
 180          * of lzma_code() will make the Subblock encoder to disable the
 181          * Subfilter once all the data has been ran through the Subfilter.
 182          *
 183          * After the first call with LZMA_SYNC_FLUSH or LZMA_FINISH, the
 184          * application must not change subfilter_mode until LZMA_STREAM_END.
 185          * Setting LZMA_SUBFILTER_SET/LZMA_SUBFILTER_FINISH and
 186          * LZMA_SYNC_FLUSH/LZMA_FINISH _at the same time_ is fine.
 187          *
 188          * \note        This variable is ignored if allow_subfilters is false.
 189          */
 190         lzma_subfilter_mode subfilter_mode;
 191
 192         /**
 193          * \brief       Subfilter and its options
 194          *
 195          * When no Subfilter is used, the data is copied as is into Subblocks.
 196          * Setting a Subfilter allows encoding some parts of the data with
 197          * an additional filter. It is possible to many different Subfilters
 198          * in the same Block, although only one can be used at once.
 199          *
 200          * \note        This variable is ignored if allow_subfilters is false.
 201          */
 202         lzma_options_filter subfilter_options;
 203
 204 } lzma_options_subblock;