Opaque structure that holds encoder state\&. Allocated and initialized with \fBBrotliEncoderCreateInstance\fP\&. Cleaned up and deallocated with \fBBrotliEncoderDestroyInstance\fP\&.
.SH"Enumeration Type Documentation"
.PP
.SS"enum \fBBrotliEncoderMode\fP"
.PP
Options for \fBBROTLI_PARAM_MODE\fP parameter\&.
.PP
\fBEnumerator\fP
.in+1c
.TP
\fB\fIBROTLI_MODE_GENERIC \fP\fP
Default compression mode\&. In this mode compressor does not know anything in advance about the properties of the input\&.
.TP
\fB\fIBROTLI_MODE_TEXT \fP\fP
Compression mode for UTF-8 formatted text input\&.
.TP
\fB\fIBROTLI_MODE_FONT \fP\fP
Compression mode used in WOFF 2\&.0\&.
.SS"enum \fBBrotliEncoderOperation\fP"
.PP
Operations that can be performed by streaming encoder\&.
.PP
\fBEnumerator\fP
.in+1c
.TP
\fB\fIBROTLI_OPERATION_PROCESS \fP\fP
Process input\&. Encoder may postpone producing output, until it has processed enough input\&.
Produce output for all processed input\&. Actual flush is performed when input stream is depleted and there is enough space in output stream\&. This means that client should repeat \fBBROTLI_OPERATION_FLUSH\fP operation until \fCavailable_in\fP becomes \fC0\fP, and \fBBrotliEncoderHasMoreOutput\fP returns \fBBROTLI_FALSE\fP\&. If output is acquired via \fBBrotliEncoderTakeOutput\fP, then operation should be repeated after output buffer is drained\&.
Finalize the stream\&. Actual finalization is performed when input stream is depleted and there is enough space in output stream\&. This means that client should repeat \fBBROTLI_OPERATION_FINISH\fP operation until \fCavailable_in\fP becomes \fC0\fP, and \fBBrotliEncoderHasMoreOutput\fP returns \fBBROTLI_FALSE\fP\&. If output is acquired via \fBBrotliEncoderTakeOutput\fP, then operation should be repeated after output buffer is drained\&.
Until finalization is complete, client \fBSHOULD\fP\fBNOT\fP swap, reduce or extend input stream\&.
.RE
.PP
Helper function \fBBrotliEncoderIsFinished\fP checks if stream is finalized and output fully dumped\&.
.PP
Adding more input data to finalized stream is impossible\&.
.TP
\fB\fIBROTLI_OPERATION_EMIT_METADATA \fP\fP
Emit metadata block to stream\&. Metadata is opaque to Brotli: neither encoder, nor decoder processes this data or relies on it\&. It may be used to pass some extra information from encoder client to decoder client without interfering with main data stream\&.
.PP
\fBNote:\fP
.RS4
Encoder may emit empty metadata blocks internally, to pad encoded stream to byte boundary\&.
.RE
.PP
\fBWarning:\fP
.RS4
Until emitting metadata is complete client \fBSHOULD\fP\fBNOT\fP swap, reduce or extend input stream\&.
.PP
The whole content of input buffer is considered to be the content of metadata block\&. Do \fBNOT\fP\fIappend\fP metadata to input stream, before it is depleted with other operations\&.
.RE
.PP
Stream is soft-flushed before metadata block is emitted\&. Metadata block \fBMUST\fP be no longer than than 16MiB\&.
.SS"enum \fBBrotliEncoderParameter\fP"
.PP
Options to be used with \fBBrotliEncoderSetParameter\fP\&.
.PP
\fBEnumerator\fP
.in+1c
.TP
\fB\fIBROTLI_PARAM_MODE \fP\fP
Tune encoder for specific input\&. \fBBrotliEncoderMode\fP enumerates all available values\&.
.TP
\fB\fIBROTLI_PARAM_QUALITY \fP\fP
The main compression speed-density lever\&. The higher the quality, the slower the compression\&. Range is from \fBBROTLI_MIN_QUALITY\fP to \fBBROTLI_MAX_QUALITY\fP\&.
.TP
\fB\fIBROTLI_PARAM_LGWIN \fP\fP
Recommended sliding LZ77 window size\&. Encoder may reduce this value, e\&.g\&. if input is much smaller than window size\&.
.PP
Window size is \fC(1 << value) - 16\fP\&.
.PP
Range is from \fBBROTLI_MIN_WINDOW_BITS\fP to \fBBROTLI_MAX_WINDOW_BITS\fP\&.
.TP
\fB\fIBROTLI_PARAM_LGBLOCK \fP\fP
Recommended input block size\&. Encoder may reduce this value, e\&.g\&. if input is much smaller than input block size\&.
.PP
Range is from \fBBROTLI_MIN_INPUT_BLOCK_BITS\fP to \fBBROTLI_MAX_INPUT_BLOCK_BITS\fP\&.
.PP
\fBNote:\fP
.RS4
Bigger input block size allows better compression, but consumes more memory\&.
.br
The rough formula of memory used for temporary input storage is \fC3 << lgBlock\fP\&.
Flag that affects usage of 'literal context modeling' format feature\&. This flag is a 'decoding-speed vs compression ratio' trade-off\&.
.TP
\fB\fIBROTLI_PARAM_SIZE_HINT \fP\fP
Estimated total input size for all \fBBrotliEncoderCompressStream\fP calls\&. The default value is 0, which means that the total input size is unknown\&.
Number of bytes of input stream already processed by a different instance\&.
.PP
\fBNote:\fP
.RS4
It is important to configure all the encoder instances with same parameters (except this one) in order to allow all the encoded parts obey the same restrictions implied by header\&.
.RE
.PP
If offset is not 0, then stream header is omitted\&. In any case output start is byte aligned, so for proper streams stitching 'predecessor' stream must be flushed\&.
.PP
Range is not artificially limited, but all the values greater or equal to maximal window size have the same effect\&. Values greater than 2**30 are not allowed\&.
Attaches a prepared dictionary of any type to the encoder\&. Can be used multiple times to attach multiple dictionaries\&. The dictionary type was determined by BrotliEncoderPrepareDictionary\&. Multiple raw prefix dictionaries and/or max 1 serialized dictionary with custom words can be attached\&.
Performs one-shot memory-to-memory compression\&. Compresses the data in \fCinput_buffer\fP into \fCencoded_buffer\fP, and sets \fC*encoded_size\fP to the compressed length\&.
.PP
\fBNote:\fP
.RS4
If \fBBrotliEncoderMaxCompressedSize\fP(\fCinput_size\fP) returns non-zero value, then output is guaranteed to be no longer than that\&.
If \fClgwin\fP is greater than \fBBROTLI_MAX_WINDOW_BITS\fP then resulting stream might be incompatible with RFC 7932; to decode such streams, decoder should be configured with \fBBROTLI_DECODER_PARAM_LARGE_WINDOW\fP = \fC1\fP
Compresses input stream to output stream\&. The values \fC*available_in\fP and \fC*available_out\fP must specify the number of bytes addressable at \fC*next_in\fP and \fC*next_out\fP respectively\&. When \fC*available_out\fP is \fC0\fP, \fCnext_out\fP is allowed to be \fCNULL\fP\&.
.PP
After each call, \fC*available_in\fP will be decremented by the amount of input bytes consumed, and the \fC*next_in\fP pointer will be incremented by that amount\&. Similarly, \fC*available_out\fP will be decremented by the amount of output bytes written, and the \fC*next_out\fP pointer will be incremented by that amount\&.
actually compress data and (optionally) store it to internal buffer
.IP"3."4
(optionally) copy compressed bytes from internal buffer to output stream
.PP
.PP
Whenever all 3 tasks can't move forward anymore, or error occurs, this method returns the control flow to caller\&.
.PP
\fCop\fP is used to perform flush, finish the stream, or inject metadata block\&. See \fBBrotliEncoderOperation\fP for more information\&.
.PP
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 \fCop\fP to \fBBROTLI_OPERATION_FLUSH\fP\&. Under some circumstances (e\&.g\&. lack of output stream capacity) this operation would require several calls to \fBBrotliEncoderCompressStream\fP\&. The method must be called again until both input stream is depleted and encoder has no more output (see \fBBrotliEncoderHasMoreOutput\fP) after the method is called\&.
.PP
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 \fCop\fP to \fBBROTLI_OPERATION_FINISH\fP\&. Under some circumstances (e\&.g\&. lack of output stream capacity) this operation would require several calls to \fBBrotliEncoderCompressStream\fP\&. The method must be called again until both input stream is depleted and encoder has no more output (see \fBBrotliEncoderHasMoreOutput\fP) after the method is called\&.
.PP
\fBWarning:\fP
.RS4
When flushing and finishing, \fCop\fP should not change until operation is complete; input stream should not be swapped, reduced or extended as well\&.
.RE
.PP
\fBParameters:\fP
.RS4
\fIstate\fP encoder instance
.br
\fIop\fP requested operation
.br
\fIavailable_in\fP\fBin:\fP amount of available input;
.br
\fBout:\fP amount of unused input
.br
\fInext_in\fP pointer to the next input byte
.br
\fIavailable_out\fP\fBin:\fP length of output buffer;
.br
\fBout:\fP remaining size of output buffer
.br
\fInext_out\fP compressed output buffer cursor; can be \fCNULL\fP if \fCavailable_out\fP is \fC0\fP
.br
\fItotal_out\fP number of bytes produced so far; can be \fCNULL\fP
Creates an instance of \fBBrotliEncoderState\fP and initializes it\&. \fCalloc_func\fP and \fCfree_func\fP\fBMUST\fP be both zero or both non-zero\&. In the case they are both zero, default memory allocators are used\&. \fCopaque\fP is passed to \fCalloc_func\fP and \fCfree_func\fP when they are called\&. \fCfree_func\fP has to return without doing anything when asked to free a NULL pointer\&.
Result is only valid if quality is at least \fC2\fP and, in case \fBBrotliEncoderCompressStream\fP was used, no flushes (\fBBROTLI_OPERATION_FLUSH\fP) were performed\&.
Prepares a shared dictionary from the given file format for the encoder\&. \fCalloc_func\fP and \fCfree_func\fP\fBMUST\fP be both zero or both non-zero\&. In the case they are both zero, default memory allocators are used\&. \fCopaque\fP is passed to \fCalloc_func\fP and \fCfree_func\fP when they are called\&. \fCfree_func\fP has to return without doing anything when asked to free a NULL pointer\&.
.PP
\fBParameters:\fP
.RS4
\fItype\fP type of dictionary stored in data
.br
\fIdata_size\fP size of \fCdata\fP buffer
.br
\fIdata\fP pointer to the dictionary data
.br
\fIquality\fP the maximum Brotli quality to prepare the dictionary for, use BROTLI_MAX_QUALITY by default
.br
\fIalloc_func\fP custom memory allocation function
Sets the specified parameter to the given encoder instance\&.
.PP
\fBParameters:\fP
.RS4
\fIstate\fP encoder instance
.br
\fIparam\fP parameter to set
.br
\fIvalue\fP new parameter value
.RE
.PP
\fBReturns:\fP
.RS4
\fBBROTLI_FALSE\fP if parameter is unrecognized, or value is invalid
.PP
\fBBROTLI_FALSE\fP 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)
.PP
\fBBROTLI_TRUE\fP if value is accepted
.RE
.PP
\fBWarning:\fP
.RS4
invalid values might be accepted in case they would not break encoding process\&.
use \fBBrotliEncoderTakeOutput\fP to peek bytes and copy to language-specific entity
.PP
.PP
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)\&.
.PP
\fBAttention:\fP
.RS4
After every call to \fBBrotliEncoderTakeOutput\fP\fC*size\fP bytes of output are considered consumed for all consecutive calls to the instance methods; returned pointer becomes invalidated as well\&.
.RE
.PP
\fBNote:\fP
.RS4
Encoder output is not guaranteed to be contiguous\&. This means that after the size-unrestricted call to \fBBrotliEncoderTakeOutput\fP, immediate next call to \fBBrotliEncoderTakeOutput\fP may return more data\&.
.RE
.PP
\fBParameters:\fP
.RS4
\fIstate\fP encoder instance
.br
\fIsize\fP\fBin:\fP number of bytes caller is ready to take, \fC0\fP if any amount could be handled;
.br
\fBout:\fP amount of data pointed by returned pointer and considered consumed;
.br
out value is never greater than in value, unless it is \fC0\fP
