aboutsummaryrefslogtreecommitdiff
path: root/src/liblzma/api/lzma/container.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/liblzma/api/lzma/container.h')
-rw-r--r--src/liblzma/api/lzma/container.h76
1 files changed, 38 insertions, 38 deletions
diff --git a/src/liblzma/api/lzma/container.h b/src/liblzma/api/lzma/container.h
index 800f2129..ba2c4f8f 100644
--- a/src/liblzma/api/lzma/container.h
+++ b/src/liblzma/api/lzma/container.h
@@ -26,30 +26,42 @@
************/
/**
- * \brief Default compression level for easy encoder
+ * \brief Default compression preset
*
- * It's not straightforward to recommend a default level, because in some
+ * It's not straightforward to recommend a default preset, because in some
* cases keeping the resource usage relatively low is more important that
* getting the maximum compression ratio.
*/
-#define LZMA_EASY_LEVEL_DEFAULT 6
+#define LZMA_PRESET_DEFAULT UINT32_C(6)
+
+
+/**
+ * \brief Mask for preset level
+ *
+ * This is useful only if you need to extract the level from the preset
+ * variable. That should be rare.
+ */
+#define LZMA_PRESET_LEVEL_MASK UINT32_C(0x1F)
/*
- * Flags for easy encoder
+ * Preset flags
*
* Currently only one flag is defined.
*/
/**
- * Use significantly slower compression to get marginally better compression
- * ratio. This doesn't affect the memory requirements of the encoder or
- * decoder. This flag is useful when you don't mind wasting time to get as
- * small result as possible.
+ * \brief Extreme compression preset
+ *
+ * This flag modifies the preset to make the encoding significantly slower
+ * while improving the compression ratio only marginally. This is useful
+ * when you don't mind wasting time to get as small result as possible.
*
- * FIXME: Not implemented yet.
+ * This flag doesn't affect the memory usage requirements of the decoder (at
+ * least not significantly). The memory usage of the encoder may be increased
+ * a little but only at the lowest preset levels (0-4 or so).
*/
-#define LZMA_EASY_EXTREME UINT32_C(0x01)
+#define LZMA_PRESET_EXTREME (UINT32_C(1) << 31)
/**
@@ -57,12 +69,9 @@
*
* This function is a wrapper for lzma_raw_encoder_memusage().
*
- * \param level Compression level
- * \param flags Easy encoder flags (usually zero). This parameter is
- * needed, because in future some flags may affect the
- * memory requirements.
+ * \param preset Compression preset (level and possible flags)
*/
-extern uint64_t lzma_easy_encoder_memusage(uint32_t level, uint32_t flags)
+extern uint64_t lzma_easy_encoder_memusage(uint32_t preset)
lzma_attr_pure;
@@ -71,12 +80,9 @@ extern uint64_t lzma_easy_encoder_memusage(uint32_t level, uint32_t flags)
*
* This function is a wrapper for lzma_raw_decoder_memusage().
*
- * \param level Compression level
- * \param flags Easy encoder flags (usually zero). This parameter is
- * needed, because in future some flags may affect the
- * memory requirements.
+ * \param preset Compression preset (level and possible flags)
*/
-extern uint64_t lzma_easy_decoder_memusage(uint32_t level, uint32_t flags)
+extern uint64_t lzma_easy_decoder_memusage(uint32_t preset)
lzma_attr_pure;
@@ -88,14 +94,12 @@ extern uint64_t lzma_easy_decoder_memusage(uint32_t level, uint32_t flags)
*
* \param strm Pointer to lzma_stream that is at least initialized
* with LZMA_STREAM_INIT.
- * \param level Compression level to use. This selects a set of
- * compression settings from a list of compression
- * presets. Currently levels from 1 to 9 are defined,
- * which match the options -1 .. -9 of the xz command
- * line tool.
- * \param flags Flags that can finetune the compression preset.
- * In most cases, no flags are wanted, and this
- * parameter is zero.
+ * \param preset Compression preset to use. A preset consist of level
+ * number and zero or more flags. Usually flags aren't
+ * used, so preset is simply a number [0, 9] which match
+ * the options -0 .. -9 of the xz command line tool.
+ * Additional flags can be be set using bitwise-or with
+ * the preset level number, e.g. 6 | LZMA_PRESET_EXTREME.
* \param check Integrity check type to use. See check.h for available
* checks. If you are unsure, use LZMA_CHECK_CRC32.
*
@@ -115,8 +119,8 @@ extern uint64_t lzma_easy_decoder_memusage(uint32_t level, uint32_t flags)
* LZMA_RUN, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, and LZMA_FINISH. In future,
* there may be compression levels or flags that don't support LZMA_SYNC_FLUSH.
*/
-extern lzma_ret lzma_easy_encoder(lzma_stream *strm,
- uint32_t level, uint32_t flags, lzma_check check)
+extern lzma_ret lzma_easy_encoder(
+ lzma_stream *strm, uint32_t preset, lzma_check check)
lzma_attr_warn_unused_result;
@@ -125,10 +129,8 @@ extern lzma_ret lzma_easy_encoder(lzma_stream *strm,
*
* \param strm Pointer to properly prepared lzma_stream
* \param filters Array of filters. This must be terminated with
- * filters[n].id = LZMA_VLI_UNKNOWN. There must
- * be 1-4 filters, but there are restrictions on how
- * multiple filters can be combined. FIXME Tell where
- * to find more information.
+ * filters[n].id = LZMA_VLI_UNKNOWN. See filter.h for
+ * more information.
* \param check Type of the integrity check to calculate from
* uncompressed data.
*
@@ -153,15 +155,13 @@ extern lzma_ret lzma_stream_encoder(lzma_stream *strm,
* legacy LZMA tools such as LZMA Utils 4.32.x. Moving to the .xz format
* is strongly recommended.
*
- * FIXME: Dictionary size limit?
- *
* The valid action values for lzma_code() are LZMA_RUN and LZMA_FINISH.
* No kind of flushing is supported, because the file format doesn't make
* it possible.
*
* \return - LZMA_OK
* - LZMA_MEM_ERROR
- * - LZMA_OPTIONS_ERROR // FIXME
+ * - LZMA_OPTIONS_ERROR
* - LZMA_PROG_ERROR
*/
extern lzma_ret lzma_alone_encoder(
@@ -252,7 +252,7 @@ extern lzma_ret lzma_auto_decoder(
/**
- * \brief Initializes decoder for .lzma file
+ * \brief Initialize .lzma decoder (legacy file format)
*
* Valid `action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH.
* There is no need to use LZMA_FINISH, but allowing it may simplify