Heatshrink encoder

Encoder state diagram:

digraph { graph [label="Encoder state machine", labelloc="t"] start [style="invis", shape="point"] not_full filled search yield_tag_bit yield_literal yield_br_length yield_br_index save_backlog flush_bits done [peripheries=2] start->not_full [label="start"] not_full->not_full [label="sink(), not full", color="blue"] not_full->filled [label="sink(), buffer is full", color="blue"] not_full->filled [label="finish(), set is_finished", color="blue"] filled->search [label="indexing (if any)"] search->yield_tag_bit [label="literal"] search->yield_tag_bit [label="match found"] search->save_backlog [label="input exhausted, not finishing"] search->flush_bits [label="input exhausted, finishing"] yield_tag_bit->yield_tag_bit [label="poll(), full buf", color="red"] yield_tag_bit->yield_literal [label="poll(), literal", color="red"] yield_tag_bit->yield_br_index [label="poll(), match", color="red"] yield_literal->yield_literal [label="poll(), full buf", color="red"] yield_literal->search [label="done"] yield_br_index->yield_br_index [label="poll(), full buf", color="red"] yield_br_index->yield_br_length [label="poll()", color="red"] yield_br_length->yield_br_length [label="poll(), full buf", color="red"] yield_br_length->search [label="done"] save_backlog->not_full [label="expect more input"] flush_bits->flush_bits [label="poll(), full buf", color="red"] flush_bits->done [label="poll(), flushed", color="red"] flush_bits->done [label="no more output"] }

Heatshrink Encoder API.

This header file defines the API for the Heatshrink encoder library.

Defines

HEATSHRINK_ENCODER_WINDOW_BITS(HSE)
HEATSHRINK_ENCODER_LOOKAHEAD_BITS(HSE)
HEATSHRINK_ENCODER_INDEX(HSE)

Enums

enum HSE_sink_res

Sink result codes.

These are the possible return values for the heatshrink_encoder_sink function.

Values:

enumerator HSER_SINK_OK

Data successfully sunk into the input buffer.

enumerator HSER_SINK_ERROR_NULL

NULL argument error.

enumerator HSER_SINK_ERROR_MISUSE

API misuse error.

enum HSE_poll_res

Poll result codes.

These are the possible return values for the heatshrink_encoder_poll function.

Values:

enumerator HSER_POLL_EMPTY

Input exhausted.

enumerator HSER_POLL_MORE

Poll again for more output.

enumerator HSER_POLL_ERROR_NULL

NULL argument error.

enumerator HSER_POLL_ERROR_MISUSE

API misuse error.

enum HSE_finish_res

Finish result codes.

These are the possible return values for the heatshrink_encoder_finish function.

Values:

enumerator HSER_FINISH_DONE

Encoding is complete.

enumerator HSER_FINISH_MORE

More output remaining; use poll.

enumerator HSER_FINISH_ERROR_NULL

NULL argument error.

Functions

heatshrink_encoder *heatshrink_encoder_alloc(uint8_t window_sz2, uint8_t lookahead_sz2)

Allocate a Heatshrink encoder.

Allocate a new encoder struct with specified window and lookahead sizes.

Note

Only for dynamic allocation mode

Parameters:

  • window_sz2 – Size of the window (2^n).

  • lookahead_sz2 – Size of the lookahead (2^n).

Returns:

Pointer to the allocated encoder, or NULL on error.

void heatshrink_encoder_free(heatshrink_encoder *hse)

Free a Heatshrink encoder.

Free the memory associated with an encoder.

Note

Only for dynamic allocation mode

Parameters:

hse – Pointer to the encoder to be freed.

void heatshrink_encoder_reset(heatshrink_encoder *hse)

Reset a Heatshrink encoder.

Reset an encoder to its initial state.

Parameters:

hse – Pointer to the encoder to be reset.

HSE_sink_res heatshrink_encoder_sink(heatshrink_encoder *hse, uint8_t *in_buf, size_t size, size_t *input_size)

Sink data into the encoder.

Sink up to SIZE bytes from IN_BUF into the encoder. The INPUT_SIZE is set to indicate how many bytes were actually sunk (in case a buffer was filled).

Parameters:

  • hse – Pointer to the encoder.

  • in_buf – Pointer to the input buffer.

  • size – Size of the input data.

  • input_size – Pointer to the variable indicating the number of bytes actually sunk.

Returns:

HSE_sink_res value indicating the result of the operation.

HSE_poll_res heatshrink_encoder_poll(heatshrink_encoder *hse, uint8_t *out_buf, size_t out_buf_size, size_t *output_size)

Poll for output from the encoder.

Poll for output from the encoder, copying at most OUT_BUF_SIZE bytes into OUT_BUF (setting OUTPUT_SIZE to the actual amount copied).

Parameters:

  • hse – Pointer to the encoder.

  • out_buf – Pointer to the output buffer.

  • out_buf_size – Size of the output buffer.

  • output_size – Pointer to the variable indicating the number of bytes actually output.

Returns:

HSE_poll_res value indicating the result of the operation.

HSE_finish_res heatshrink_encoder_finish(heatshrink_encoder *hse)

Notify the encoder that the input stream is finished.

Notify the encoder that the input stream is finished. If the return value is HSER_FINISH_MORE, there is still more output, so call heatshrink_encoder_poll and repeat.

Parameters:

hse – Pointer to the encoder.

Returns:

HSE_finish_res value indicating the result of the operation.

struct hs_index
#include <heatshrink_encoder.h>

Public Members

uint16_t size
int16_t index[]
struct heatshrink_encoder
#include <heatshrink_encoder.h>

Heatshrink encoder structure.

This structure represents a Heatshrink encoder. It contains various fields necessary for the encoding process.

Public Members

uint16_t input_size

Bytes in the input buffer.

uint16_t match_scan_index
uint16_t match_length
uint16_t match_pos
uint16_t outgoing_bits

Enqueued outgoing bits.

uint8_t outgoing_bits_count
uint8_t flags
uint8_t state

Current state machine node.

uint8_t current_byte

Current byte of output.

uint8_t bit_index

Current bit index.

uint8_t window_sz2

2^n size of window.

uint8_t lookahead_sz2

2^n size of lookahead.

struct hs_index *search_index
uint8_t buffer[]