BaseTools/Source/C/BrotliCompress/enc/encode.h

   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 /* API for Brotli compression. */
   8
   9 #ifndef BROTLI_ENC_ENCODE_H_
  10 #define BROTLI_ENC_ENCODE_H_
  11
  12 #include "../common/types.h"
  13
  14 #if defined(__cplusplus) || defined(c_plusplus)
  15 extern "C" {
  16 #endif
  17
  18 static const int kBrotliMaxWindowBits = 24;
  19 static const int kBrotliMinWindowBits = 10;
  20 static const int kBrotliMinInputBlockBits = 16;
  21 static const int kBrotliMaxInputBlockBits = 24;
  22
  23 #define BROTLI_MIN_QUALITY 0
  24 #define BROTLI_MAX_QUALITY 11
  25
  26 typedef enum BrotliEncoderMode {
  27   /* Default compression mode. The compressor does not know anything in
  28      advance about the properties of the input. */
  29   BROTLI_MODE_GENERIC = 0,
  30   /* Compression mode for UTF-8 format text input. */
  31   BROTLI_MODE_TEXT = 1,
  32   /* Compression mode used in WOFF 2.0. */
  33   BROTLI_MODE_FONT = 2
  34 } BrotliEncoderMode;
  35
  36 #define BROTLI_DEFAULT_QUALITY 11
  37 #define BROTLI_DEFAULT_WINDOW 22
  38 #define BROTLI_DEFAULT_MODE BROTLI_MODE_GENERIC
  39
  40 typedef enum BrotliEncoderOperation {
  41   BROTLI_OPERATION_PROCESS = 0,
  42   /* Request output stream to flush. Performed when input stream is depleted
  43      and there is enough space in output stream. */
  44   BROTLI_OPERATION_FLUSH = 1,
  45   /* Request output stream to finish. Performed when input stream is depleted
  46      and there is enough space in output stream. */
  47   BROTLI_OPERATION_FINISH = 2
  48 } BrotliEncoderOperation;
  49
  50 typedef enum BrotliEncoderParameter {
  51   BROTLI_PARAM_MODE = 0,
  52   /* Controls the compression-speed vs compression-density tradeoffs. The higher
  53      the quality, the slower the compression. Range is 0 to 11. */
  54   BROTLI_PARAM_QUALITY = 1,
  55   /* Base 2 logarithm of the sliding window size. Range is 10 to 24. */
  56   BROTLI_PARAM_LGWIN = 2,
  57   /* Base 2 logarithm of the maximum input block size. Range is 16 to 24.
  58      If set to 0, the value will be set based on the quality. */
  59   BROTLI_PARAM_LGBLOCK = 3
  60 } BrotliEncoderParameter;
  61
  62 /* A state can not be reused for multiple brotli streams. */
  63 typedef struct BrotliEncoderStateStruct BrotliEncoderState;
  64
  65 BROTLI_BOOL BrotliEncoderSetParameter(
  66     BrotliEncoderState* state, BrotliEncoderParameter p, uint32_t value);
  67
  68 /* Creates the instance of BrotliEncoderState and initializes it.
  69    |alloc_func| and |free_func| MUST be both zero or both non-zero. In the case
  70    they are both zero, default memory allocators are used. |opaque| is passed to
  71    |alloc_func| and |free_func| when they are called. */
  72 BrotliEncoderState* BrotliEncoderCreateInstance(brotli_alloc_func alloc_func,
  73                                                 brotli_free_func free_func,
  74                                                 void* opaque);
  75
  76 /* Deinitializes and frees BrotliEncoderState instance. */
  77 void BrotliEncoderDestroyInstance(BrotliEncoderState* state);
  78 /* The maximum input size that can be processed at once. */
  79 size_t BrotliEncoderInputBlockSize(BrotliEncoderState* state);
  80
  81 /* Encodes the data in |input_buffer| as a meta-block and writes it to
  82    |encoded_buffer| (|*encoded_size should| be set to the size of
  83    |encoded_buffer|) and sets |*encoded_size| to the number of bytes that
  84    was written. The |input_size| must not be greater than input_block_size().
  85    Returns false if there was an error and true otherwise. */
  86 BROTLI_BOOL BrotliEncoderWriteMetaBlock(
  87     BrotliEncoderState* state, const size_t input_size,
  88     const uint8_t* input_buffer, const BROTLI_BOOL is_last,
  89     size_t* encoded_size, uint8_t* encoded_buffer);
  90
  91 /* Writes a metadata meta-block containing the given input to encoded_buffer.
  92    |*encoded_size| should be set to the size of the encoded_buffer.
  93    Sets |*encoded_size| to the number of bytes that was written.
  94    Note that the given input data will not be part of the sliding window and
  95    thus no backward references can be made to this data from subsequent
  96    metablocks. |input_size| must not be greater than 2^24 and provided
  97    |*encoded_size| must not be less than |input_size| + 6.
  98    Returns false if there was an error and true otherwise. */
  99 BROTLI_BOOL BrotliEncoderWriteMetadata(
 100     BrotliEncoderState* state, const size_t input_size,
 101     const uint8_t* input_buffer, const BROTLI_BOOL is_last,
 102     size_t* encoded_size, uint8_t* encoded_buffer);
 103
 104 /* Writes a zero-length meta-block with end-of-input bit set to the
 105    internal output buffer and copies the output buffer to |encoded_buffer|
 106    (|*encoded_size| should be set to the size of |encoded_buffer|) and sets
 107    |*encoded_size| to the number of bytes written.
 108    Returns false if there was an error and true otherwise. */
 109 BROTLI_BOOL BrotliEncoderFinishStream(
 110     BrotliEncoderState* state, size_t* encoded_size, uint8_t* encoded_buffer);
 111
 112 /* Copies the given input data to the internal ring buffer of the compressor.
 113    No processing of the data occurs at this time and this function can be
 114    called multiple times before calling WriteBrotliData() to process the
 115    accumulated input. At most input_block_size() bytes of input data can be
 116    copied to the ring buffer, otherwise the next WriteBrotliData() will fail.
 117  */
 118 void BrotliEncoderCopyInputToRingBuffer(BrotliEncoderState* state,
 119                                         const size_t input_size,
 120                                         const uint8_t* input_buffer);
 121
 122 /* Processes the accumulated input data and sets |*out_size| to the length of
 123    the new output meta-block, or to zero if no new output meta-block has been
 124    created (in this case the processed input data is buffered internally).
 125    If |*out_size| is positive, |*output| points to the start of the output
 126    data. If |is_last| or |force_flush| is 1, an output meta-block is always
 127    created. However, until |is_last| is 1 encoder may retain up to 7 bits
 128    of the last byte of output. To force encoder to dump the remaining bits
 129    use WriteMetadata() to append an empty meta-data block.
 130    Returns false if the size of the input data is larger than
 131    input_block_size(). */
 132 BROTLI_BOOL BrotliEncoderWriteData(
 133     BrotliEncoderState* state, const BROTLI_BOOL is_last,
 134     const BROTLI_BOOL force_flush, size_t* out_size, uint8_t** output);
 135
 136 /* Fills the new state with a dictionary for LZ77, warming up the ringbuffer,
 137    e.g. for custom static dictionaries for data formats.
 138    Not to be confused with the built-in transformable dictionary of Brotli.
 139    To decode, use BrotliSetCustomDictionary() of the decoder with the same
 140    dictionary. */
 141 void BrotliEncoderSetCustomDictionary(BrotliEncoderState* state, size_t size,
 142                                       const uint8_t* dict);
 143
 144 /* Returns buffer size that is large enough to contain BrotliEncoderCompress
 145    output for any input.
 146    Returns 0 if result does not fit size_t. */
 147 size_t BrotliEncoderMaxCompressedSize(size_t input_size);
 148
 149 /* Compresses the data in |input_buffer| into |encoded_buffer|, and sets
 150    |*encoded_size| to the compressed length.
 151    BROTLI_DEFAULT_QUALITY, BROTLI_DEFAULT_WINDOW and BROTLI_DEFAULT_MODE should
 152    be used as |quality|, |lgwin| and |mode| if there are no specific
 153    requirements to encoder speed and compression ratio.
 154    If compression fails, |*encoded_size| is set to 0.
 155    If BrotliEncoderMaxCompressedSize(|input_size|) is not zero, then
 156    |*encoded_size| is never set to the bigger value.
 157    Returns false if there was an error and true otherwise. */
 158 BROTLI_BOOL BrotliEncoderCompress(
 159     int quality, int lgwin, BrotliEncoderMode mode, size_t input_size,
 160     const uint8_t* input_buffer, size_t* encoded_size, uint8_t* encoded_buffer);
 161
 162 /* Progressively compress input stream and push produced bytes to output stream.
 163    Internally workflow consists of 3 tasks:
 164     * (optional) copy input data to internal buffer
 165     * actually compress data and (optionally) store it to internal buffer
 166     * (optional) copy compressed bytes from internal buffer to output stream
 167    Whenever all 3 tasks can't move forward anymore, or error occurs, this
 168    method returns.
 169
 170    |available_in| and |next_in| represent input stream; when X bytes of input
 171    are consumed, X is subtracted from |available_in| and added to |next_in|.
 172    |available_out| and |next_out| represent output stream; when Y bytes are
 173    pushed to output, Y is subtracted from |available_out| and added to
 174    |next_out|. |total_out|, if it is not a null-pointer, is assigned to the
 175    total amount of bytes pushed by the instance of encoder to output.
 176
 177    |op| is used to perform flush or finish the stream.
 178
 179    Flushing the stream means forcing encoding of all input passed to encoder and
 180    completing the current output block, so it could be fully decoded by stream
 181    decoder. To perform flush |op| must be set to BROTLI_OPERATION_FLUSH. Under
 182    some circumstances (e.g. lack of output stream capacity) this operation would
 183    require several calls to BrotliEncoderCompressStream. The method must be
 184    called again until both input stream is depleted and encoder has no more
 185    output (see BrotliEncoderHasMoreOutput) after the method is called.
 186
 187    Finishing the stream means encoding of all input passed to encoder and
 188    adding specific "final" marks, so stream decoder could determine that stream
 189    is complete. To perform finish |op| must be set to BROTLI_OPERATION_FINISH.
 190    Under some circumstances (e.g. lack of output stream capacity) this operation
 191    would require several calls to BrotliEncoderCompressStream. The method must
 192    be called again until both input stream is depleted and encoder has no more
 193    output (see BrotliEncoderHasMoreOutput) after the method is called.
 194
 195    WARNING: when flushing and finishing, |op| should not change until operation
 196    is complete; input stream should not be refilled as well.
 197
 198    Returns false if there was an error and true otherwise.
 199 */
 200 BROTLI_BOOL BrotliEncoderCompressStream(
 201     BrotliEncoderState* s, BrotliEncoderOperation op, size_t* available_in,
 202     const uint8_t** next_in, size_t* available_out, uint8_t** next_out,
 203     size_t* total_out);
 204
 205 /* Check if encoder is in "finished" state, i.e. no more input is acceptable and
 206    no more output will be produced.
 207    Works only with BrotliEncoderCompressStream workflow.
 208    Returns 1 if stream is finished and 0 otherwise. */
 209 BROTLI_BOOL BrotliEncoderIsFinished(BrotliEncoderState* s);
 210
 211 /* Check if encoder has more output bytes in internal buffer.
 212    Works only with BrotliEncoderCompressStream workflow.
 213    Returns 1 if has more output (in internal buffer) and 0 otherwise. */
 214 BROTLI_BOOL BrotliEncoderHasMoreOutput(BrotliEncoderState* s);
 215
 216
 217 #if defined(__cplusplus) || defined(c_plusplus)
 218 }  /* extern "C" */
 219 #endif
 220
 221 #endif  /* BROTLI_ENC_ENCODE_H_ */