encode.h(3)

📦
version 1.2.1 · 2 versions
, in alpine 3.23, alpine 3.24, arch rolling, nixos 26.05, nixpkgs unstable

✨ NAME ✨

okay so this is encode.h — the API for Brotli compression. You're reading encode.h(3), the library functions manual, and it's giving main character energy. 💅 No cap, this is the bestie guide to Brotli encoding.

🦋 SYNOPSIS 🦋

Macros

  • #define BROTLI_DEFAULT_MODE BROTLI_MODE_GENERIC — the default vibe for the BROTLI_PARAM_MODE parameter. ✨
  • #define BROTLI_DEFAULT_QUALITY 11 — the default value for the BROTLI_PARAM_QUALITY parameter. 💖
  • #define BROTLI_DEFAULT_WINDOW 22 — the default value for the BROTLI_PARAM_LGWIN parameter. 🌸
  • #define BROTLI_LARGE_MAX_WINDOW_BITS 30 — the maximal value for the BROTLI_PARAM_LGWIN parameter in 'Large Window Brotli' (32-bit). 👑
  • #define BROTLI_MAX_INPUT_BLOCK_BITS 24 — the maximal value for the BROTLI_PARAM_LGBLOCK parameter. 🔥
  • #define BROTLI_MAX_QUALITY 11 — the maximal value for the BROTLI_PARAM_QUALITY parameter. 💯
  • #define BROTLI_MAX_WINDOW_BITS 24 — the maximal value for the BROTLI_PARAM_LGWIN parameter. 🦋
  • #define BROTLI_MIN_INPUT_BLOCK_BITS 16 — the minimal value for the BROTLI_PARAM_LGBLOCK parameter. 🥺
  • #define BROTLI_MIN_QUALITY 0 — the minimal value for the BROTLI_PARAM_QUALITY parameter. 🙈
  • #define BROTLI_MIN_WINDOW_BITS 10 — the minimal value for the BROTLI_PARAM_LGWIN parameter. 💅

Typedefs

  • typedef enum BrotliEncoderMode BrotliEncoderMode — the options for the BROTLI_PARAM_MODE parameter. 🎀
  • typedef enum BrotliEncoderOperation BrotliEncoderOperation — the operations that can be performed by the streaming encoder. 🌈
  • typedef enum BrotliEncoderParameter BrotliEncoderParameter — the options to be used with BrotliEncoderSetParameter. ⭐
  • typedef struct BrotliEncoderStateStruct BrotliEncoderState — an opaque structure that holds the encoder state. 💜

Enumerations

(no enumerators listed here, bestie — just vibes)

Functions

  • BROTLI_BOOL BrotliEncoderAttachPreparedDictionary (BrotliEncoderState *state, const BrotliEncoderPreparedDictionary *dictionary) — attaches a prepared dictionary of any type to the encoder. 🫶
  • BROTLI_BOOL BrotliEncoderCompress (int quality, int lgwin, BrotliEncoderMode mode, size_t input_size, const uint8_t input_buffer[input_size], size_t *encoded_size, uint8_t encoded_buffer[*encoded_size]) — performs one-shot memory-to-memory compression. 🧚
  • BROTLI_BOOL BrotliEncoderCompressStream (BrotliEncoderState *state, BrotliEncoderOperation op, size_t *available_in, const uint8_t **next_in, size_t *available_out, uint8_t **next_out, size_t *total_out) — compresses an input stream to an output stream. 🌊
  • BrotliEncoderState * BrotliEncoderCreateInstance (brotli_alloc_func alloc_func, brotli_free_func free_func, void *opaque) — creates an instance of BrotliEncoderState and initializes it. ✨
  • void BrotliEncoderDestroyInstance (BrotliEncoderState *state) — deinitializes and frees a BrotliEncoderState instance. 💀
  • BROTLI_BOOL BrotliEncoderHasMoreOutput (BrotliEncoderState *state) — checks if the encoder has more output. 🔍
  • BROTLI_BOOL BrotliEncoderIsFinished (BrotliEncoderState *state) — checks if the encoder instance reached the final state. 🏁
  • size_t BrotliEncoderMaxCompressedSize (size_t input_size) — calculates the output size bound for the given input_size. 📏
  • BrotliEncoderPreparedDictionary * BrotliEncoderPrepareDictionary (BrotliSharedDictionaryType type, size_t data_size, const uint8_t data[data_size], int quality, brotli_alloc_func alloc_func, brotli_free_func free_func, void *opaque) — prepares a shared dictionary from the given file format for the encoder. 📚
  • BROTLI_BOOL BrotliEncoderSetParameter (BrotliEncoderState *state, BrotliEncoderParameter param, uint32_t value) — sets the specified parameter to the given encoder instance. 🎛️
  • const uint8_t * BrotliEncoderTakeOutput (BrotliEncoderState *state, size_t *size) — acquires a pointer to the internal output buffer. 📤
  • uint32_t BrotliEncoderVersion (void) — gets an encoder library version. 🔢

