diff options
Diffstat (limited to 'Build/source/extra/xz/src/liblzma/api/lzma/filter.h')
-rw-r--r-- | Build/source/extra/xz/src/liblzma/api/lzma/filter.h | 51 |
1 files changed, 25 insertions, 26 deletions
diff --git a/Build/source/extra/xz/src/liblzma/api/lzma/filter.h b/Build/source/extra/xz/src/liblzma/api/lzma/filter.h index 038a93398c6..efd036f7f04 100644 --- a/Build/source/extra/xz/src/liblzma/api/lzma/filter.h +++ b/Build/source/extra/xz/src/liblzma/api/lzma/filter.h @@ -1,6 +1,6 @@ /** * \file lzma/filter.h - * \brief Common filter related types + * \brief Common filter related types and functions */ /* @@ -59,11 +59,6 @@ typedef struct { * If the filter doesn't need options, set this to NULL. If id is * set to LZMA_VLI_UNKNOWN, options is ignored, and thus * doesn't need be initialized. - * - * Some filters support changing the options in the middle of - * the encoding process. These filters store the pointer of the - * options structure and communicate with the application via - * modifications of the options structure. */ void *options; @@ -126,15 +121,16 @@ extern LZMA_API(lzma_ret) lzma_filters_copy(const lzma_filter *src, /** - * \brief Calculate rough memory requirements for raw encoder + * \brief Calculate approximate memory requirements for raw encoder * - * Because the calculation is rough, this function can be used to calculate - * the memory requirements for Block and Stream encoders too. + * This function can be used to calculate the memory requirements for + * Block and Stream encoders too because Block and Stream encoders don't + * need significantly more memory than raw encoder. * * \param filters Array of filters terminated with * .id == LZMA_VLI_UNKNOWN. * - * \return Rough number of bytes of memory required for the given + * \return Number of bytes of memory required for the given * filter chain when encoding. */ extern LZMA_API(uint64_t) lzma_raw_encoder_memusage(const lzma_filter *filters) @@ -142,15 +138,16 @@ extern LZMA_API(uint64_t) lzma_raw_encoder_memusage(const lzma_filter *filters) /** - * \brief Calculate rough memory requirements for raw decoder + * \brief Calculate approximate memory requirements for raw decoder * - * Because the calculation is rough, this function can be used to calculate - * the memory requirements for Block and Stream decoders too. + * This function can be used to calculate the memory requirements for + * Block and Stream decoders too because Block and Stream decoders don't + * need significantly more memory than raw decoder. * * \param filters Array of filters terminated with * .id == LZMA_VLI_UNKNOWN. * - * \return Rough number of bytes of memory required for the given + * \return Number of bytes of memory required for the given * filter chain when decoding. */ extern LZMA_API(uint64_t) lzma_raw_decoder_memusage(const lzma_filter *filters) @@ -251,7 +248,8 @@ extern LZMA_API(lzma_ret) lzma_filters_update( * * \note There is no function to calculate how big output buffer * would surely be big enough. (lzma_stream_buffer_bound() - * works only for lzma_stream_buffer_encode().) + * works only for lzma_stream_buffer_encode(); raw encoder + * won't necessarily meet that bound.) */ extern LZMA_API(lzma_ret) lzma_raw_buffer_encode( const lzma_filter *filters, lzma_allocator *allocator, @@ -323,9 +321,10 @@ extern LZMA_API(lzma_ret) lzma_properties_size( * succeeds but using the same options to initialize the encoder * will fail. * - * \note It is OK to skip calling this function if - * lzma_properties_size() indicated that the size - * of the Filter Properties field is zero. + * \note If lzma_properties_size() indicated that the size + * of the Filter Properties field is zero, calling + * lzma_properties_encode() is not required, but it + * won't do any harm either. */ extern LZMA_API(lzma_ret) lzma_properties_encode( const lzma_filter *filter, uint8_t *props) lzma_nothrow; @@ -364,11 +363,11 @@ extern LZMA_API(lzma_ret) lzma_properties_decode( * memory to hold the encoded Filter Flags. * * \param size Pointer to integer to hold the calculated size - * \param filters Filter ID and associated options whose encoded + * \param filter Filter ID and associated options whose encoded * size is to be calculated * * \return - LZMA_OK: *size set successfully. Note that this doesn't - * guarantee that filters->options is valid, thus + * guarantee that filter->options is valid, thus * lzma_filter_flags_encode() may still fail. * - LZMA_OPTIONS_ERROR: Unknown Filter ID or unsupported options. * - LZMA_PROG_ERROR: Invalid options @@ -377,7 +376,7 @@ extern LZMA_API(lzma_ret) lzma_properties_decode( * you need to loop over every lzma_filter entry. */ extern LZMA_API(lzma_ret) lzma_filter_flags_size( - uint32_t *size, const lzma_filter *filters) + uint32_t *size, const lzma_filter *filter) lzma_nothrow lzma_attr_warn_unused_result; @@ -387,7 +386,7 @@ extern LZMA_API(lzma_ret) lzma_filter_flags_size( * In contrast to some functions, this doesn't allocate the needed buffer. * This is due to how this function is used internally by liblzma. * - * \param filters Filter ID and options to be encoded + * \param filter Filter ID and options to be encoded * \param out Beginning of the output buffer * \param out_pos out[*out_pos] is the next write position. This * is updated by the encoder. @@ -399,7 +398,7 @@ extern LZMA_API(lzma_ret) lzma_filter_flags_size( * buffer space (you should have checked it with * lzma_filter_flags_size()). */ -extern LZMA_API(lzma_ret) lzma_filter_flags_encode(const lzma_filter *filters, +extern LZMA_API(lzma_ret) lzma_filter_flags_encode(const lzma_filter *filter, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow lzma_attr_warn_unused_result; @@ -407,8 +406,8 @@ extern LZMA_API(lzma_ret) lzma_filter_flags_encode(const lzma_filter *filters, /** * \brief Decode Filter Flags from given buffer * - * The decoded result is stored into *filters. filters->options is - * initialized but the old value is NOT free()d. + * The decoded result is stored into *filter. The old value of + * filter->options is not free()d. * * \return - LZMA_OK * - LZMA_OPTIONS_ERROR @@ -416,6 +415,6 @@ extern LZMA_API(lzma_ret) lzma_filter_flags_encode(const lzma_filter *filters, * - LZMA_PROG_ERROR */ extern LZMA_API(lzma_ret) lzma_filter_flags_decode( - lzma_filter *filters, lzma_allocator *allocator, + lzma_filter *filter, lzma_allocator *allocator, const uint8_t *in, size_t *in_pos, size_t in_size) lzma_nothrow lzma_attr_warn_unused_result; |