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
|
/* Copyright 2013 Google Inc. All Rights Reserved.
Distributed under MIT license.
See file LICENSE for detail or copy at https://opensource.org/licenses/MIT
*/
/* API for Brotli compression. */
#ifndef BROTLI_ENC_ENCODE_H_
#define BROTLI_ENC_ENCODE_H_
#include "../common/types.h"
#if defined(__cplusplus) || defined(c_plusplus)
extern "C" {
#endif
static const int kBrotliMaxWindowBits = 24;
static const int kBrotliMinWindowBits = 10;
static const int kBrotliMinInputBlockBits = 16;
static const int kBrotliMaxInputBlockBits = 24;
#define BROTLI_MIN_QUALITY 0
#define BROTLI_MAX_QUALITY 11
typedef enum BrotliEncoderMode {
/* Default compression mode. The compressor does not know anything in
advance about the properties of the input. */
BROTLI_MODE_GENERIC = 0,
/* Compression mode for UTF-8 format text input. */
BROTLI_MODE_TEXT = 1,
/* Compression mode used in WOFF 2.0. */
BROTLI_MODE_FONT = 2
} BrotliEncoderMode;
#define BROTLI_DEFAULT_QUALITY 11
#define BROTLI_DEFAULT_WINDOW 22
#define BROTLI_DEFAULT_MODE BROTLI_MODE_GENERIC
typedef enum BrotliEncoderOperation {
BROTLI_OPERATION_PROCESS = 0,
/* Request output stream to flush. Performed when input stream is depleted
and there is enough space in output stream. */
BROTLI_OPERATION_FLUSH = 1,
/* Request output stream to finish. Performed when input stream is depleted
and there is enough space in output stream. */
BROTLI_OPERATION_FINISH = 2
} BrotliEncoderOperation;
typedef enum BrotliEncoderParameter {
BROTLI_PARAM_MODE = 0,
/* Controls the compression-speed vs compression-density tradeoffs. The higher
the quality, the slower the compression. Range is 0 to 11. */
BROTLI_PARAM_QUALITY = 1,
/* Base 2 logarithm of the sliding window size. Range is 10 to 24. */
BROTLI_PARAM_LGWIN = 2,
/* Base 2 logarithm of the maximum input block size. Range is 16 to 24.
If set to 0, the value will be set based on the quality. */
BROTLI_PARAM_LGBLOCK = 3
} BrotliEncoderParameter;
/* A state can not be reused for multiple brotli streams. */
typedef struct BrotliEncoderStateStruct BrotliEncoderState;
BROTLI_BOOL BrotliEncoderSetParameter(
BrotliEncoderState* state, BrotliEncoderParameter p, uint32_t value);
/* Creates the instance of BrotliEncoderState and initializes it.
|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. */
BrotliEncoderState* BrotliEncoderCreateInstance(brotli_alloc_func alloc_func,
brotli_free_func free_func,
void* opaque);
/* Deinitializes and frees BrotliEncoderState instance. */
void BrotliEncoderDestroyInstance(BrotliEncoderState* state);
/* The maximum input size that can be processed at once. */
size_t BrotliEncoderInputBlockSize(BrotliEncoderState* state);
/* Encodes the data in |input_buffer| as a meta-block and writes it to
|encoded_buffer| (|*encoded_size should| be set to the size of
|encoded_buffer|) and sets |*encoded_size| to the number of bytes that
was written. The |input_size| must not be greater than input_block_size().
Returns false if there was an error and true otherwise. */
BROTLI_BOOL BrotliEncoderWriteMetaBlock(
BrotliEncoderState* state, const size_t input_size,
const uint8_t* input_buffer, const BROTLI_BOOL is_last,
size_t* encoded_size, uint8_t* encoded_buffer);
/* Writes a metadata meta-block containing the given input to encoded_buffer.
|*encoded_size| should be set to the size of the encoded_buffer.
Sets |*encoded_size| to the number of bytes that was written.
Note that the given input data will not be part of the sliding window and
thus no backward references can be made to this data from subsequent
metablocks. |input_size| must not be greater than 2^24 and provided
|*encoded_size| must not be less than |input_size| + 6.
Returns false if there was an error and true otherwise. */
BROTLI_BOOL BrotliEncoderWriteMetadata(
BrotliEncoderState* state, const size_t input_size,
const uint8_t* input_buffer, const BROTLI_BOOL is_last,
size_t* encoded_size, uint8_t* encoded_buffer);
/* Writes a zero-length meta-block with end-of-input bit set to the
internal output buffer and copies the output buffer to |encoded_buffer|
(|*encoded_size| should be set to the size of |encoded_buffer|) and sets
|*encoded_size| to the number of bytes written.
Returns false if there was an error and true otherwise. */
BROTLI_BOOL BrotliEncoderFinishStream(
BrotliEncoderState* state, size_t* encoded_size, uint8_t* encoded_buffer);
/* Copies the given input data to the internal ring buffer of the compressor.
No processing of the data occurs at this time and this function can be
called multiple times before calling WriteBrotliData() to process the
accumulated input. At most input_block_size() bytes of input data can be
copied to the ring buffer, otherwise the next WriteBrotliData() will fail.
*/
void BrotliEncoderCopyInputToRingBuffer(BrotliEncoderState* state,
const size_t input_size,
const uint8_t* input_buffer);
/* Processes the accumulated input data and sets |*out_size| to the length of
the new output meta-block, or to zero if no new output meta-block has been
created (in this case the processed input data is buffered internally).
If |*out_size| is positive, |*output| points to the start of the output
data. If |is_last| or |force_flush| is 1, an output meta-block is always
created. However, until |is_last| is 1 encoder may retain up to 7 bits
of the last byte of output. To force encoder to dump the remaining bits
use WriteMetadata() to append an empty meta-data block.
Returns false if the size of the input data is larger than
input_block_size(). */
BROTLI_BOOL BrotliEncoderWriteData(
BrotliEncoderState* state, const BROTLI_BOOL is_last,
const BROTLI_BOOL force_flush, size_t* out_size, uint8_t** output);
/* Fills the new state with a dictionary for LZ77, warming up the ringbuffer,
e.g. for custom static dictionaries for data formats.
Not to be confused with the built-in transformable dictionary of Brotli.
To decode, use BrotliSetCustomDictionary() of the decoder with the same
dictionary. */
void BrotliEncoderSetCustomDictionary(BrotliEncoderState* state, size_t size,
const uint8_t* dict);
/* Returns buffer size that is large enough to contain BrotliEncoderCompress
output for any input.
Returns 0 if result does not fit size_t. */
size_t BrotliEncoderMaxCompressedSize(size_t input_size);
/* Compresses the data in |input_buffer| into |encoded_buffer|, and sets
|*encoded_size| to the compressed length.
BROTLI_DEFAULT_QUALITY, BROTLI_DEFAULT_WINDOW and BROTLI_DEFAULT_MODE should
be used as |quality|, |lgwin| and |mode| if there are no specific
requirements to encoder speed and compression ratio.
If compression fails, |*encoded_size| is set to 0.
If BrotliEncoderMaxCompressedSize(|input_size|) is not zero, then
|*encoded_size| is never set to the bigger value.
Returns false if there was an error and true otherwise. */
BROTLI_BOOL BrotliEncoderCompress(
int quality, int lgwin, BrotliEncoderMode mode, size_t input_size,
const uint8_t* input_buffer, size_t* encoded_size, uint8_t* encoded_buffer);
/* Progressively compress input stream and push produced bytes to output stream.
Internally workflow consists of 3 tasks:
* (optional) copy input data to internal buffer
* actually compress data and (optionally) store it to internal buffer
* (optional) copy compressed bytes from internal buffer to output stream
Whenever all 3 tasks can't move forward anymore, or error occurs, this
method returns.
|available_in| and |next_in| represent input stream; when X bytes of input
are consumed, X is subtracted from |available_in| and added to |next_in|.
|available_out| and |next_out| represent output stream; when Y bytes are
pushed to output, Y is subtracted from |available_out| and added to
|next_out|. |total_out|, if it is not a null-pointer, is assigned to the
total amount of bytes pushed by the instance of encoder to output.
|op| is used to perform flush or finish the stream.
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 |op| must be set 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 |op| must be set 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 operation
is complete; input stream should not be refilled as well.
Returns false if there was an error and true otherwise.
*/
BROTLI_BOOL BrotliEncoderCompressStream(
BrotliEncoderState* s, BrotliEncoderOperation op, size_t* available_in,
const uint8_t** next_in, size_t* available_out, uint8_t** next_out,
size_t* total_out);
/* Check if encoder is in "finished" state, i.e. no more input is acceptable and
no more output will be produced.
Works only with BrotliEncoderCompressStream workflow.
Returns 1 if stream is finished and 0 otherwise. */
BROTLI_BOOL BrotliEncoderIsFinished(BrotliEncoderState* s);
/* Check if encoder has more output bytes in internal buffer.
Works only with BrotliEncoderCompressStream workflow.
Returns 1 if has more output (in internal buffer) and 0 otherwise. */
BROTLI_BOOL BrotliEncoderHasMoreOutput(BrotliEncoderState* s);
#if defined(__cplusplus) || defined(c_plusplus)
} /* extern "C" */
#endif
#endif /* BROTLI_ENC_ENCODE_H_ */
|