📖 Detailed Description 📖

API for Brotli compression. That's the whole vibe, bestie. 💅

🔧 Macro Definition Documentation 🔧

#define BROTLI_DEFAULT_MODE BROTLI_MODE_GENERIC

This is the default value for the BROTLI_PARAM_MODE parameter. 💅

#define BROTLI_DEFAULT_QUALITY 11

This is the default value for the BROTLI_PARAM_QUALITY parameter. 💖

#define BROTLI_DEFAULT_WINDOW 22

This is the default value for the BROTLI_PARAM_LGWIN parameter. 🌸

#define BROTLI_MAX_INPUT_BLOCK_BITS 24

This is the maximal value for the BROTLI_PARAM_LGBLOCK parameter. 🔥

#define BROTLI_MAX_QUALITY 11

This is the maximal value for the BROTLI_PARAM_QUALITY parameter. 💯

#define BROTLI_MAX_WINDOW_BITS 24

This is the maximal value for the BROTLI_PARAM_LGWIN parameter. 🦋

Note: equal to the BROTLI_MAX_DISTANCE_BITS constant.

#define BROTLI_MIN_INPUT_BLOCK_BITS 16

This is the minimal value for the BROTLI_PARAM_LGBLOCK parameter. 🥺

#define BROTLI_MIN_QUALITY 0

This is the minimal value for the BROTLI_PARAM_QUALITY parameter. 🙈

#define BROTLI_MIN_WINDOW_BITS 10

This is the minimal value for the BROTLI_PARAM_LGWIN parameter. 💅

🧬 Typedef Documentation 🧬

typedef enum BrotliEncoderMode BrotliEncoderMode

These are the options for the BROTLI_PARAM_MODE parameter. 🎀

typedef enum BrotliEncoderOperation BrotliEncoderOperation

These are the operations that can be performed by the streaming encoder. 🌈

typedef enum BrotliEncoderParameter BrotliEncoderParameter

These are the options to be used with BrotliEncoderSetParameter. ⭐

typedef struct BrotliEncoderStateStruct BrotliEncoderState

An opaque structure that holds the encoder state. It's allocated and initialized with BrotliEncoderCreateInstance. It's cleaned up and deallocated with BrotliEncoderDestroyInstance. 💜

🌈 Enumeration Type Documentation 🌈

enum BrotliEncoderMode

Options for the BROTLI_PARAM_MODE parameter. 🎀

Enumerator

  • BROTLI_MODE_GENERIC — the default compression mode. In this mode, the compressor does not know anything in advance about the properties of the input. 🤷‍♀️
  • BROTLI_MODE_TEXT — the compression mode for UTF-8 formatted text input. 📝
  • BROTLI_MODE_FONT — the compression mode used in WOFF 2.0. 🔤

enum BrotliEncoderOperation

Operations that can be performed by the streaming encoder. 🌈

Enumerator

  • BROTLI_OPERATION_PROCESS — process input. The encoder may postpone producing output until it has processed enough input. ⏳
  • BROTLI_OPERATION_FLUSH — produce output for all processed input. The actual flush is performed when the input stream is depleted and there is enough space in the output stream. This means that the client should repeat the BROTLI_OPERATION_FLUSH operation until available_in becomes 0, and BrotliEncoderHasMoreOutput returns BROTLI_FALSE. If output is acquired via BrotliEncoderTakeOutput, then the operation should be repeated after the output buffer is drained. 🚽
