1 /* Copyright 2013 Google Inc. All Rights Reserved. 2 3 Distributed under MIT license. 4 See file LICENSE for detail or copy at https://opensource.org/licenses/MIT 5 */ 6 7 /** 8 * @file 9 * API for Brotli compression. 10 */ 11 12 #ifndef BROTLI_ENC_ENCODE_H_ 13 #define BROTLI_ENC_ENCODE_H_ 14 15 #include <brotli/port.h> 16 #include <brotli/types.h> 17 18 #if defined(__cplusplus) || defined(c_plusplus) 19 extern "C" { 20 #endif 21 22 /** Minimal value for ::BROTLI_PARAM_LGWIN parameter. */ 23 #define BROTLI_MIN_WINDOW_BITS 10 24 /** 25 * Maximal value for ::BROTLI_PARAM_LGWIN parameter. 26 * 27 * @note equal to @c BROTLI_MAX_DISTANCE_BITS constant. 28 */ 29 #define BROTLI_MAX_WINDOW_BITS 24 30 /** Minimal value for ::BROTLI_PARAM_LGBLOCK parameter. */ 31 #define BROTLI_MIN_INPUT_BLOCK_BITS 16 32 /** Maximal value for ::BROTLI_PARAM_LGBLOCK parameter. */ 33 #define BROTLI_MAX_INPUT_BLOCK_BITS 24 34 /** Minimal value for ::BROTLI_PARAM_QUALITY parameter. */ 35 #define BROTLI_MIN_QUALITY 0 36 /** Maximal value for ::BROTLI_PARAM_QUALITY parameter. */ 37 #define BROTLI_MAX_QUALITY 11 38 39 /** Options for ::BROTLI_PARAM_MODE parameter. */ 40 typedef enum BrotliEncoderMode { 41 /** 42 * Default compression mode. 43 * 44 * In this mode compressor does not know anything in advance about the 45 * properties of the input. 46 */ 47 BROTLI_MODE_GENERIC = 0, 48 /** Compression mode for UTF-8 formatted text input. */ 49 BROTLI_MODE_TEXT = 1, 50 /** Compression mode used in WOFF 2.0. */ 51 BROTLI_MODE_FONT = 2 52 } BrotliEncoderMode; 53 54 /** Default value for ::BROTLI_PARAM_QUALITY parameter. */ 55 #define BROTLI_DEFAULT_QUALITY 11 56 /** Default value for ::BROTLI_PARAM_LGWIN parameter. */ 57 #define BROTLI_DEFAULT_WINDOW 22 58 /** Default value for ::BROTLI_PARAM_MODE parameter. */ 59 #define BROTLI_DEFAULT_MODE BROTLI_MODE_GENERIC 60 61 /** Operations that can be performed by streaming encoder. */ 62 typedef enum BrotliEncoderOperation { 63 /** 64 * Process input. 65 * 66 * Encoder may postpone producing output, until it has processed enough input. 67 */ 68 BROTLI_OPERATION_PROCESS = 0, 69 /** 70 * Produce output for all processed input. 71 * 72 * Actual flush is performed when input stream is depleted and there is enough 73 * space in output stream. This means that client should repeat 74 * ::BROTLI_OPERATION_FLUSH operation until @p available_in becomes @c 0, and 75 * ::BrotliEncoderHasMoreOutput returns ::BROTLI_FALSE. If output is acquired 76 * via ::BrotliEncoderTakeOutput, then operation should be repeated after 77 * output buffer is drained. 78 * 79 * @warning Until flush is complete, client @b SHOULD @b NOT swap, 80 * reduce or extend input stream. 81 * 82 * When flush is complete, output data will be sufficient for decoder to 83 * reproduce all the given input. 84 */ 85 BROTLI_OPERATION_FLUSH = 1, 86 /** 87 * Finalize the stream. 88 * 89 * Actual finalization is performed when input stream is depleted and there is 90 * enough space in output stream. This means that client should repeat 91 * ::BROTLI_OPERATION_FINISH operation until @p available_in becomes @c 0, and 92 * ::BrotliEncoderHasMoreOutput returns ::BROTLI_FALSE. If output is acquired 93 * via ::BrotliEncoderTakeOutput, then operation should be repeated after 94 * output buffer is drained. 95 * 96 * @warning Until finalization is complete, client @b SHOULD @b NOT swap, 97 * reduce or extend input stream. 98 * 99 * Helper function ::BrotliEncoderIsFinished checks if stream is finalized and 100 * output fully dumped. 101 * 102 * Adding more input data to finalized stream is impossible. 103 */ 104 BROTLI_OPERATION_FINISH = 2, 105 /** 106 * Emit metadata block to stream. 107 * 108 * Metadata is opaque to Brotli: neither encoder, nor decoder processes this 109 * data or relies on it. It may be used to pass some extra information from 110 * encoder client to decoder client without interfering with main data stream. 111 * 112 * @note Encoder may emit empty metadata blocks internally, to pad encoded 113 * stream to byte boundary. 114 * 115 * @warning Until emitting metadata is complete client @b SHOULD @b NOT swap, 116 * reduce or extend input stream. 117 * 118 * @warning The whole content of input buffer is considered to be the content 119 * of metadata block. Do @b NOT @e append metadata to input stream, 120 * before it is depleted with other operations. 121 * 122 * Stream is soft-flushed before metadata block is emitted. Metadata block 123 * @b MUST be no longer than than 16MiB. 124 */ 125 BROTLI_OPERATION_EMIT_METADATA = 3 126 } BrotliEncoderOperation; 127 128 /** Options to be used with ::BrotliEncoderSetParameter. */ 129 typedef enum BrotliEncoderParameter { 130 /** 131 * Tune encoder for specific input. 132 * 133 * ::BrotliEncoderMode enumerates all available values. 134 */ 135 BROTLI_PARAM_MODE = 0, 136 /** 137 * The main compression speed-density lever. 138 * 139 * The higher the quality, the slower the compression. Range is 140 * from ::BROTLI_MIN_QUALITY to ::BROTLI_MAX_QUALITY. 141 */ 142 BROTLI_PARAM_QUALITY = 1, 143 /** 144 * Recommended sliding LZ77 window size. 145 * 146 * Encoder may reduce this value, e.g. if input is much smaller than 147 * window size. 148 * 149 * Window size is `(1 << value) - 16`. 150 * 151 * Range is from ::BROTLI_MIN_WINDOW_BITS to ::BROTLI_MAX_WINDOW_BITS. 152 */ 153 BROTLI_PARAM_LGWIN = 2, 154 /** 155 * Recommended input block size. 156 * 157 * Encoder may reduce this value, e.g. if input is much smaller than input 158 * block size. 159 * 160 * Range is from ::BROTLI_MIN_INPUT_BLOCK_BITS to 161 * ::BROTLI_MAX_INPUT_BLOCK_BITS. 162 * 163 * @note Bigger input block size allows better compression, but consumes more 164 * memory. \n The rough formula of memory used for temporary input 165 * storage is `3 << lgBlock`. 166 */ 167 BROTLI_PARAM_LGBLOCK = 3, 168 /** 169 * Flag that affects usage of "literal context modeling" format feature. 170 * 171 * This flag is a "decoding-speed vs compression ratio" trade-off. 172 */ 173 BROTLI_PARAM_DISABLE_LITERAL_CONTEXT_MODELING = 4, 174 /** 175 * Estimated total input size for all ::BrotliEncoderCompressStream calls. 176 * 177 * The default value is 0, which means that the total input size is unknown. 178 */ 179 BROTLI_PARAM_SIZE_HINT = 5 180 } BrotliEncoderParameter; 181 182 /** 183 * Opaque structure that holds encoder state. 184 * 185 * Allocated and initialized with ::BrotliEncoderCreateInstance. 186 * Cleaned up and deallocated with ::BrotliEncoderDestroyInstance. 187 */ 188 typedef struct BrotliEncoderStateStruct BrotliEncoderState; 189 190 /** 191 * Sets the specified parameter to the given encoder instance. 192 * 193 * @param state encoder instance 194 * @param param parameter to set 195 * @param value new parameter value 196 * @returns ::BROTLI_FALSE if parameter is unrecognized, or value is invalid 197 * @returns ::BROTLI_FALSE if value of parameter can not be changed at current 198 * encoder state (e.g. when encoding is started, window size might be 199 * already encoded and therefore it is impossible to change it) 200 * @returns ::BROTLI_TRUE if value is accepted 201 * @warning invalid values might be accepted in case they would not break 202 * encoding process. 203 */ 204 BROTLI_ENC_API BROTLI_BOOL BrotliEncoderSetParameter( 205 BrotliEncoderState* state, BrotliEncoderParameter param, uint32_t value); 206 207 /** 208 * Creates an instance of ::BrotliEncoderState and initializes it. 209 * 210 * @p alloc_func and @p free_func @b MUST be both zero or both non-zero. In the 211 * case they are both zero, default memory allocators are used. @p opaque is 212 * passed to @p alloc_func and @p free_func when they are called. 213 * 214 * @param alloc_func custom memory allocation function 215 * @param free_func custom memory fee function 216 * @param opaque custom memory manager handle 217 * @returns @c 0 if instance can not be allocated or initialized 218 * @returns pointer to initialized ::BrotliEncoderState otherwise 219 */ 220 BROTLI_ENC_API BrotliEncoderState* BrotliEncoderCreateInstance( 221 brotli_alloc_func alloc_func, brotli_free_func free_func, void* opaque); 222 223 /** 224 * Deinitializes and frees ::BrotliEncoderState instance. 225 * 226 * @param state decoder instance to be cleaned up and deallocated 227 */ 228 BROTLI_ENC_API void BrotliEncoderDestroyInstance(BrotliEncoderState* state); 229 230 /** 231 * Calculates the output size bound for the given @p input_size. 232 * 233 * @warning Result is not applicable to ::BrotliEncoderCompressStream output, 234 * because every "flush" adds extra overhead bytes, and some encoder 235 * settings (e.g. quality @c 0 and @c 1) might imply a "soft flush" 236 * after every chunk of input. 237 * 238 * @param input_size size of projected input 239 * @returns @c 0 if result does not fit @c size_t 240 */ 241 BROTLI_ENC_API size_t BrotliEncoderMaxCompressedSize(size_t input_size); 242 243 /** 244 * Performs one-shot memory-to-memory compression. 245 * 246 * Compresses the data in @p input_buffer into @p encoded_buffer, and sets 247 * @p *encoded_size to the compressed length. 248 * 249 * @note If ::BrotliEncoderMaxCompressedSize(@p input_size) returns non-zero 250 * value, then output is guaranteed to be no longer than that. 251 * 252 * @param quality quality parameter value, e.g. ::BROTLI_DEFAULT_QUALITY 253 * @param lgwin lgwin parameter value, e.g. ::BROTLI_DEFAULT_WINDOW 254 * @param mode mode parameter value, e.g. ::BROTLI_DEFAULT_MODE 255 * @param input_size size of @p input_buffer 256 * @param input_buffer input data buffer with at least @p input_size 257 * addressable bytes 258 * @param[in, out] encoded_size @b in: size of @p encoded_buffer; \n 259 * @b out: length of compressed data written to 260 * @p encoded_buffer, or @c 0 if compression fails 261 * @param encoded_buffer compressed data destination buffer 262 * @returns ::BROTLI_FALSE in case of compression error 263 * @returns ::BROTLI_FALSE if output buffer is too small 264 * @returns ::BROTLI_TRUE otherwise 265 */ 266 BROTLI_ENC_API BROTLI_BOOL BrotliEncoderCompress( 267 int quality, int lgwin, BrotliEncoderMode mode, size_t input_size, 268 const uint8_t input_buffer[BROTLI_ARRAY_PARAM(input_size)], 269 size_t* encoded_size, 270 uint8_t encoded_buffer[BROTLI_ARRAY_PARAM(*encoded_size)]); 271 272 /** 273 * Compresses input stream to output stream. 274 * 275 * The values @p *available_in and @p *available_out must specify the number of 276 * bytes addressable at @p *next_in and @p *next_out respectively. 277 * When @p *available_out is @c 0, @p next_out is allowed to be @c NULL. 278 * 279 * After each call, @p *available_in will be decremented by the amount of input 280 * bytes consumed, and the @p *next_in pointer will be incremented by that 281 * amount. Similarly, @p *available_out will be decremented by the amount of 282 * output bytes written, and the @p *next_out pointer will be incremented by 283 * that amount. 284 * 285 * @p total_out, if it is not a null-pointer, will be set to the number 286 * of bytes decompressed since the last @p state initialization. 287 * 288 * 289 * 290 * Internally workflow consists of 3 tasks: 291 * -# (optionally) copy input data to internal buffer 292 * -# actually compress data and (optionally) store it to internal buffer 293 * -# (optionally) copy compressed bytes from internal buffer to output stream 294 * 295 * Whenever all 3 tasks can't move forward anymore, or error occurs, this 296 * method returns the control flow to caller. 297 * 298 * @p op is used to perform flush, finish the stream, or inject metadata block. 299 * See ::BrotliEncoderOperation for more information. 300 * 301 * Flushing the stream means forcing encoding of all input passed to encoder and 302 * completing the current output block, so it could be fully decoded by stream 303 * decoder. To perform flush set @p op to ::BROTLI_OPERATION_FLUSH. 304 * Under some circumstances (e.g. lack of output stream capacity) this operation 305 * would require several calls to ::BrotliEncoderCompressStream. The method must 306 * be called again until both input stream is depleted and encoder has no more 307 * output (see ::BrotliEncoderHasMoreOutput) after the method is called. 308 * 309 * Finishing the stream means encoding of all input passed to encoder and 310 * adding specific "final" marks, so stream decoder could determine that stream 311 * is complete. To perform finish set @p op to ::BROTLI_OPERATION_FINISH. 312 * Under some circumstances (e.g. lack of output stream capacity) this operation 313 * would require several calls to ::BrotliEncoderCompressStream. The method must 314 * be called again until both input stream is depleted and encoder has no more 315 * output (see ::BrotliEncoderHasMoreOutput) after the method is called. 316 * 317 * @warning When flushing and finishing, @p op should not change until operation 318 * is complete; input stream should not be swapped, reduced or 319 * extended as well. 320 * 321 * @param state encoder instance 322 * @param op requested operation 323 * @param[in, out] available_in @b in: amount of available input; \n 324 * @b out: amount of unused input 325 * @param[in, out] next_in pointer to the next input byte 326 * @param[in, out] available_out @b in: length of output buffer; \n 327 * @b out: remaining size of output buffer 328 * @param[in, out] next_out compressed output buffer cursor; 329 * can be @c NULL if @p available_out is @c 0 330 * @param[out] total_out number of bytes produced so far; can be @c NULL 331 * @returns ::BROTLI_FALSE if there was an error 332 * @returns ::BROTLI_TRUE otherwise 333 */ 334 BROTLI_ENC_API BROTLI_BOOL BrotliEncoderCompressStream( 335 BrotliEncoderState* state, BrotliEncoderOperation op, size_t* available_in, 336 const uint8_t** next_in, size_t* available_out, uint8_t** next_out, 337 size_t* total_out); 338 339 /** 340 * Checks if encoder instance reached the final state. 341 * 342 * @param state encoder instance 343 * @returns ::BROTLI_TRUE if encoder is in a state where it reached the end of 344 * the input and produced all of the output 345 * @returns ::BROTLI_FALSE otherwise 346 */ 347 BROTLI_ENC_API BROTLI_BOOL BrotliEncoderIsFinished(BrotliEncoderState* state); 348 349 /** 350 * Checks if encoder has more output. 351 * 352 * @param state encoder instance 353 * @returns ::BROTLI_TRUE, if encoder has some unconsumed output 354 * @returns ::BROTLI_FALSE otherwise 355 */ 356 BROTLI_ENC_API BROTLI_BOOL BrotliEncoderHasMoreOutput( 357 BrotliEncoderState* state); 358 359 /** 360 * Acquires pointer to internal output buffer. 361 * 362 * This method is used to make language bindings easier and more efficient: 363 * -# push data to ::BrotliEncoderCompressStream, 364 * until ::BrotliEncoderHasMoreOutput returns BROTL_TRUE 365 * -# use ::BrotliEncoderTakeOutput to peek bytes and copy to language-specific 366 * entity 367 * 368 * Also this could be useful if there is an output stream that is able to 369 * consume all the provided data (e.g. when data is saved to file system). 370 * 371 * @attention After every call to ::BrotliEncoderTakeOutput @p *size bytes of 372 * output are considered consumed for all consecutive calls to the 373 * instance methods; returned pointer becomes invalidated as well. 374 * 375 * @note Encoder output is not guaranteed to be contiguous. This means that 376 * after the size-unrestricted call to ::BrotliEncoderTakeOutput, 377 * immediate next call to ::BrotliEncoderTakeOutput may return more data. 378 * 379 * @param state encoder instance 380 * @param[in, out] size @b in: number of bytes caller is ready to take, @c 0 if 381 * any amount could be handled; \n 382 * @b out: amount of data pointed by returned pointer and 383 * considered consumed; \n 384 * out value is never greater than in value, unless it is @c 0 385 * @returns pointer to output data 386 */ 387 BROTLI_ENC_API const uint8_t* BrotliEncoderTakeOutput( 388 BrotliEncoderState* state, size_t* size); 389 390 391 /** 392 * Gets an encoder library version. 393 * 394 * Look at BROTLI_VERSION for more information. 395 */ 396 BROTLI_ENC_API uint32_t BrotliEncoderVersion(void); 397 398 #if defined(__cplusplus) || defined(c_plusplus) 399 } /* extern "C" */ 400 #endif 401 402 #endif /* BROTLI_ENC_ENCODE_H_ */ 403
