2 * \file lzma/subblock.h
3 * \brief Subblock filter
5 * \author Copyright (C) 1999-2006 Igor Pavlov
6 * \author Copyright (C) 2007 Lasse Collin
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.
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.
19 #ifndef LZMA_H_INTERNAL
20 # error Never include this file directly. Use <lzma.h> instead.
27 * Filter ID of the Subblock filter. This is used as lzma_options_filter.id.
29 #define LZMA_FILTER_SUBBLOCK LZMA_VLI_C(0x01)
33 * \brief Subfilter mode
35 * See lzma_options_subblock.subfilter_mode for details.
40 * No Subfilter is in use.
45 * New Subfilter has been requested to be initialized.
50 * Subfilter is active.
55 * Subfilter has been requested to be finished.
57 } lzma_subfilter_mode;
61 * \brief Options for the Subblock filter
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.
68 /* Options for encoder and decoder */
71 * \brief Allowing subfilters
73 * If this true, subfilters are allowed.
75 * In the encoder, if this is set to false, subfilter_mode and
76 * subfilter_options are completely ignored.
78 lzma_bool allow_subfilters;
80 /* Options for encoder only */
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.
92 * The alignment should be a positive integer. Subblock filter will
93 * add enough padding between Subblocks so that this is true for
95 * input_offset % alignment == output_offset % alignment
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
104 # define LZMA_SUBBLOCK_ALIGNMENT_MIN 1
105 # define LZMA_SUBBLOCK_ALIGNMENT_MAX 32
106 # define LZMA_SUBBLOCK_ALIGNMENT_DEFAULT 4
109 * \brief Size of the Subblock Data part of each Subblock
111 * This value is re-read every time a new Subblock is started.
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).
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
125 * \brief Run-length encoder remote control
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.
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
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.
145 * If there are consecutive identical buffers of subblock_data_size
146 * bytes, they will be encoded using a single repeat entry if
149 * If need arises, more advanced RLE can be implemented later
150 * without breaking API or ABI.
153 # define LZMA_SUBBLOCK_RLE_OFF 0
154 # define LZMA_SUBBLOCK_RLE_MIN 1
155 # define LZMA_SUBBLOCK_RLE_MAX 256
158 * \brief Subfilter remote control
160 * When the Subblock filter is initialized, this variable must be
161 * LZMA_SUBFILTER_NONE or LZMA_SUBFILTER_SET.
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.
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.
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.
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.
188 * \note This variable is ignored if allow_subfilters is false.
190 lzma_subfilter_mode subfilter_mode;
193 * \brief Subfilter and its options
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.
200 * \note This variable is ignored if allow_subfilters is false.
202 lzma_options_filter subfilter_options;
204 } lzma_options_subblock;