Warning: Until flush is complete, the client SHOULD NOT swap, reduce or extend the input stream. 🛑

When flush is complete, the output data will be sufficient for the decoder to reproduce all the given input. ✨

  • BROTLI_OPERATION_FINISH — finalize the stream. The actual finalization is performed when the input stream is depleted and there is enough space in the output stream. This means that the client should repeat the BROTLI_OPERATION_FINISH operation until available_in becomes 0, and BrotliEncoderHasMoreOutput returns BROTLI_FALSE. If output is acquired via BrotliEncoderTakeOutput, then the operation should be repeated after the output buffer is drained. 🏁
Warning: Until finalization is complete, the client SHOULD NOT swap, reduce or extend the input stream. 🛑

The helper function BrotliEncoderIsFinished checks if the stream is finalized and the output is fully dumped. 🔍

Adding more input data to a finalized stream is impossible. 🚫

  • BROTLI_OPERATION_EMIT_METADATA — emit a metadata block to the stream. Metadata is opaque to Brotli: neither the encoder nor the decoder processes this data or relies on it. It may be used to pass some extra information from the encoder client to the decoder client without interfering with the main data stream. 📦
Note: The encoder may emit empty metadata blocks internally, to pad the encoded stream to a byte boundary. 📏
Warning: Until emitting metadata is complete, the client SHOULD NOT swap, reduce or extend the input stream. 🛑 The whole content of the input buffer is considered to be the content of the metadata block. Do NOT append metadata to the input stream before it is depleted with other operations. 🚫

The stream is soft-flushed before the metadata block is emitted. The metadata block MUST be no longer than than 16MiB. 📦

enum BrotliEncoderParameter

Options to be used with BrotliEncoderSetParameter. ⭐

Enumerator

  • BROTLI_PARAM_MODE — tune the encoder for a specific input. BrotliEncoderMode enumerates all available values. 🎛️
  • BROTLI_PARAM_QUALITY — the main compression speed-density lever. The higher the quality, the slower the compression. The range is from BROTLI_MIN_QUALITY to BROTLI_MAX_QUALITY. ⚖️
  • BROTLI_PARAM_LGWIN — recommended sliding LZ77 window size. The encoder may reduce this value, e.g. if the input is much smaller than the window size. 🪟

Window size is (1 << value) - 16.

The range is from BROTLI_MIN_WINDOW_BITS to BROTLI_MAX_WINDOW_BITS. 📐

  • BROTLI_PARAM_LGBLOCK — recommended input block size. The encoder may reduce this value, e.g. if the input is much smaller than the input block size. 🧱

The range is from BROTLI_MIN_INPUT_BLOCK_BITS to BROTLI_MAX_INPUT_BLOCK_BITS. 📏

Note: A bigger input block size allows better compression, but consumes more memory. 💾 The rough formula of memory used for temporary input storage is 3 << lgBlock. 🧮
  • BROTLI_PARAM_DISABLE_LITERAL_CONTEXT_MODELING — a flag that affects usage of the 'literal context modeling' format feature. This flag is a 'decoding-speed vs compression ratio' trade-off. ⚡
  • BROTLI_PARAM_SIZE_HINT — estimated total input size for all BrotliEncoderCompressStream calls. The default value is 0, which means that the total input size is unknown. 🤷‍♀️
  • BROTLI_PARAM_LARGE_WINDOW — a flag that determines if 'Large Window Brotli' is used. 🪟
  • BROTLI_PARAM_NPOSTFIX — recommended number of postfix bits (NPOSTFIX). The encoder may change this value. 🔢

The range is from 0 to BROTLI_MAX_NPOSTFIX. 📊

  • BROTLI_PARAM_NDIRECT — recommended number of direct distance codes (NDIRECT). The encoder may change this value. 📍

The range is from 0 to (15 << NPOSTFIX) in steps of (1 << NPOSTFIX). 🪜

  • BROTLI_PARAM_STREAM_OFFSET — number of bytes of input stream already processed by a different instance. 🔄
Note: It is important to configure all the encoder instances with the same parameters (except this one) in order to allow all the encoded parts to obey the same restrictions implied by the header. 📋

If the offset is not 0, then the stream header is omitted. In any case the output start is byte aligned, so for proper streams stitching the 'predecessor' stream must be flushed. 🧵

