lzma_options_subblock Struct Reference

Options for the Subblock filter. More...

#include <subblock.h>

Data Fields

lzma_bool allow_subfilters
 Allowing subfilters.
uint32_t alignment
 Alignment.
uint32_t subblock_data_size
 Size of the Subblock Data part of each Subblock.
uint32_t rle
 Run-length encoder remote control.
lzma_subfilter_mode subfilter_mode
 Subfilter remote control.
lzma_filter subfilter_options
 Subfilter and its options.

Detailed Description

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.


Field Documentation

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.

Referenced by options_subblock().

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.

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).

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.

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.

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.

The documentation for this struct was generated from the following file:

Generated on Mon Dec 21 22:54:41 2009 for XZ Utils by  doxygen 1.6.1