encode.c File Reference

#include <brotli/encode.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 "./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 "./quality.h"
#include "./ringbuffer.h"
#include "./utf8_util.h"
#include "./write_bits.h"

Data Structures
struct	BrotliEncoderStateStruct

Macros
#define	COPY_ARRAY(dst, src)

Typedefs
typedef enum BrotliEncoderStreamState	BrotliEncoderStreamState
typedef enum BrotliEncoderFlintState	BrotliEncoderFlintState
typedef struct BrotliEncoderStateStruct	BrotliEncoderStateStruct

Enumerations
enum	BrotliEncoderStreamState {   BROTLI_STREAM_PROCESSING = 0 , BROTLI_STREAM_FLUSH_REQUESTED = 1 , BROTLI_STREAM_FINISHED = 2 , BROTLI_STREAM_METADATA_HEAD = 3 ,   BROTLI_STREAM_METADATA_BODY = 4 }
enum	BrotliEncoderFlintState {   BROTLI_FLINT_NEEDS_2_BYTES = 2 , BROTLI_FLINT_NEEDS_1_BYTE = 1 , BROTLI_FLINT_WAITING_FOR_PROCESSING = 0 , BROTLI_FLINT_WAITING_FOR_FLUSHING = -1 ,   BROTLI_FLINT_DONE = -2 }

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, size_t *encoded_size, uint8_t *encoded_buffer)
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)

Macro Definition Documentation

COPY_ARRAY

#define COPY_ARRAY	(		dst,
			src )

Value:

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

Typedef Documentation

BrotliEncoderFlintState

typedef enum BrotliEncoderFlintState BrotliEncoderFlintState

BrotliEncoderStateStruct

typedef struct BrotliEncoderStateStruct BrotliEncoderStateStruct

BrotliEncoderStreamState

typedef enum BrotliEncoderStreamState BrotliEncoderStreamState

Enumeration Type Documentation

BrotliEncoderFlintState

enum BrotliEncoderFlintState

Enumerator
BROTLI_FLINT_NEEDS_2_BYTES
BROTLI_FLINT_NEEDS_1_BYTE
BROTLI_FLINT_WAITING_FOR_PROCESSING
BROTLI_FLINT_WAITING_FOR_FLUSHING
BROTLI_FLINT_DONE

BrotliEncoderStreamState

enum BrotliEncoderStreamState

Enumerator
BROTLI_STREAM_PROCESSING
BROTLI_STREAM_FLUSH_REQUESTED
BROTLI_STREAM_FINISHED
BROTLI_STREAM_METADATA_HEAD
BROTLI_STREAM_METADATA_BODY

Function Documentation

BrotliEncoderCompress()

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

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

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

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.