The range is not artificially limited, but all the values greater or equal to the maximal window size have the same effect. Values greater than 2**30 are not allowed. 🚫

🛠️ FUNCTION DOCUMENTATION 🛠️

okay bestie, this is the part where we meet the actual functions, and honestly? iconic behavior all around. let's go one by one, no skipping, no cap 💅

💖 BROTLI_BOOL BrotliEncoderAttachPreparedDictionary (BrotliEncoderState * state, const BrotliEncoderPreparedDictionary * dictionary)

BROTLI_BOOL BrotliEncoderAttachPreparedDictionary (BrotliEncoderState * state,
    const BrotliEncoderPreparedDictionary * dictionary)

Attaches a prepared dictionary of any type to the encoder, fr fr. And yes you can call this multiple times to attach multiple dictionaries — it's giving collect-them-all energy. The dictionary type was determined by BrotliEncoderPrepareDictionary. You can attach multiple raw prefix dictionaries and/or max 1 serialized dictionary with custom words. 🎀

Returns:

  • BROTLI_FALSE in case of error
  • BROTLI_TRUE otherwise

💖 BROTLI_BOOL BrotliEncoderCompress (int quality, int lgwin, BrotliEncoderMode mode, size_t input_size, const uint8_t input_buffer[input_size], size_t * encoded_size, uint8_t encoded_buffer[*encoded_size])

BROTLI_BOOL BrotliEncoderCompress (int quality, int lgwin, BrotliEncoderMode mode,
    size_t input_size, const uint8_t input_buffer[input_size], size_t * encoded_size,
    uint8_t encoded_buffer[*encoded_size])

Performs one-shot memory-to-memory compression — the "just do it all in one go" queen 👑. It compresses the data in input_buffer into encoded_buffer, and sets *encoded_size to the compressed length.

Note: if BrotliEncoderMaxCompressedSize(input_size) returns a non-zero value, then output is guaranteed to be no longer than that. ✨
Note: if lgwin is greater than BROTLI_MAX_WINDOW_BITS then the resulting stream might be incompatible with RFC 7932 😭 — to decode such streams, the decoder should be configured with BROTLI_DECODER_PARAM_LARGE_WINDOW = 1.

Parameters:

  • quality — quality parameter value, e.g. BROTLI_DEFAULT_QUALITY
  • lgwin — lgwin parameter value, e.g. BROTLI_DEFAULT_WINDOW
  • mode — mode parameter value, e.g. BROTLI_DEFAULT_MODE
  • input_size — size of input_buffer
  • input_buffer — input data buffer with at least input_size addressable bytes
  • encoded_size — in: size of encoded_buffer; out: length of compressed data written to encoded_buffer, or 0 if compression fails
  • encoded_buffer — compressed data destination buffer

Returns:

  • BROTLI_FALSE in case of compression error
  • BROTLI_FALSE if output buffer is too small
  • BROTLI_TRUE otherwise

💖 BROTLI_BOOL BrotliEncoderCompressStream (BrotliEncoderState * state, BrotliEncoderOperation op, size_t * available_in, const uint8_t ** next_in, size_t * available_out, uint8_t ** next_out, size_t * total_out)

BROTLI_BOOL BrotliEncoderCompressStream (BrotliEncoderState * state,
    BrotliEncoderOperation op, size_t * available_in, const uint8_t ** next_in,
    size_t * available_out, uint8_t ** next_out, size_t * total_out)

Compresses input stream to output stream — the streaming era main character 🌈. The values *available_in and *available_out must specify the number of bytes addressable at *next_in and *next_out respectively. When *available_out is 0, next_out is allowed to be NULL.

After each call, *available_in will be decremented by the amount of input bytes consumed, and the *next_in pointer will be incremented by that amount. Similarly, *available_out will be decremented by the amount of output bytes written, and the *next_out pointer will be incremented by that amount. Math is mathing 📐

total_out, if it is not a null-pointer, will be set to the number of bytes compressed since the last state initialization.

Internally the workflow consists of 3 tasks:

  1. (optionally) copy input data to internal buffer
  2. actually compress data and (optionally) store it to internal buffer
  3. (optionally) copy compressed bytes from internal buffer to output stream

