encode.c File Reference

#include <brotli/encode.h>
#include <brotli/shared_dictionary.h>
#include <brotli/types.h>
#include <stdlib.h>
#include <string.h>
#include "../common/constants.h"
#include "../common/context.h"
#include "../common/platform.h"
#include "../common/version.h"
#include "backward_references.h"
#include "backward_references_hq.h"
#include "bit_cost.h"
#include "brotli_bit_stream.h"
#include "compress_fragment.h"
#include "compress_fragment_two_pass.h"
#include "dictionary_hash.h"
#include "encoder_dict.h"
#include "entropy_encode.h"
#include "fast_log.h"
#include "hash.h"
#include "histogram.h"
#include "memory.h"
#include "metablock.h"
#include "prefix.h"
#include "state.h"
#include "quality.h"
#include "ringbuffer.h"
#include "utf8_util.h"
#include "write_bits.h"

Macros
#define	COPY_ARRAY(dst, src)
#define	BROTLI_ENCODER_ON_FINISH(s)

Functions
BROTLI_BOOL	BrotliEncoderSetParameter (BrotliEncoderState *state, BrotliEncoderParameter p, uint32_t value)
BrotliEncoderState *	BrotliEncoderCreateInstance (brotli_alloc_func alloc_func, brotli_free_func free_func, void *opaque)
void	BrotliEncoderDestroyInstance (BrotliEncoderState *state)
size_t	BrotliEncoderMaxCompressedSize (size_t input_size)
BROTLI_BOOL	BrotliEncoderCompress (int quality, int lgwin, BrotliEncoderMode mode, size_t input_size, const uint8_t input_buffer[BROTLI_ARRAY_PARAM(input_size)], size_t *encoded_size, uint8_t encoded_buffer[BROTLI_ARRAY_PARAM(*encoded_size)])
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)
BROTLI_BOOL	BrotliEncoderIsFinished (BrotliEncoderState *s)
BROTLI_BOOL	BrotliEncoderHasMoreOutput (BrotliEncoderState *s)
const uint8_t *	BrotliEncoderTakeOutput (BrotliEncoderState *s, size_t *size)
uint32_t	BrotliEncoderVersion (void)
BrotliEncoderPreparedDictionary *	BrotliEncoderPrepareDictionary (BrotliSharedDictionaryType type, size_t size, const uint8_t data[BROTLI_ARRAY_PARAM(size)], int quality, brotli_alloc_func alloc_func, brotli_free_func free_func, void *opaque)
void	BrotliEncoderDestroyPreparedDictionary (BrotliEncoderPreparedDictionary *dictionary)
BROTLI_BOOL	BrotliEncoderAttachPreparedDictionary (BrotliEncoderState *state, const BrotliEncoderPreparedDictionary *dictionary)
size_t	BrotliEncoderEstimatePeakMemoryUsage (int quality, int lgwin, size_t input_size)
size_t	BrotliEncoderGetPreparedDictionarySize (const BrotliEncoderPreparedDictionary *prepared_dictionary)

Macro Definition Documentation

BROTLI_ENCODER_ON_FINISH

#define BROTLI_ENCODER_ON_FINISH

(

s

)

Value:

(void)(s);

COPY_ARRAY

#define COPY_ARRAY	(		dst,
			src )

Value:

memcpy(dst, src, sizeof(src));

Function Documentation

BrotliEncoderAttachPreparedDictionary()

BROTLI_BOOL BrotliEncoderAttachPreparedDictionary	(	BrotliEncoderState *	state,
		const BrotliEncoderPreparedDictionary *	dictionary )

Attaches a prepared dictionary of any type to the encoder. Can be used multiple times to attach multiple dictionaries. The dictionary type was determined by BrotliEncoderPrepareDictionary. Multiple raw prefix dictionaries and/or max 1 serialized dictionary with custom words can be attached.

Returns

BROTLI_FALSE in case of error

BROTLI_TRUE otherwise

BrotliEncoderCompress()

