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

   1 /* Copyright 2016 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 /* C++ API for Brotli compression. */
   8
   9 #ifndef BROTLI_ENC_COMPRESSOR_H_
  10 #define BROTLI_ENC_COMPRESSOR_H_
  11
  12 #include "./encode.h"
  13 #include "./streams.h"
  14
  15 namespace brotli {
  16
  17 static const int kMinWindowBits = kBrotliMinWindowBits;
  18 static const int kMaxWindowBits = kBrotliMaxWindowBits;
  19 static const int kMinInputBlockBits = kBrotliMinInputBlockBits;
  20 static const int kMaxInputBlockBits = kBrotliMaxInputBlockBits;
  21
  22 struct BrotliParams {
  23   BrotliParams(void)
  24       : mode(MODE_GENERIC),
  25         quality(11),
  26         lgwin(22),
  27         lgblock(0),
  28         enable_dictionary(true),
  29         enable_transforms(false),
  30         greedy_block_split(false),
  31         enable_context_modeling(true) {}
  32
  33   enum Mode {
  34     /* Default compression mode. The compressor does not know anything in
  35        advance about the properties of the input. */
  36     MODE_GENERIC = 0,
  37     /* Compression mode for UTF-8 format text input. */
  38     MODE_TEXT = 1,
  39     /* Compression mode used in WOFF 2.0. */
  40     MODE_FONT = 2
  41   };
  42   Mode mode;
  43
  44   /* Controls the compression-speed vs compression-density tradeoffs. The higher
  45      the |quality|, the slower the compression. Range is 0 to 11. */
  46   int quality;
  47   /* Base 2 logarithm of the sliding window size. Range is 10 to 24. */
  48   int lgwin;
  49   /* Base 2 logarithm of the maximum input block size. Range is 16 to 24.
  50      If set to 0, the value will be set based on the quality. */
  51   int lgblock;
  52
  53   /* These settings are deprecated and will be ignored.
  54      All speed vs. size compromises are controlled by the |quality| param. */
  55   bool enable_dictionary;
  56   bool enable_transforms;
  57   bool greedy_block_split;
  58   bool enable_context_modeling;
  59 };
  60
  61 /* An instance can not be reused for multiple brotli streams. */
  62 class BrotliCompressor {
  63  public:
  64   explicit BrotliCompressor(BrotliParams params);
  65   ~BrotliCompressor(void);
  66
  67   /* The maximum input size that can be processed at once. */
  68   size_t input_block_size(void) const {
  69     return BrotliEncoderInputBlockSize(state_);
  70   }
  71
  72   /* Encodes the data in |input_buffer| as a meta-block and writes it to
  73      |encoded_buffer| (|*encoded_size should| be set to the size of
  74      |encoded_buffer|) and sets |*encoded_size| to the number of bytes that
  75      was written. The |input_size| must not be greater than input_block_size().
  76      Returns false if there was an error and true otherwise. */
  77   bool WriteMetaBlock(const size_t input_size,
  78                       const uint8_t* input_buffer,
  79                       const bool is_last,
  80                       size_t* encoded_size,
  81                       uint8_t* encoded_buffer);
  82
  83   /* Writes a metadata meta-block containing the given input to encoded_buffer.
  84      |*encoded_size| should be set to the size of the encoded_buffer.
  85      Sets |*encoded_size| to the number of bytes that was written.
  86      Note that the given input data will not be part of the sliding window and
  87      thus no backward references can be made to this data from subsequent
  88      metablocks. |input_size| must not be greater than 2^24 and provided
  89      |*encoded_size| must not be less than |input_size| + 6.
  90      Returns false if there was an error and true otherwise. */
  91   bool WriteMetadata(const size_t input_size,
  92                      const uint8_t* input_buffer,
  93                      const bool is_last,
  94                      size_t* encoded_size,
  95                      uint8_t* encoded_buffer);
  96
  97   /* Writes a zero-length meta-block with end-of-input bit set to the
  98      internal output buffer and copies the output buffer to |encoded_buffer|
  99      (|*encoded_size| should be set to the size of |encoded_buffer|) and sets
 100      |*encoded_size| to the number of bytes written.
 101      Returns false if there was an error and true otherwise. */
 102   bool FinishStream(size_t* encoded_size, uint8_t* encoded_buffer);
 103
 104   /* Copies the given input data to the internal ring buffer of the compressor.
 105      No processing of the data occurs at this time and this function can be
 106      called multiple times before calling WriteBrotliData() to process the
 107      accumulated input. At most input_block_size() bytes of input data can be
 108      copied to the ring buffer, otherwise the next WriteBrotliData() will fail.
 109    */
 110   void CopyInputToRingBuffer(const size_t input_size,
 111                              const uint8_t* input_buffer);
 112
 113   /* Processes the accumulated input data and sets |*out_size| to the length of
 114      the new output meta-block, or to zero if no new output meta-block has been
 115      created (in this case the processed input data is buffered internally).
 116      If |*out_size| is positive, |*output| points to the start of the output
 117      data. If |is_last| or |force_flush| is true, an output meta-block is always
 118      created. However, until |is_last| is true encoder may retain up to 7 bits
 119      of the last byte of output. To force encoder to dump the remaining bits
 120      use WriteMetadata() to append an empty meta-data block.
 121      Returns false if the size of the input data is larger than
 122      input_block_size(). */
 123   bool WriteBrotliData(const bool is_last, const bool force_flush,
 124                        size_t* out_size, uint8_t** output);
 125
 126   /* Fills the new state with a dictionary for LZ77, warming up the ringbuffer,
 127      e.g. for custom static dictionaries for data formats.
 128      Not to be confused with the built-in transformable dictionary of Brotli.
 129      To decode, use BrotliSetCustomDictionary() of the decoder with the same
 130      dictionary. */
 131   void BrotliSetCustomDictionary(size_t size, const uint8_t* dict);
 132
 133   /* No-op, but we keep it here for API backward-compatibility. */
 134   void WriteStreamHeader(void) {}
 135
 136  private:
 137   BrotliEncoderState* state_;
 138 };
 139
 140 /* Compresses the data in |input_buffer| into |encoded_buffer|, and sets
 141    |*encoded_size| to the compressed length.
 142    Returns 0 if there was an error and 1 otherwise. */
 143 int BrotliCompressBuffer(BrotliParams params,
 144                          size_t input_size,
 145                          const uint8_t* input_buffer,
 146                          size_t* encoded_size,
 147                          uint8_t* encoded_buffer);
 148
 149 /* Same as above, but uses the specified input and output classes instead
 150    of reading from and writing to pre-allocated memory buffers. */
 151 int BrotliCompress(BrotliParams params, BrotliIn* in, BrotliOut* out);
 152
 153 /* Before compressing the data, sets a custom LZ77 dictionary with
 154    BrotliCompressor::BrotliSetCustomDictionary. */
 155 int BrotliCompressWithCustomDictionary(size_t dictsize, const uint8_t* dict,
 156                                        BrotliParams params,
 157                                        BrotliIn* in, BrotliOut* out);
 158
 159 }  /* namespace brotli */
 160
 161 #endif  /* BROTLI_ENC_COMPRESSOR_H_ */