Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/thirdparty/brotli/docs/encode.h.3 @ 2:b50eed0cc0ef upstream

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:43:07 +0200
parents
children
comparison
equal deleted inserted replaced
1:1d09e1dec1d9 2:b50eed0cc0ef
1 .TH "encode.h" 3 "August 2021" "Brotli" \" -*- nroff -*-
2 .ad l
3 .nh
4 .SH NAME
5 encode.h \- API for Brotli compression\&.
6
7 .SH SYNOPSIS
8 .br
9 .PP
10 .SS "Macros"
11
12 .in +1c
13 .ti -1c
14 .RI "#define \fBBROTLI_DEFAULT_MODE\fP \fBBROTLI_MODE_GENERIC\fP"
15 .br
16 .RI "\fIDefault value for \fBBROTLI_PARAM_MODE\fP parameter\&. \fP"
17 .ti -1c
18 .RI "#define \fBBROTLI_DEFAULT_QUALITY\fP 11"
19 .br
20 .RI "\fIDefault value for \fBBROTLI_PARAM_QUALITY\fP parameter\&. \fP"
21 .ti -1c
22 .RI "#define \fBBROTLI_DEFAULT_WINDOW\fP 22"
23 .br
24 .RI "\fIDefault value for \fBBROTLI_PARAM_LGWIN\fP parameter\&. \fP"
25 .ti -1c
26 .RI "#define \fBBROTLI_LARGE_MAX_WINDOW_BITS\fP 30"
27 .br
28 .RI "\fIMaximal value for \fBBROTLI_PARAM_LGWIN\fP parameter in 'Large Window Brotli' (32-bit)\&. \fP"
29 .ti -1c
30 .RI "#define \fBBROTLI_MAX_INPUT_BLOCK_BITS\fP 24"
31 .br
32 .RI "\fIMaximal value for \fBBROTLI_PARAM_LGBLOCK\fP parameter\&. \fP"
33 .ti -1c
34 .RI "#define \fBBROTLI_MAX_QUALITY\fP 11"
35 .br
36 .RI "\fIMaximal value for \fBBROTLI_PARAM_QUALITY\fP parameter\&. \fP"
37 .ti -1c
38 .RI "#define \fBBROTLI_MAX_WINDOW_BITS\fP 24"
39 .br
40 .RI "\fIMaximal value for \fBBROTLI_PARAM_LGWIN\fP parameter\&. \fP"
41 .ti -1c
42 .RI "#define \fBBROTLI_MIN_INPUT_BLOCK_BITS\fP 16"
43 .br
44 .RI "\fIMinimal value for \fBBROTLI_PARAM_LGBLOCK\fP parameter\&. \fP"
45 .ti -1c
46 .RI "#define \fBBROTLI_MIN_QUALITY\fP 0"
47 .br
48 .RI "\fIMinimal value for \fBBROTLI_PARAM_QUALITY\fP parameter\&. \fP"
49 .ti -1c
50 .RI "#define \fBBROTLI_MIN_WINDOW_BITS\fP 10"
51 .br
52 .RI "\fIMinimal value for \fBBROTLI_PARAM_LGWIN\fP parameter\&. \fP"
53 .in -1c
54 .SS "Typedefs"
55
56 .in +1c
57 .ti -1c
58 .RI "typedef enum \fBBrotliEncoderMode\fP \fBBrotliEncoderMode\fP"
59 .br
60 .RI "\fIOptions for \fBBROTLI_PARAM_MODE\fP parameter\&. \fP"
61 .ti -1c
62 .RI "typedef enum \fBBrotliEncoderOperation\fP \fBBrotliEncoderOperation\fP"
63 .br
64 .RI "\fIOperations that can be performed by streaming encoder\&. \fP"
65 .ti -1c
66 .RI "typedef enum \fBBrotliEncoderParameter\fP \fBBrotliEncoderParameter\fP"
67 .br
68 .RI "\fIOptions to be used with \fBBrotliEncoderSetParameter\fP\&. \fP"
69 .ti -1c
70 .RI "typedef struct BrotliEncoderStateStruct \fBBrotliEncoderState\fP"
71 .br
72 .RI "\fIOpaque structure that holds encoder state\&. \fP"
73 .in -1c
74 .SS "Enumerations"
75 .SS "Functions"
76
77 .in +1c
78 .ti -1c
79 .RI "\fBBROTLI_BOOL\fP \fBBrotliEncoderAttachPreparedDictionary\fP (\fBBrotliEncoderState\fP *state, const BrotliEncoderPreparedDictionary *dictionary)"
80 .br
81 .RI "\fIAttaches a prepared dictionary of any type to the encoder\&. \fP"
82 .ti -1c
83 .RI "\fBBROTLI_BOOL\fP \fBBrotliEncoderCompress\fP (int quality, int lgwin, \fBBrotliEncoderMode\fP mode, size_t input_size, const uint8_t input_buffer[input_size], size_t *encoded_size, uint8_t encoded_buffer[*encoded_size])"
84 .br
85 .RI "\fIPerforms one-shot memory-to-memory compression\&. \fP"
86 .ti -1c
87 .RI "\fBBROTLI_BOOL\fP \fBBrotliEncoderCompressStream\fP (\fBBrotliEncoderState\fP *state, \fBBrotliEncoderOperation\fP op, size_t *available_in, const uint8_t **next_in, size_t *available_out, uint8_t **next_out, size_t *total_out)"
88 .br
89 .RI "\fICompresses input stream to output stream\&. \fP"
90 .ti -1c
91 .RI "\fBBrotliEncoderState\fP * \fBBrotliEncoderCreateInstance\fP (\fBbrotli_alloc_func\fP alloc_func, \fBbrotli_free_func\fP free_func, void *opaque)"
92 .br
93 .RI "\fICreates an instance of \fBBrotliEncoderState\fP and initializes it\&. \fP"
94 .ti -1c
95 .RI "void \fBBrotliEncoderDestroyInstance\fP (\fBBrotliEncoderState\fP *state)"
96 .br
97 .RI "\fIDeinitializes and frees \fBBrotliEncoderState\fP instance\&. \fP"
98 .ti -1c
99 .RI "\fBBROTLI_BOOL\fP \fBBrotliEncoderHasMoreOutput\fP (\fBBrotliEncoderState\fP *state)"
100 .br
101 .RI "\fIChecks if encoder has more output\&. \fP"
102 .ti -1c
103 .RI "\fBBROTLI_BOOL\fP \fBBrotliEncoderIsFinished\fP (\fBBrotliEncoderState\fP *state)"
104 .br
105 .RI "\fIChecks if encoder instance reached the final state\&. \fP"
106 .ti -1c
107 .RI "size_t \fBBrotliEncoderMaxCompressedSize\fP (size_t input_size)"
108 .br
109 .RI "\fICalculates the output size bound for the given \fCinput_size\fP\&. \fP"
110 .ti -1c
111 .RI "BrotliEncoderPreparedDictionary * \fBBrotliEncoderPrepareDictionary\fP (BrotliSharedDictionaryType type, size_t data_size, const uint8_t data[data_size], int quality, \fBbrotli_alloc_func\fP alloc_func, \fBbrotli_free_func\fP free_func, void *opaque)"
112 .br
113 .RI "\fIPrepares a shared dictionary from the given file format for the encoder\&. \fP"
114 .ti -1c
115 .RI "\fBBROTLI_BOOL\fP \fBBrotliEncoderSetParameter\fP (\fBBrotliEncoderState\fP *state, \fBBrotliEncoderParameter\fP param, uint32_t value)"
116 .br
117 .RI "\fISets the specified parameter to the given encoder instance\&. \fP"
118 .ti -1c
119 .RI "const uint8_t * \fBBrotliEncoderTakeOutput\fP (\fBBrotliEncoderState\fP *state, size_t *size)"
120 .br
121 .RI "\fIAcquires pointer to internal output buffer\&. \fP"
122 .ti -1c
123 .RI "uint32_t \fBBrotliEncoderVersion\fP (void)"
124 .br
125 .RI "\fIGets an encoder library version\&. \fP"
126 .in -1c
127 .SH "Detailed Description"
128 .PP
129 API for Brotli compression\&.
130
131
132 .SH "Macro Definition Documentation"
133 .PP
134 .SS "#define BROTLI_DEFAULT_MODE \fBBROTLI_MODE_GENERIC\fP"
135
136 .PP
137 Default value for \fBBROTLI_PARAM_MODE\fP parameter\&.
138 .SS "#define BROTLI_DEFAULT_QUALITY 11"
139
140 .PP
141 Default value for \fBBROTLI_PARAM_QUALITY\fP parameter\&.
142 .SS "#define BROTLI_DEFAULT_WINDOW 22"
143
144 .PP
145 Default value for \fBBROTLI_PARAM_LGWIN\fP parameter\&.
146 .SS "#define BROTLI_MAX_INPUT_BLOCK_BITS 24"
147
148 .PP
149 Maximal value for \fBBROTLI_PARAM_LGBLOCK\fP parameter\&.
150 .SS "#define BROTLI_MAX_QUALITY 11"
151
152 .PP
153 Maximal value for \fBBROTLI_PARAM_QUALITY\fP parameter\&.
154 .SS "#define BROTLI_MAX_WINDOW_BITS 24"
155
156 .PP
157 Maximal value for \fBBROTLI_PARAM_LGWIN\fP parameter\&.
158 .PP
159 \fBNote:\fP
160 .RS 4
161 equal to \fCBROTLI_MAX_DISTANCE_BITS\fP constant\&.
162 .RE
163 .PP
164
165 .SS "#define BROTLI_MIN_INPUT_BLOCK_BITS 16"
166
167 .PP
168 Minimal value for \fBBROTLI_PARAM_LGBLOCK\fP parameter\&.
169 .SS "#define BROTLI_MIN_QUALITY 0"
170
171 .PP
172 Minimal value for \fBBROTLI_PARAM_QUALITY\fP parameter\&.
173 .SS "#define BROTLI_MIN_WINDOW_BITS 10"
174
175 .PP
176 Minimal value for \fBBROTLI_PARAM_LGWIN\fP parameter\&.
177 .SH "Typedef Documentation"
178 .PP
179 .SS "typedef enum \fBBrotliEncoderMode\fP \fBBrotliEncoderMode\fP"
180
181 .PP
182 Options for \fBBROTLI_PARAM_MODE\fP parameter\&.
183 .SS "typedef enum \fBBrotliEncoderOperation\fP \fBBrotliEncoderOperation\fP"
184
185 .PP
186 Operations that can be performed by streaming encoder\&.
187 .SS "typedef enum \fBBrotliEncoderParameter\fP \fBBrotliEncoderParameter\fP"
188
189 .PP
190 Options to be used with \fBBrotliEncoderSetParameter\fP\&.
191 .SS "typedef struct BrotliEncoderStateStruct \fBBrotliEncoderState\fP"
192
193 .PP
194 Opaque structure that holds encoder state\&. Allocated and initialized with \fBBrotliEncoderCreateInstance\fP\&. Cleaned up and deallocated with \fBBrotliEncoderDestroyInstance\fP\&.
195 .SH "Enumeration Type Documentation"
196 .PP
197 .SS "enum \fBBrotliEncoderMode\fP"
198
199 .PP
200 Options for \fBBROTLI_PARAM_MODE\fP parameter\&.
201 .PP
202 \fBEnumerator\fP
203 .in +1c
204 .TP
205 \fB\fIBROTLI_MODE_GENERIC \fP\fP
206 Default compression mode\&. In this mode compressor does not know anything in advance about the properties of the input\&.
207 .TP
208 \fB\fIBROTLI_MODE_TEXT \fP\fP
209 Compression mode for UTF-8 formatted text input\&.
210 .TP
211 \fB\fIBROTLI_MODE_FONT \fP\fP
212 Compression mode used in WOFF 2\&.0\&.
213 .SS "enum \fBBrotliEncoderOperation\fP"
214
215 .PP
216 Operations that can be performed by streaming encoder\&.
217 .PP
218 \fBEnumerator\fP
219 .in +1c
220 .TP
221 \fB\fIBROTLI_OPERATION_PROCESS \fP\fP
222 Process input\&. Encoder may postpone producing output, until it has processed enough input\&.
223 .TP
224 \fB\fIBROTLI_OPERATION_FLUSH \fP\fP
225 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\&.
226 .PP
227 \fBWarning:\fP
228 .RS 4
229 Until flush is complete, client \fBSHOULD\fP \fBNOT\fP swap, reduce or extend input stream\&.
230 .RE
231 .PP
232 When flush is complete, output data will be sufficient for decoder to reproduce all the given input\&.
233 .TP
234 \fB\fIBROTLI_OPERATION_FINISH \fP\fP
235 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\&.
236 .PP
237 \fBWarning:\fP
238 .RS 4
239 Until finalization is complete, client \fBSHOULD\fP \fBNOT\fP swap, reduce or extend input stream\&.
240 .RE
241 .PP
242 Helper function \fBBrotliEncoderIsFinished\fP checks if stream is finalized and output fully dumped\&.
243 .PP
244 Adding more input data to finalized stream is impossible\&.
245 .TP
246 \fB\fIBROTLI_OPERATION_EMIT_METADATA \fP\fP
247 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\&.
248 .PP
249 \fBNote:\fP
250 .RS 4
251 Encoder may emit empty metadata blocks internally, to pad encoded stream to byte boundary\&.
252 .RE
253 .PP
254 \fBWarning:\fP
255 .RS 4
256 Until emitting metadata is complete client \fBSHOULD\fP \fBNOT\fP swap, reduce or extend input stream\&.
257 .PP
258 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\&.
259 .RE
260 .PP
261 Stream is soft-flushed before metadata block is emitted\&. Metadata block \fBMUST\fP be no longer than than 16MiB\&.
262 .SS "enum \fBBrotliEncoderParameter\fP"
263
264 .PP
265 Options to be used with \fBBrotliEncoderSetParameter\fP\&.
266 .PP
267 \fBEnumerator\fP
268 .in +1c
269 .TP
270 \fB\fIBROTLI_PARAM_MODE \fP\fP
271 Tune encoder for specific input\&. \fBBrotliEncoderMode\fP enumerates all available values\&.
272 .TP
273 \fB\fIBROTLI_PARAM_QUALITY \fP\fP
274 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\&.
275 .TP
276 \fB\fIBROTLI_PARAM_LGWIN \fP\fP
277 Recommended sliding LZ77 window size\&. Encoder may reduce this value, e\&.g\&. if input is much smaller than window size\&.
278 .PP
279 Window size is \fC(1 << value) - 16\fP\&.
280 .PP
281 Range is from \fBBROTLI_MIN_WINDOW_BITS\fP to \fBBROTLI_MAX_WINDOW_BITS\fP\&.
282 .TP
283 \fB\fIBROTLI_PARAM_LGBLOCK \fP\fP
284 Recommended input block size\&. Encoder may reduce this value, e\&.g\&. if input is much smaller than input block size\&.
285 .PP
286 Range is from \fBBROTLI_MIN_INPUT_BLOCK_BITS\fP to \fBBROTLI_MAX_INPUT_BLOCK_BITS\fP\&.
287 .PP
288 \fBNote:\fP
289 .RS 4
290 Bigger input block size allows better compression, but consumes more memory\&.
291 .br
292 The rough formula of memory used for temporary input storage is \fC3 << lgBlock\fP\&.
293 .RE
294 .PP
295
296 .TP
297 \fB\fIBROTLI_PARAM_DISABLE_LITERAL_CONTEXT_MODELING \fP\fP
298 Flag that affects usage of 'literal context modeling' format feature\&. This flag is a 'decoding-speed vs compression ratio' trade-off\&.
299 .TP
300 \fB\fIBROTLI_PARAM_SIZE_HINT \fP\fP
301 Estimated total input size for all \fBBrotliEncoderCompressStream\fP calls\&. The default value is 0, which means that the total input size is unknown\&.
302 .TP
303 \fB\fIBROTLI_PARAM_LARGE_WINDOW \fP\fP
304 Flag that determines if 'Large Window Brotli' is used\&.
305 .TP
306 \fB\fIBROTLI_PARAM_NPOSTFIX \fP\fP
307 Recommended number of postfix bits (NPOSTFIX)\&. Encoder may change this value\&.
308 .PP
309 Range is from 0 to \fBBROTLI_MAX_NPOSTFIX\fP\&.
310 .TP
311 \fB\fIBROTLI_PARAM_NDIRECT \fP\fP
312 Recommended number of direct distance codes (NDIRECT)\&. Encoder may change this value\&.
313 .PP
314 Range is from 0 to (15 << NPOSTFIX) in steps of (1 << NPOSTFIX)\&.
315 .TP
316 \fB\fIBROTLI_PARAM_STREAM_OFFSET \fP\fP
317 Number of bytes of input stream already processed by a different instance\&.
318 .PP
319 \fBNote:\fP
320 .RS 4
321 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\&.
322 .RE
323 .PP
324 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\&.
325 .PP
326 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\&.
327 .SH "Function Documentation"
328 .PP
329 .SS "\fBBROTLI_BOOL\fP BrotliEncoderAttachPreparedDictionary (\fBBrotliEncoderState\fP * state, const BrotliEncoderPreparedDictionary * dictionary)"
330
331 .PP
332 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\&.
333 .PP
334 \fBReturns:\fP
335 .RS 4
336 \fBBROTLI_FALSE\fP in case of error
337 .PP
338 \fBBROTLI_TRUE\fP otherwise
339 .RE
340 .PP
341
342 .SS "\fBBROTLI_BOOL\fP BrotliEncoderCompress (int quality, int lgwin, \fBBrotliEncoderMode\fP mode, size_t input_size, const uint8_t input_buffer[input_size], size_t * encoded_size, uint8_t encoded_buffer[*encoded_size])"
343
344 .PP
345 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\&.
346 .PP
347 \fBNote:\fP
348 .RS 4
349 If \fBBrotliEncoderMaxCompressedSize\fP(\fCinput_size\fP) returns non-zero value, then output is guaranteed to be no longer than that\&.
350 .PP
351 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
352 .RE
353 .PP
354 \fBParameters:\fP
355 .RS 4
356 \fIquality\fP quality parameter value, e\&.g\&. \fBBROTLI_DEFAULT_QUALITY\fP
357 .br
358 \fIlgwin\fP lgwin parameter value, e\&.g\&. \fBBROTLI_DEFAULT_WINDOW\fP
359 .br
360 \fImode\fP mode parameter value, e\&.g\&. \fBBROTLI_DEFAULT_MODE\fP
361 .br
362 \fIinput_size\fP size of \fCinput_buffer\fP
363 .br
364 \fIinput_buffer\fP input data buffer with at least \fCinput_size\fP addressable bytes
365 .br
366 \fIencoded_size\fP \fBin:\fP size of \fCencoded_buffer\fP;
367 .br
368 \fBout:\fP length of compressed data written to \fCencoded_buffer\fP, or \fC0\fP if compression fails
369 .br
370 \fIencoded_buffer\fP compressed data destination buffer
371 .RE
372 .PP
373 \fBReturns:\fP
374 .RS 4
375 \fBBROTLI_FALSE\fP in case of compression error
376 .PP
377 \fBBROTLI_FALSE\fP if output buffer is too small
378 .PP
379 \fBBROTLI_TRUE\fP otherwise
380 .RE
381 .PP
382
383 .SS "\fBBROTLI_BOOL\fP BrotliEncoderCompressStream (\fBBrotliEncoderState\fP * state, \fBBrotliEncoderOperation\fP op, size_t * available_in, const uint8_t ** next_in, size_t * available_out, uint8_t ** next_out, size_t * total_out)"
384
385 .PP
386 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\&.
387 .PP
388 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\&.
389 .PP
390 \fCtotal_out\fP, if it is not a null-pointer, will be set to the number of bytes compressed since the last \fCstate\fP initialization\&.
391 .PP
392 Internally workflow consists of 3 tasks:
393 .IP "1." 4
394 (optionally) copy input data to internal buffer
395 .IP "2." 4
396 actually compress data and (optionally) store it to internal buffer
397 .IP "3." 4
398 (optionally) copy compressed bytes from internal buffer to output stream
399 .PP
400 .PP
401 Whenever all 3 tasks can't move forward anymore, or error occurs, this method returns the control flow to caller\&.
402 .PP
403 \fCop\fP is used to perform flush, finish the stream, or inject metadata block\&. See \fBBrotliEncoderOperation\fP for more information\&.
404 .PP
405 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\&.
406 .PP
407 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\&.
408 .PP
409 \fBWarning:\fP
410 .RS 4
411 When flushing and finishing, \fCop\fP should not change until operation is complete; input stream should not be swapped, reduced or extended as well\&.
412 .RE
413 .PP
414 \fBParameters:\fP
415 .RS 4
416 \fIstate\fP encoder instance
417 .br
418 \fIop\fP requested operation
419 .br
420 \fIavailable_in\fP \fBin:\fP amount of available input;
421 .br
422 \fBout:\fP amount of unused input
423 .br
424 \fInext_in\fP pointer to the next input byte
425 .br
426 \fIavailable_out\fP \fBin:\fP length of output buffer;
427 .br
428 \fBout:\fP remaining size of output buffer
429 .br
430 \fInext_out\fP compressed output buffer cursor; can be \fCNULL\fP if \fCavailable_out\fP is \fC0\fP
431 .br
432 \fItotal_out\fP number of bytes produced so far; can be \fCNULL\fP
433 .RE
434 .PP
435 \fBReturns:\fP
436 .RS 4
437 \fBBROTLI_FALSE\fP if there was an error
438 .PP
439 \fBBROTLI_TRUE\fP otherwise
440 .RE
441 .PP
442
443 .SS "\fBBrotliEncoderState\fP* BrotliEncoderCreateInstance (\fBbrotli_alloc_func\fP alloc_func, \fBbrotli_free_func\fP free_func, void * opaque)"
444
445 .PP
446 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\&.
447 .PP
448 \fBParameters:\fP
449 .RS 4
450 \fIalloc_func\fP custom memory allocation function
451 .br
452 \fIfree_func\fP custom memory free function
453 .br
454 \fIopaque\fP custom memory manager handle
455 .RE
456 .PP
457 \fBReturns:\fP
458 .RS 4
459 \fC0\fP if instance can not be allocated or initialized
460 .PP
461 pointer to initialized \fBBrotliEncoderState\fP otherwise
462 .RE
463 .PP
464
465 .SS "void BrotliEncoderDestroyInstance (\fBBrotliEncoderState\fP * state)"
466
467 .PP
468 Deinitializes and frees \fBBrotliEncoderState\fP instance\&.
469 .PP
470 \fBParameters:\fP
471 .RS 4
472 \fIstate\fP decoder instance to be cleaned up and deallocated
473 .RE
474 .PP
475
476 .SS "\fBBROTLI_BOOL\fP BrotliEncoderHasMoreOutput (\fBBrotliEncoderState\fP * state)"
477
478 .PP
479 Checks if encoder has more output\&.
480 .PP
481 \fBParameters:\fP
482 .RS 4
483 \fIstate\fP encoder instance
484 .RE
485 .PP
486 \fBReturns:\fP
487 .RS 4
488 \fBBROTLI_TRUE\fP, if encoder has some unconsumed output
489 .PP
490 \fBBROTLI_FALSE\fP otherwise
491 .RE
492 .PP
493
494 .SS "\fBBROTLI_BOOL\fP BrotliEncoderIsFinished (\fBBrotliEncoderState\fP * state)"
495
496 .PP
497 Checks if encoder instance reached the final state\&.
498 .PP
499 \fBParameters:\fP
500 .RS 4
501 \fIstate\fP encoder instance
502 .RE
503 .PP
504 \fBReturns:\fP
505 .RS 4
506 \fBBROTLI_TRUE\fP if encoder is in a state where it reached the end of the input and produced all of the output
507 .PP
508 \fBBROTLI_FALSE\fP otherwise
509 .RE
510 .PP
511
512 .SS "size_t BrotliEncoderMaxCompressedSize (size_t input_size)"
513
514 .PP
515 Calculates the output size bound for the given \fCinput_size\fP\&.
516 .PP
517 \fBWarning:\fP
518 .RS 4
519 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\&.
520 .RE
521 .PP
522 \fBParameters:\fP
523 .RS 4
524 \fIinput_size\fP size of projected input
525 .RE
526 .PP
527 \fBReturns:\fP
528 .RS 4
529 \fC0\fP if result does not fit \fCsize_t\fP
530 .RE
531 .PP
532
533 .SS "BrotliEncoderPreparedDictionary* BrotliEncoderPrepareDictionary (BrotliSharedDictionaryType type, size_t data_size, const uint8_t data[data_size], int quality, \fBbrotli_alloc_func\fP alloc_func, \fBbrotli_free_func\fP free_func, void * opaque)"
534
535 .PP
536 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\&.
537 .PP
538 \fBParameters:\fP
539 .RS 4
540 \fItype\fP type of dictionary stored in data
541 .br
542 \fIdata_size\fP size of \fCdata\fP buffer
543 .br
544 \fIdata\fP pointer to the dictionary data
545 .br
546 \fIquality\fP the maximum Brotli quality to prepare the dictionary for, use BROTLI_MAX_QUALITY by default
547 .br
548 \fIalloc_func\fP custom memory allocation function
549 .br
550 \fIfree_func\fP custom memory free function
551 .br
552 \fIopaque\fP custom memory manager handle
553 .RE
554 .PP
555
556 .SS "\fBBROTLI_BOOL\fP BrotliEncoderSetParameter (\fBBrotliEncoderState\fP * state, \fBBrotliEncoderParameter\fP param, uint32_t value)"
557
558 .PP
559 Sets the specified parameter to the given encoder instance\&.
560 .PP
561 \fBParameters:\fP
562 .RS 4
563 \fIstate\fP encoder instance
564 .br
565 \fIparam\fP parameter to set
566 .br
567 \fIvalue\fP new parameter value
568 .RE
569 .PP
570 \fBReturns:\fP
571 .RS 4
572 \fBBROTLI_FALSE\fP if parameter is unrecognized, or value is invalid
573 .PP
574 \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)
575 .PP
576 \fBBROTLI_TRUE\fP if value is accepted
577 .RE
578 .PP
579 \fBWarning:\fP
580 .RS 4
581 invalid values might be accepted in case they would not break encoding process\&.
582 .RE
583 .PP
584
585 .SS "const uint8_t* BrotliEncoderTakeOutput (\fBBrotliEncoderState\fP * state, size_t * size)"
586
587 .PP
588 Acquires pointer to internal output buffer\&. This method is used to make language bindings easier and more efficient:
589 .IP "1." 4
590 push data to \fBBrotliEncoderCompressStream\fP, until \fBBrotliEncoderHasMoreOutput\fP returns BROTLI_TRUE
591 .IP "2." 4
592 use \fBBrotliEncoderTakeOutput\fP to peek bytes and copy to language-specific entity
593 .PP
594 .PP
595 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)\&.
596 .PP
597 \fBAttention:\fP
598 .RS 4
599 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\&.
600 .RE
601 .PP
602 \fBNote:\fP
603 .RS 4
604 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\&.
605 .RE
606 .PP
607 \fBParameters:\fP
608 .RS 4
609 \fIstate\fP encoder instance
610 .br
611 \fIsize\fP \fBin:\fP number of bytes caller is ready to take, \fC0\fP if any amount could be handled;
612 .br
613 \fBout:\fP amount of data pointed by returned pointer and considered consumed;
614 .br
615 out value is never greater than in value, unless it is \fC0\fP
616 .RE
617 .PP
618 \fBReturns:\fP
619 .RS 4
620 pointer to output data
621 .RE
622 .PP
623
624 .SS "uint32_t BrotliEncoderVersion (void)"
625
626 .PP
627 Gets an encoder library version\&. Look at BROTLI_MAKE_HEX_VERSION for more information\&.
628 .SH "Author"
629 .PP
630 Generated automatically by Doxygen for Brotli from the source code\&.