| /** |
| * \file lzma/subblock.h |
| * \brief Subblock filter |
| */ |
| |
| /* |
| * Author: Lasse Collin |
| * |
| * This file has been put into the public domain. |
| * You can do whatever you want with this file. |
| * |
| * See ../lzma.h for information about liblzma as a whole. |
| */ |
| |
| #ifndef LZMA_H_INTERNAL |
| # error Never include this file directly. Use <lzma.h> instead. |
| #endif |
| |
| |
| /** |
| * \brief Filter ID |
| * |
| * Filter ID of the Subblock filter. This is used as lzma_filter.id. |
| */ |
| #define LZMA_FILTER_SUBBLOCK LZMA_VLI_C(0x01) |
| |
| |
| /** |
| * \brief Subfilter mode |
| * |
| * See lzma_options_subblock.subfilter_mode for details. |
| */ |
| typedef enum { |
| LZMA_SUBFILTER_NONE, |
| /**< |
| * No Subfilter is in use. |
| */ |
| |
| LZMA_SUBFILTER_SET, |
| /**< |
| * New Subfilter has been requested to be initialized. |
| */ |
| |
| LZMA_SUBFILTER_RUN, |
| /**< |
| * Subfilter is active. |
| */ |
| |
| LZMA_SUBFILTER_FINISH |
| /**< |
| * Subfilter has been requested to be finished. |
| */ |
| } lzma_subfilter_mode; |
| |
| |
| /** |
| * \brief Options for the Subblock filter |
| * |
| * Specifying options for the Subblock filter is optional: if the pointer |
| * options is NULL, no subfilters are allowed and the default value is used |
| * for subblock_data_size. |
| */ |
| typedef struct { |
| /* Options for encoder and decoder */ |
| |
| /** |
| * \brief Allowing subfilters |
| * |
| * If this true, subfilters are allowed. |
| * |
| * In the encoder, if this is set to false, subfilter_mode and |
| * subfilter_options are completely ignored. |
| */ |
| lzma_bool allow_subfilters; |
| |
| /* Options for encoder only */ |
| |
| /** |
| * \brief Alignment |
| * |
| * The Subblock filter encapsulates the input data into Subblocks. |
| * Each Subblock has a header which takes a few bytes of space. |
| * When the output of the Subblock encoder is fed to another filter |
| * that takes advantage of the alignment of the input data (e.g. LZMA), |
| * the Subblock filter can add padding to keep the actual data parts |
| * in the Subblocks aligned correctly. |
| * |
| * The alignment should be a positive integer. Subblock filter will |
| * add enough padding between Subblocks so that this is true for |
| * every payload byte: |
| * input_offset % alignment == output_offset % alignment |
| * |
| * The Subblock filter assumes that the first output byte will be |
| * written to a position in the output stream that is properly |
| * aligned. This requirement is automatically met when the start |
| * offset of the Stream or Block is correctly told to Block or |
| * Stream encoder. |
| */ |
| uint32_t alignment; |
| # define LZMA_SUBBLOCK_ALIGNMENT_MIN 1 |
| # define LZMA_SUBBLOCK_ALIGNMENT_MAX 32 |
| # define LZMA_SUBBLOCK_ALIGNMENT_DEFAULT 4 |
| |
| /** |
| * \brief Size of the Subblock Data part of each Subblock |
| * |
| * This value is re-read every time a new Subblock is started. |
| * |
| * Bigger values |
| * - save a few bytes of space; |
| * - increase latency in the encoder (but no effect for decoding); |
| * - decrease memory locality (increased cache pollution) in the |
| * encoder (no effect in decoding). |
| */ |
| uint32_t subblock_data_size; |
| # define LZMA_SUBBLOCK_DATA_SIZE_MIN 1 |
| # define LZMA_SUBBLOCK_DATA_SIZE_MAX (UINT32_C(1) << 28) |
| # define LZMA_SUBBLOCK_DATA_SIZE_DEFAULT 4096 |
| |
| /** |
| * \brief Run-length encoder remote control |
| * |
| * The Subblock filter has an internal run-length encoder (RLE). It |
| * can be useful when the data includes byte sequences that repeat |
| * very many times. The RLE can be used also when a Subfilter is |
| * in use; the RLE will be applied to the output of the Subfilter. |
| * |
| * Note that in contrast to traditional RLE, this RLE is intended to |
| * be used only when there's a lot of data to be repeated. If the |
| * input data has e.g. 500 bytes of NULs now and then, this RLE |
| * is probably useless, because plain LZMA should provide better |
| * results. |
| * |
| * Due to above reasons, it was decided to keep the implementation |
| * of the RLE very simple. When the rle variable is non-zero, it |
| * subblock_data_size must be a multiple of rle. Once the Subblock |
| * encoder has got subblock_data_size bytes of input, it will check |
| * if the whole buffer of the last subblock_data_size can be |
| * represented with repeats of chunks having size of rle bytes. |
| * |
| * If there are consecutive identical buffers of subblock_data_size |
| * bytes, they will be encoded using a single repeat entry if |
| * possible. |
| * |
| * If need arises, more advanced RLE can be implemented later |
| * without breaking API or ABI. |
| */ |
| uint32_t rle; |
| # define LZMA_SUBBLOCK_RLE_OFF 0 |
| # define LZMA_SUBBLOCK_RLE_MIN 1 |
| # define LZMA_SUBBLOCK_RLE_MAX 256 |
| |
| /** |
| * \brief Subfilter remote control |
| * |
| * When the Subblock filter is initialized, this variable must be |
| * LZMA_SUBFILTER_NONE or LZMA_SUBFILTER_SET. |
| * |
| * When subfilter_mode is LZMA_SUBFILTER_NONE, the application may |
| * put Subfilter options to subfilter_options structure, and then |
| * set subfilter_mode to LZMA_SUBFILTER_SET. No new input data will |
| * be read until the Subfilter has been enabled. Once the Subfilter |
| * has been enabled, liblzma will set subfilter_mode to |
| * LZMA_SUBFILTER_RUN. |
| * |
| * When subfilter_mode is LZMA_SUBFILTER_RUN, the application may |
| * set subfilter_mode to LZMA_SUBFILTER_FINISH. All the input |
| * currently available will be encoded before unsetting the |
| * Subfilter. Application must not change the amount of available |
| * input until the Subfilter has finished. Once the Subfilter has |
| * finished, liblzma will set subfilter_mode to LZMA_SUBFILTER_NONE. |
| * |
| * If the intent is to have Subfilter enabled to the very end of |
| * the data, it is not needed to separately disable Subfilter with |
| * LZMA_SUBFILTER_FINISH. Using LZMA_FINISH as the second argument |
| * of lzma_code() will make the Subblock encoder to disable the |
| * Subfilter once all the data has been ran through the Subfilter. |
| * |
| * After the first call with LZMA_SYNC_FLUSH or LZMA_FINISH, the |
| * application must not change subfilter_mode until LZMA_STREAM_END. |
| * Setting LZMA_SUBFILTER_SET/LZMA_SUBFILTER_FINISH and |
| * LZMA_SYNC_FLUSH/LZMA_FINISH _at the same time_ is fine. |
| * |
| * \note This variable is ignored if allow_subfilters is false. |
| */ |
| lzma_subfilter_mode subfilter_mode; |
| |
| /** |
| * \brief Subfilter and its options |
| * |
| * When no Subfilter is used, the data is copied as is into Subblocks. |
| * Setting a Subfilter allows encoding some parts of the data with |
| * an additional filter. It is possible to many different Subfilters |
| * in the same Block, although only one can be used at once. |
| * |
| * \note This variable is ignored if allow_subfilters is false. |
| */ |
| lzma_filter subfilter_options; |
| |
| } lzma_options_subblock; |