1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586
|
.TH "encode.h" 3 "Thu Feb 22 2018" "Brotli" \" -*- nroff -*-
.ad l
.nh
.SH NAME
encode.h \- API for Brotli compression\&.
.SH SYNOPSIS
.br
.PP
.SS "Macros"
.in +1c
.ti -1c
.RI "#define \fBBROTLI_DEFAULT_MODE\fP \fBBROTLI_MODE_GENERIC\fP"
.br
.RI "\fIDefault value for \fBBROTLI_PARAM_MODE\fP parameter\&. \fP"
.ti -1c
.RI "#define \fBBROTLI_DEFAULT_QUALITY\fP 11"
.br
.RI "\fIDefault value for \fBBROTLI_PARAM_QUALITY\fP parameter\&. \fP"
.ti -1c
.RI "#define \fBBROTLI_DEFAULT_WINDOW\fP 22"
.br
.RI "\fIDefault value for \fBBROTLI_PARAM_LGWIN\fP parameter\&. \fP"
.ti -1c
.RI "#define \fBBROTLI_LARGE_MAX_WINDOW_BITS\fP 30"
.br
.RI "\fIMaximal value for \fBBROTLI_PARAM_LGWIN\fP parameter in 'Large Window Brotli' (32-bit)\&. \fP"
.ti -1c
.RI "#define \fBBROTLI_MAX_INPUT_BLOCK_BITS\fP 24"
.br
.RI "\fIMaximal value for \fBBROTLI_PARAM_LGBLOCK\fP parameter\&. \fP"
.ti -1c
.RI "#define \fBBROTLI_MAX_QUALITY\fP 11"
.br
.RI "\fIMaximal value for \fBBROTLI_PARAM_QUALITY\fP parameter\&. \fP"
.ti -1c
.RI "#define \fBBROTLI_MAX_WINDOW_BITS\fP 24"
.br
.RI "\fIMaximal value for \fBBROTLI_PARAM_LGWIN\fP parameter\&. \fP"
.ti -1c
.RI "#define \fBBROTLI_MIN_INPUT_BLOCK_BITS\fP 16"
.br
.RI "\fIMinimal value for \fBBROTLI_PARAM_LGBLOCK\fP parameter\&. \fP"
.ti -1c
.RI "#define \fBBROTLI_MIN_QUALITY\fP 0"
.br
.RI "\fIMinimal value for \fBBROTLI_PARAM_QUALITY\fP parameter\&. \fP"
.ti -1c
.RI "#define \fBBROTLI_MIN_WINDOW_BITS\fP 10"
.br
.RI "\fIMinimal value for \fBBROTLI_PARAM_LGWIN\fP parameter\&. \fP"
.in -1c
.SS "Typedefs"
.in +1c
.ti -1c
.RI "typedef enum \fBBrotliEncoderMode\fP \fBBrotliEncoderMode\fP"
.br
.RI "\fIOptions for \fBBROTLI_PARAM_MODE\fP parameter\&. \fP"
.ti -1c
.RI "typedef enum \fBBrotliEncoderOperation\fP \fBBrotliEncoderOperation\fP"
.br
.RI "\fIOperations that can be performed by streaming encoder\&. \fP"
.ti -1c
.RI "typedef enum \fBBrotliEncoderParameter\fP \fBBrotliEncoderParameter\fP"
.br
.RI "\fIOptions to be used with \fBBrotliEncoderSetParameter\fP\&. \fP"
.ti -1c
.RI "typedef struct BrotliEncoderStateStruct \fBBrotliEncoderState\fP"
.br
.RI "\fIOpaque structure that holds encoder state\&. \fP"
.in -1c
.SS "Enumerations"
.SS "Functions"
.in +1c
.ti -1c
.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])"
.br
.RI "\fIPerforms one-shot memory-to-memory compression\&. \fP"
.ti -1c
.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)"
.br
.RI "\fICompresses input stream to output stream\&. \fP"
.ti -1c
.RI "\fBBrotliEncoderState\fP * \fBBrotliEncoderCreateInstance\fP (\fBbrotli_alloc_func\fP alloc_func, \fBbrotli_free_func\fP free_func, void *opaque)"
.br
.RI "\fICreates an instance of \fBBrotliEncoderState\fP and initializes it\&. \fP"
.ti -1c
.RI "void \fBBrotliEncoderDestroyInstance\fP (\fBBrotliEncoderState\fP *state)"
.br
.RI "\fIDeinitializes and frees \fBBrotliEncoderState\fP instance\&. \fP"
.ti -1c
.RI "\fBBROTLI_BOOL\fP \fBBrotliEncoderHasMoreOutput\fP (\fBBrotliEncoderState\fP *state)"
.br
.RI "\fIChecks if encoder has more output\&. \fP"
.ti -1c
.RI "\fBBROTLI_BOOL\fP \fBBrotliEncoderIsFinished\fP (\fBBrotliEncoderState\fP *state)"
.br
.RI "\fIChecks if encoder instance reached the final state\&. \fP"
.ti -1c
.RI "size_t \fBBrotliEncoderMaxCompressedSize\fP (size_t input_size)"
.br
.RI "\fICalculates the output size bound for the given \fCinput_size\fP\&. \fP"
.ti -1c
.RI "\fBBROTLI_BOOL\fP \fBBrotliEncoderSetParameter\fP (\fBBrotliEncoderState\fP *state, \fBBrotliEncoderParameter\fP param, uint32_t value)"
.br
.RI "\fISets the specified parameter to the given encoder instance\&. \fP"
.ti -1c
.RI "const uint8_t * \fBBrotliEncoderTakeOutput\fP (\fBBrotliEncoderState\fP *state, size_t *size)"
.br
.RI "\fIAcquires pointer to internal output buffer\&. \fP"
.ti -1c
.RI "uint32_t \fBBrotliEncoderVersion\fP (void)"
.br
.RI "\fIGets an encoder library version\&. \fP"
.in -1c
.SH "Detailed Description"
.PP
API for Brotli compression\&.
.SH "Macro Definition Documentation"
.PP
.SS "#define BROTLI_DEFAULT_MODE \fBBROTLI_MODE_GENERIC\fP"
.PP
Default value for \fBBROTLI_PARAM_MODE\fP parameter\&.
.SS "#define BROTLI_DEFAULT_QUALITY 11"
.PP
Default value for \fBBROTLI_PARAM_QUALITY\fP parameter\&.
.SS "#define BROTLI_DEFAULT_WINDOW 22"
.PP
Default value for \fBBROTLI_PARAM_LGWIN\fP parameter\&.
.SS "#define BROTLI_MAX_INPUT_BLOCK_BITS 24"
.PP
Maximal value for \fBBROTLI_PARAM_LGBLOCK\fP parameter\&.
.SS "#define BROTLI_MAX_QUALITY 11"
.PP
Maximal value for \fBBROTLI_PARAM_QUALITY\fP parameter\&.
.SS "#define BROTLI_MAX_WINDOW_BITS 24"
.PP
Maximal value for \fBBROTLI_PARAM_LGWIN\fP parameter\&.
.PP
\fBNote:\fP
.RS 4
equal to \fCBROTLI_MAX_DISTANCE_BITS\fP constant\&.
.RE
.PP
.SS "#define BROTLI_MIN_INPUT_BLOCK_BITS 16"
.PP
Minimal value for \fBBROTLI_PARAM_LGBLOCK\fP parameter\&.
.SS "#define BROTLI_MIN_QUALITY 0"
.PP
Minimal value for \fBBROTLI_PARAM_QUALITY\fP parameter\&.
.SS "#define BROTLI_MIN_WINDOW_BITS 10"
.PP
Minimal value for \fBBROTLI_PARAM_LGWIN\fP parameter\&.
.SH "Typedef Documentation"
.PP
.SS "typedef enum \fBBrotliEncoderMode\fP \fBBrotliEncoderMode\fP"
.PP
Options for \fBBROTLI_PARAM_MODE\fP parameter\&.
.SS "typedef enum \fBBrotliEncoderOperation\fP \fBBrotliEncoderOperation\fP"
.PP
Operations that can be performed by streaming encoder\&.
.SS "typedef enum \fBBrotliEncoderParameter\fP \fBBrotliEncoderParameter\fP"
.PP
Options to be used with \fBBrotliEncoderSetParameter\fP\&.
.SS "typedef struct BrotliEncoderStateStruct \fBBrotliEncoderState\fP"
.PP
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\&.
.TP
\fB\fIBROTLI_OPERATION_FLUSH \fP\fP
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\&.
.PP
\fBWarning:\fP
.RS 4
Until flush is complete, client \fBSHOULD\fP \fBNOT\fP swap, reduce or extend input stream\&.
.RE
.PP
When flush is complete, output data will be sufficient for decoder to reproduce all the given input\&.
.TP
\fB\fIBROTLI_OPERATION_FINISH \fP\fP
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\&.
.PP
\fBWarning:\fP
.RS 4
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
.RS 4
Encoder may emit empty metadata blocks internally, to pad encoded stream to byte boundary\&.
.RE
.PP
\fBWarning:\fP
.RS 4
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
.RS 4
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\&.
.RE
.PP
.TP
\fB\fIBROTLI_PARAM_DISABLE_LITERAL_CONTEXT_MODELING \fP\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\&.
.TP
\fB\fIBROTLI_PARAM_LARGE_WINDOW \fP\fP
Flag that determines if 'Large Window Brotli' is used\&.
.TP
\fB\fIBROTLI_PARAM_NPOSTFIX \fP\fP
Recommended number of postfix bits (NPOSTFIX)\&. Encoder may change this value\&.
.PP
Range is from 0 to \fBBROTLI_MAX_NPOSTFIX\fP\&.
.TP
\fB\fIBROTLI_PARAM_NDIRECT \fP\fP
Recommended number of direct distance codes (NDIRECT)\&. Encoder may change this value\&.
.PP
Range is from 0 to (15 << NPOSTFIX) in steps of (1 << NPOSTFIX)\&.
.TP
\fB\fIBROTLI_PARAM_STREAM_OFFSET \fP\fP
Number of bytes of input stream already processed by a different instance\&.
.PP
\fBNote:\fP
.RS 4
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\&.
.SH "Function Documentation"
.PP
.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])"
.PP
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
.RS 4
If \fBBrotliEncoderMaxCompressedSize\fP(\fCinput_size\fP) returns non-zero value, then output is guaranteed to be no longer than that\&.
.PP
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
.RE
.PP
\fBParameters:\fP
.RS 4
\fIquality\fP quality parameter value, e\&.g\&. \fBBROTLI_DEFAULT_QUALITY\fP
.br
\fIlgwin\fP lgwin parameter value, e\&.g\&. \fBBROTLI_DEFAULT_WINDOW\fP
.br
\fImode\fP mode parameter value, e\&.g\&. \fBBROTLI_DEFAULT_MODE\fP
.br
\fIinput_size\fP size of \fCinput_buffer\fP
.br
\fIinput_buffer\fP input data buffer with at least \fCinput_size\fP addressable bytes
.br
\fIencoded_size\fP \fBin:\fP size of \fCencoded_buffer\fP;
.br
\fBout:\fP length of compressed data written to \fCencoded_buffer\fP, or \fC0\fP if compression fails
.br
\fIencoded_buffer\fP compressed data destination buffer
.RE
.PP
\fBReturns:\fP
.RS 4
\fBBROTLI_FALSE\fP in case of compression error
.PP
\fBBROTLI_FALSE\fP if output buffer is too small
.PP
\fBBROTLI_TRUE\fP otherwise
.RE
.PP
.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)"
.PP
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\&.
.PP
\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\&.
.PP
Internally workflow consists of 3 tasks:
.IP "1." 4
(optionally) copy input data to internal buffer
.IP "2." 4
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
.RS 4
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
.RS 4
\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
.RE
.PP
\fBReturns:\fP
.RS 4
\fBBROTLI_FALSE\fP if there was an error
.PP
\fBBROTLI_TRUE\fP otherwise
.RE
.PP
.SS "\fBBrotliEncoderState\fP* BrotliEncoderCreateInstance (\fBbrotli_alloc_func\fP alloc_func, \fBbrotli_free_func\fP free_func, void * opaque)"
.PP
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\&.
.PP
\fBParameters:\fP
.RS 4
\fIalloc_func\fP custom memory allocation function
.br
\fIfree_func\fP custom memory free function
.br
\fIopaque\fP custom memory manager handle
.RE
.PP
\fBReturns:\fP
.RS 4
\fC0\fP if instance can not be allocated or initialized
.PP
pointer to initialized \fBBrotliEncoderState\fP otherwise
.RE
.PP
.SS "void BrotliEncoderDestroyInstance (\fBBrotliEncoderState\fP * state)"
.PP
Deinitializes and frees \fBBrotliEncoderState\fP instance\&.
.PP
\fBParameters:\fP
.RS 4
\fIstate\fP decoder instance to be cleaned up and deallocated
.RE
.PP
.SS "\fBBROTLI_BOOL\fP BrotliEncoderHasMoreOutput (\fBBrotliEncoderState\fP * state)"
.PP
Checks if encoder has more output\&.
.PP
\fBParameters:\fP
.RS 4
\fIstate\fP encoder instance
.RE
.PP
\fBReturns:\fP
.RS 4
\fBBROTLI_TRUE\fP, if encoder has some unconsumed output
.PP
\fBBROTLI_FALSE\fP otherwise
.RE
.PP
.SS "\fBBROTLI_BOOL\fP BrotliEncoderIsFinished (\fBBrotliEncoderState\fP * state)"
.PP
Checks if encoder instance reached the final state\&.
.PP
\fBParameters:\fP
.RS 4
\fIstate\fP encoder instance
.RE
.PP
\fBReturns:\fP
.RS 4
\fBBROTLI_TRUE\fP if encoder is in a state where it reached the end of the input and produced all of the output
.PP
\fBBROTLI_FALSE\fP otherwise
.RE
.PP
.SS "size_t BrotliEncoderMaxCompressedSize (size_t input_size)"
.PP
Calculates the output size bound for the given \fCinput_size\fP\&.
.PP
\fBWarning:\fP
.RS 4
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\&.
.RE
.PP
\fBParameters:\fP
.RS 4
\fIinput_size\fP size of projected input
.RE
.PP
\fBReturns:\fP
.RS 4
\fC0\fP if result does not fit \fCsize_t\fP
.RE
.PP
.SS "\fBBROTLI_BOOL\fP BrotliEncoderSetParameter (\fBBrotliEncoderState\fP * state, \fBBrotliEncoderParameter\fP param, uint32_t value)"
.PP
Sets the specified parameter to the given encoder instance\&.
.PP
\fBParameters:\fP
.RS 4
\fIstate\fP encoder instance
.br
\fIparam\fP parameter to set
.br
\fIvalue\fP new parameter value
.RE
.PP
\fBReturns:\fP
.RS 4
\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
.RS 4
invalid values might be accepted in case they would not break encoding process\&.
.RE
.PP
.SS "const uint8_t* BrotliEncoderTakeOutput (\fBBrotliEncoderState\fP * state, size_t * size)"
.PP
Acquires pointer to internal output buffer\&. This method is used to make language bindings easier and more efficient:
.IP "1." 4
push data to \fBBrotliEncoderCompressStream\fP, until \fBBrotliEncoderHasMoreOutput\fP returns BROTL_TRUE
.IP "2." 4
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
.RS 4
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
.RS 4
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
.RS 4
\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
.RE
.PP
\fBReturns:\fP
.RS 4
pointer to output data
.RE
.PP
.SS "uint32_t BrotliEncoderVersion (void)"
.PP
Gets an encoder library version\&. Look at BROTLI_VERSION for more information\&.
.SH "Author"
.PP
Generated automatically by Doxygen for Brotli from the source code\&.
|