Whenever all 3 tasks can't move forward anymore, or error occurs, this method returns the control flow to caller.

op is used to perform flush, finish the stream, or inject metadata block. See BrotliEncoderOperation for more information.

Flushing the stream means forcing encoding of all input passed to encoder and completing the current output block, so it could be fully decoded by stream decoder. To perform flush set op to BROTLI_OPERATION_FLUSH. Under some circumstances (e.g. lack of output stream capacity) this operation would require several calls to BrotliEncoderCompressStream. The method must be called again until both input stream is depleted and encoder has no more output (see BrotliEncoderHasMoreOutput) after the method is called.

Finishing the stream means encoding of all input passed to encoder and adding specific 'final' marks, so stream decoder could determine that stream is complete. To perform finish set op to BROTLI_OPERATION_FINISH. Under some circumstances (e.g. lack of output stream capacity) this operation would require several calls to BrotliEncoderCompressStream. The method must be called again until both input stream is depleted and encoder has no more output (see BrotliEncoderHasMoreOutput) after the method is called.

Warning: when flushing and finishing, op should not change until the operation is complete; input stream should not be swapped, reduced or extended as well. 🚨 do not touch, bestie, it's mid-transformation.

Parameters:

  • state — encoder instance
  • op — requested operation
  • available_in — in: amount of available input; out: amount of unused input
  • next_in — pointer to the next input byte
  • available_out — in: length of output buffer; out: remaining size of output buffer
  • next_out — compressed output buffer cursor; can be NULL if available_out is 0
  • total_out — number of bytes produced so far; can be NULL

Returns:

  • BROTLI_FALSE if there was an error
  • BROTLI_TRUE otherwise

💖 BrotliEncoderState* BrotliEncoderCreateInstance (brotli_alloc_func alloc_func, brotli_free_func free_func, void * opaque)

BrotliEncoderState* BrotliEncoderCreateInstance (brotli_alloc_func alloc_func,
    brotli_free_func free_func, void * opaque)

Creates an instance of BrotliEncoderState and initializes it — the birth of a legend, honestly 🦋. alloc_func and free_func MUST be both zero or both non-zero. In the case they are both zero, default memory allocators are used. opaque is passed to alloc_func and free_func when they are called. free_func has to return without doing anything when asked to free a NULL pointer.

Parameters:

  • alloc_func — custom memory allocation function
  • free_func — custom memory free function
  • opaque — custom memory manager handle

Returns:

  • 0 if instance can not be allocated or initialized
  • pointer to initialized BrotliEncoderState otherwise

💖 void BrotliEncoderDestroyInstance (BrotliEncoderState * state)

void BrotliEncoderDestroyInstance (BrotliEncoderState * state)

Deinitializes and frees BrotliEncoderState instance. it's giving closure, and we love that for it 💀✨

Parameters:

  • state — decoder instance to be cleaned up and deallocated

💖 BROTLI_BOOL BrotliEncoderHasMoreOutput (BrotliEncoderState * state)

BROTLI_BOOL BrotliEncoderHasMoreOutput (BrotliEncoderState * state)

Checks if encoder has more output. the vibe check function 🎀

Parameters:

  • state — encoder instance

Returns:

  • BROTLI_TRUE, if encoder has some unconsumed output
  • BROTLI_FALSE otherwise

💖 BROTLI_BOOL BrotliEncoderIsFinished (BrotliEncoderState * state)

BROTLI_BOOL BrotliEncoderIsFinished (BrotliEncoderState * state)

Checks if encoder instance reached the final state. are we done yet or nah 🔥

Parameters:

  • state — encoder instance

Returns:

  • BROTLI_TRUE if encoder is in a state where it reached the end of the input and produced all of the output
  • BROTLI_FALSE otherwise

💖 size_t BrotliEncoderMaxCompressedSize (size_t input_size)

size_t BrotliEncoderMaxCompressedSize (size_t input_size)

Calculates the output size bound for the given input_size. math girlies rise 💅

Warning: result is only valid if quality is at least 2 and, in case BrotliEncoderCompressStream was used, no flushes (BROTLI_OPERATION_FLUSH) were performed. so like, don't come for this number if you broke the rules 🙈

Parameters:

  • input_size — size of projected input

