brotli/enc/encode.h

/* 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;

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;

/* DEPRECATED */
typedef struct BrotliEncoderParams {
  BrotliEncoderMode mode;
  /* Controls the compression-speed vs compression-density tradeoffs. The higher
     the |quality|, the slower the compression. Range is 0 to 11. */
  int quality;
  /* Base 2 logarithm of the sliding window size. Range is 10 to 24. */
  int lgwin;
  /* 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. */
  int lgblock;
} BrotliEncoderParams;

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;

int 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 0 if there was an error and 1 otherwise. */
int BrotliEncoderWriteMetaBlock(BrotliEncoderState* state,
                                const size_t input_size,
                                const uint8_t* input_buffer, const int 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 0 if there was an error and 1 otherwise. */
int BrotliEncoderWriteMetadata(BrotliEncoderState* state,
                               const size_t input_size,
                               const uint8_t* input_buffer, const int 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 0 if there was an error and 1 otherwise. */
int 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 0 if the size of the input data is larger than
   input_block_size(). */
int BrotliEncoderWriteData(BrotliEncoderState* state, const int is_last,
                           const int 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 0 if there was an error and 1 otherwise. */
int 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 0 if there was an error and 1 otherwise.
*/
int 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. */
int 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. */
int BrotliEncoderHasMoreOutput(BrotliEncoderState* s);


#if defined(__cplusplus) || defined(c_plusplus)
}  /* extern "C" */
#endif

#endif  /* BROTLI_ENC_ENCODE_H_ */