BROTLI_BOOL BrotliEncoderCompress	(	int	quality,
		int	lgwin,
		BrotliEncoderMode	mode,
		size_t	input_size,
		const uint8_t	input_buffer[BROTLI_ARRAY_PARAM(input_size)],
		size_t *	encoded_size,
		uint8_t	encoded_buffer[BROTLI_ARRAY_PARAM(*encoded_size)] )

Performs one-shot memory-to-memory compression.

Compresses the data in input_buffer into encoded_buffer, and sets *encoded_size to the compressed length.

Note

If BrotliEncoderMaxCompressedSize(input_size) returns non-zero value, then output is guaranteed to be no longer than that.

If lgwin is greater than BROTLI_MAX_WINDOW_BITS then resulting stream might be incompatible with RFC 7932; to decode such streams, decoder should be configured with BROTLI_DECODER_PARAM_LARGE_WINDOW = 1

Parameters

	quality	quality parameter value, e.g. BROTLI_DEFAULT_QUALITY
	lgwin	lgwin parameter value, e.g. BROTLI_DEFAULT_WINDOW
	mode	mode parameter value, e.g. BROTLI_DEFAULT_MODE
	input_size	size of input_buffer
	input_buffer	input data buffer with at least input_size addressable bytes
[in,out]	encoded_size	in: size of encoded_buffer; out: length of compressed data written to encoded_buffer, or 0 if compression fails
	encoded_buffer	compressed data destination buffer

Returns

BROTLI_FALSE in case of compression error

BROTLI_FALSE if output buffer is too small

BROTLI_TRUE otherwise

BrotliEncoderCompressStream()

BROTLI_BOOL BrotliEncoderCompressStream	(	BrotliEncoderState *	state,
		BrotliEncoderOperation	op,
		size_t *	available_in,
		const uint8_t **	next_in,
		size_t *	available_out,
		uint8_t **	next_out,
		size_t *	total_out )

Compresses input stream to output stream.

The values *available_in and *available_out must specify the number of bytes addressable at *next_in and *next_out respectively. When *available_out is 0, next_out is allowed to be NULL.

After each call, *available_in will be decremented by the amount of input bytes consumed, and the *next_in pointer will be incremented by that amount. Similarly, *available_out will be decremented by the amount of output bytes written, and the *next_out pointer will be incremented by that amount.

total_out, if it is not a null-pointer, will be set to the number of bytes compressed since the last state initialization.

Internally workflow consists of 3 tasks:

1. (optionally) copy input data to internal buffer
2. actually compress data and (optionally) store it to internal buffer
3. (optionally) copy compressed bytes from internal buffer to output stream

Whenever all 3 tasks can't move forward anymore, or error occurs, this method returns the control flow to caller.

op is used to perform flush, finish the stream, or inject metadata block. See BrotliEncoderOperation for more information.

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 set op 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 set op 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 swapped, reduced or extended as well.

Parameters

	state	encoder instance
	op	requested operation
[in,out]	available_in	in: amount of available input; out: amount of unused input
[in,out]	next_in	pointer to the next input byte
[in,out]	available_out	in: length of output buffer; out: remaining size of output buffer
[in,out]	next_out	compressed output buffer cursor; can be NULL if available_out is 0
[out]	total_out	number of bytes produced so far; can be NULL

Returns

BROTLI_FALSE if there was an error

BROTLI_TRUE otherwise

BrotliEncoderCreateInstance()

BrotliEncoderState * BrotliEncoderCreateInstance	(	brotli_alloc_func	alloc_func,
		brotli_free_func	free_func,
		void *	opaque )

Creates an 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. free_func has to return without doing anything when asked to free a NULL pointer.

Parameters

alloc_func	custom memory allocation function
free_func	custom memory free function
opaque	custom memory manager handle

Returns

0 if instance can not be allocated or initialized

pointer to initialized BrotliEncoderState otherwise

BrotliEncoderDestroyInstance()

void BrotliEncoderDestroyInstance

(

BrotliEncoderState *

state

)

Deinitializes and frees BrotliEncoderState instance.

Parameters

state

decoder instance to be cleaned up and deallocated