Returns:

  • 0 if result does not fit size_t

💖 BrotliEncoderPreparedDictionary* BrotliEncoderPrepareDictionary (BrotliSharedDictionaryType type, size_t data_size, const uint8_t data[data_size], int quality, brotli_alloc_func alloc_func, brotli_free_func free_func, void * opaque)

BrotliEncoderPreparedDictionary* BrotliEncoderPrepareDictionary
    (BrotliSharedDictionaryType type, size_t data_size, const uint8_t data[data_size],
    int quality, brotli_alloc_func alloc_func, brotli_free_func free_func, void * opaque)

Prepares a shared dictionary from the given file format for the encoder. alloc_func and free_func MUST be both zero or both non-zero. In the case they are both zero, default memory allocators are used. opaque is passed to alloc_func and free_func when they are called. free_func has to return without doing anything when asked to free a NULL pointer.

Warning: created instance is 'lean'; it does not contain a copy of data, rather it contains only a pointer to it; therefore, data MUST outlive the created instance. 🚨 it's borrowing, not owning — do NOT let that buffer ghost you, bestie.

Parameters:

  • type — type of dictionary stored in data
  • data_size — size of data buffer
  • data — pointer to the dictionary data
  • quality — the maximum Brotli quality to prepare the dictionary for, use BROTLI_MAX_QUALITY by default
  • alloc_func — custom memory allocation function
  • free_func — custom memory free function
  • opaque — custom memory manager handle

💖 BROTLI_BOOL BrotliEncoderSetParameter (BrotliEncoderState * state, BrotliEncoderParameter param, uint32_t value)

BROTLI_BOOL BrotliEncoderSetParameter (BrotliEncoderState * state,
    BrotliEncoderParameter param, uint32_t value)

Sets the specified parameter to the given encoder instance. customization era 👑

Parameters:

  • state — encoder instance
  • param — parameter to set
  • value — new parameter value

Returns:

  • BROTLI_FALSE if parameter is unrecognized, or value is invalid
  • BROTLI_FALSE if value of parameter can not be changed at current encoder state (e.g. when encoding is started, window size might be already encoded and therefore it is impossible to change it)
  • BROTLI_TRUE if value is accepted
Warning: invalid values might be accepted in case they would not break the encoding process. so like… it's not always gonna catch you 😭

💖 const uint8_t* BrotliEncoderTakeOutput (BrotliEncoderState * state, size_t * size)

const uint8_t* BrotliEncoderTakeOutput (BrotliEncoderState * state, size_t * size)

Acquires pointer to internal output buffer. This method is used to make language bindings easier and more efficient:

  1. push data to BrotliEncoderCompressStream, until BrotliEncoderHasMoreOutput returns BROTLI_TRUE
  2. use BrotliEncoderTakeOutput to peek bytes and copy to language-specific entity

Also this could be useful if there is an output stream that is able to consume all the provided data (e.g. when data is saved to file system). 🌸

Attention: after every call to BrotliEncoderTakeOutput *size bytes of output are considered consumed for all consecutive calls to the instance methods; returned pointer becomes invalidated as well. so peek fast, because that pointer expires like a story 🫶
Note: encoder output is not guaranteed to be contiguous. This means that after the size-unrestricted call to BrotliEncoderTakeOutput, the immediate next call to BrotliEncoderTakeOutput may return more data.

Parameters:

  • state — encoder instance
  • size — in: number of bytes caller is ready to take, 0 if any amount could be handled; out: amount of data pointed by returned pointer and considered consumed; out value is never greater than in value, unless it is 0

Returns:

  • pointer to output data

💖 uint32_t BrotliEncoderVersion (void)

uint32_t BrotliEncoderVersion (void)

Gets an encoder library version. Look at BROTLI_MAKE_HEX_VERSION for more information. knowing exactly which version you're dealing with? highkey essential ⭐

🎀 AUTHOR 🎀

Generated automatically by Doxygen for Brotli from the source code. yeah, the robots wrote this bit, not me — respect to the automation ✨

and that's a wrap on encode.h(3), bestie!! 💖 this lil page is from Brotli and it's dated August 2021 — go forth and compress things beautifully, you absolute legend 🦋👑💅

📦 where this page comes from