BrotliEncoderDestroyPreparedDictionary()

void BrotliEncoderDestroyPreparedDictionary

(

BrotliEncoderPreparedDictionary *

dictionary

)

BrotliEncoderEstimatePeakMemoryUsage()

size_t BrotliEncoderEstimatePeakMemoryUsage	(	int	quality,
		int	lgwin,
		size_t	input_size )

BrotliEncoderGetPreparedDictionarySize()

size_t BrotliEncoderGetPreparedDictionarySize

(

const BrotliEncoderPreparedDictionary *

prepared_dictionary

)

BrotliEncoderHasMoreOutput()

BROTLI_BOOL BrotliEncoderHasMoreOutput

(

BrotliEncoderState *

state

)

Checks if encoder has more output.

Parameters

state

encoder instance

Returns

BROTLI_TRUE, if encoder has some unconsumed output

BROTLI_FALSE otherwise

BrotliEncoderIsFinished()

BROTLI_BOOL BrotliEncoderIsFinished

(

BrotliEncoderState *

state

)

Checks if encoder instance reached the final state.

Parameters

state

encoder instance

Returns

BROTLI_TRUE if encoder is in a state where it reached the end of the input and produced all of the output

BROTLI_FALSE otherwise

BrotliEncoderMaxCompressedSize()

size_t BrotliEncoderMaxCompressedSize

(

size_t

input_size

)

Calculates the output size bound for the given input_size.

Warning

Result is only valid if quality is at least 2 and, in case BrotliEncoderCompressStream was used, no flushes (BROTLI_OPERATION_FLUSH) were performed.

Parameters

input_size

size of projected input

Returns

0 if result does not fit size_t

BrotliEncoderPrepareDictionary()

BrotliEncoderPreparedDictionary * BrotliEncoderPrepareDictionary	(	BrotliSharedDictionaryType	type,
		size_t	size,
		const uint8_t	data[BROTLI_ARRAY_PARAM(size)],
		int	quality,
		brotli_alloc_func	alloc_func,
		brotli_free_func	free_func,
		void *	opaque )

BrotliEncoderSetParameter()

BROTLI_BOOL BrotliEncoderSetParameter	(	BrotliEncoderState *	state,
		BrotliEncoderParameter	param,
		uint32_t	value )

Sets the specified parameter to the given encoder instance.

Parameters

state	encoder instance
param	parameter to set
value	new parameter value

Returns

BROTLI_FALSE if parameter is unrecognized, or value is invalid

BROTLI_FALSE if value of parameter can not be changed at current encoder state (e.g. when encoding is started, window size might be already encoded and therefore it is impossible to change it)

BROTLI_TRUE if value is accepted

Warning

invalid values might be accepted in case they would not break encoding process.

BrotliEncoderTakeOutput()

const uint8_t * BrotliEncoderTakeOutput	(	BrotliEncoderState *	state,
		size_t *	size )

Acquires pointer to internal output buffer.

This method is used to make language bindings easier and more efficient:

1. push data to BrotliEncoderCompressStream, until BrotliEncoderHasMoreOutput returns BROTL_TRUE
2. use BrotliEncoderTakeOutput to peek bytes and copy to language-specific entity

Also this could be useful if there is an output stream that is able to consume all the provided data (e.g. when data is saved to file system).

Attention

After every call to BrotliEncoderTakeOutput *size bytes of output are considered consumed for all consecutive calls to the instance methods; returned pointer becomes invalidated as well.

Note

Encoder output is not guaranteed to be contiguous. This means that after the size-unrestricted call to BrotliEncoderTakeOutput, immediate next call to BrotliEncoderTakeOutput may return more data.

Parameters

	state	encoder instance
[in,out]	size	in: number of bytes caller is ready to take, 0 if any amount could be handled; out: amount of data pointed by returned pointer and considered consumed; out value is never greater than in value, unless it is 0

Returns

pointer to output data

BrotliEncoderVersion()

uint32_t BrotliEncoderVersion

(

void

)

Gets an encoder library version.

Look at BROTLI_VERSION for more information.