t85.h File Reference

Go to the source code of this file.

Typedefs
typedef struct t85_encode_state_s	t85_encode_state_t
typedef struct t85_decode_state_s	t85_decode_state_t
Enumerations
enum	{ T85_TPBON = 0x08, T85_VLENGTH = 0x20, T85_LRLTWO = 0x40 }
Functions
int	t85_encode_image_complete (t85_encode_state_t *s)
	Check if we are at the end of the current document page.
int	t85_encode_get (t85_encode_state_t *s, uint8_t buf[], size_t max_len)
	Get the next chunk of the current document page. The document will be padded for the current minimum scan line time.
int	t85_encode_set_row_read_handler (t85_encode_state_t *s, t4_row_read_handler_t handler, void *user_data)
	Set the row read handler for a T.85 encode context.
logging_state_t *	t85_encode_get_logging_state (t85_encode_state_t *s)
	Get the logging context associated with a T.85 encode context.
t85_encode_state_t *	t85_encode_init (t85_encode_state_t *s, uint32_t image_width, uint32_t image_length, t4_row_read_handler_t handler, void *user_data)
	Prepare to encode an image in T.85 format.
int	t85_encode_restart (t85_encode_state_t *s, uint32_t image_width, uint32_t image_length)
	Restart a T.85 encode context.
int	t85_encode_release (t85_encode_state_t *s)
int	t85_encode_free (t85_encode_state_t *s)
void	t85_encode_set_options (t85_encode_state_t *s, uint32_t l0, int mx, int options)
	Set the T.85 options.
void	t85_encode_comment (t85_encode_state_t *s, const uint8_t comment[], size_t len)
	Insert a comment in the encoded file.
int	t85_encode_set_image_width (t85_encode_state_t *s, uint32_t image_width)
	Set the image width.
int	t85_encode_set_image_length (t85_encode_state_t *s, uint32_t length)
	Alter the length of a T.85 encoded image. The new length cannot be greater than the originally specified length. If the new length is less than the current length it will be silently adjusted to the current length. Therefore, adjust the length to 1 will make the currently encoded length the final length.
uint32_t	t85_encode_get_image_width (t85_encode_state_t *s)
	Get the width of the image.
uint32_t	t85_encode_get_image_length (t85_encode_state_t *s)
	Get the length of the image.
int	t85_encode_get_compressed_image_size (t85_encode_state_t *s)
	Get the size of the compressed image, in bits.
void	t85_encode_abort (t85_encode_state_t *s)
	Stop image encoding prematurely.
logging_state_t *	t85_decode_get_logging_state (t85_decode_state_t *s)
	Get the logging context associated with a T.85 decode context.
t85_decode_state_t *	t85_decode_init (t85_decode_state_t *s, t4_row_write_handler_t handler, void *user_data)
	Prepare to decode an image in T.85 format.
int	t85_decode_new_plane (t85_decode_state_t *s)
int	t85_decode_restart (t85_decode_state_t *s)
int	t85_decode_release (t85_decode_state_t *s)
int	t85_decode_free (t85_decode_state_t *s)
uint32_t	t85_decode_get_image_width (t85_decode_state_t *s)
	Get the width of the image.
uint32_t	t85_decode_get_image_length (t85_decode_state_t *s)
	Get the length of the image.
int	t85_decode_get_compressed_image_size (t85_decode_state_t *s)
	Get the size of the compressed image, in bits.
int	t85_decode_set_row_write_handler (t85_decode_state_t *s, t4_row_write_handler_t handler, void *user_data)
	Set the row handler routine.
int	t85_decode_set_comment_handler (t85_decode_state_t *s, uint32_t max_comment_len, t4_row_write_handler_t handler, void *user_data)
	Set the comment handler routine.
int	t85_decode_set_image_size_constraints (t85_decode_state_t *s, uint32_t max_xd, uint32_t max_yd)
	Set constraints on the received image size.
void	t85_decode_rx_status (t85_decode_state_t *s, int status)
	Inform the T.85 decode engine of a status change in the signal source (end of tx, rx signal change, etc.).
int	t85_decode_put (t85_decode_state_t *s, const uint8_t data[], size_t len)
	Decode a chunk of T.85 data.

---

Detailed Description

---

Typedef Documentation

typedef struct t85_decode_state_s t85_decode_state_t

State of a working instance of the T.85 decoder

typedef struct t85_encode_state_s t85_encode_state_t

State of a working instance of the T.85 encoder

---

Enumeration Type Documentation

anonymous enum

Bits in the option byte of the T.82 BIH which are valid for T.85

Enumerator:

T85_TPBON	Enable typical prediction (bottom)
T85_VLENGTH	Variable length image
T85_LRLTWO	Lowest-resolution-layer is a two-line template

---

Function Documentation

int t85_decode_get_compressed_image_size

(

t85_decode_state_t *

s

)

Get the size of the compressed image, in bits.

Parameters:

s

The T.85 context.

Returns:

The size of the compressed image, in bits.

Referenced by t4_rx_get_transfer_statistics().

uint32_t t85_decode_get_image_length

(

t85_decode_state_t *

s

)

Get the length of the image.

Parameters:

s

The T.85 context.

Returns:

The length of the image, in pixels.

Referenced by t4_rx_end_page(), and t4_rx_get_transfer_statistics().

uint32_t t85_decode_get_image_width

(

t85_decode_state_t *

s

)

Get the width of the image.

Parameters:

s

The T.85 context.

Returns:

The width of the image, in pixels.

Referenced by t4_rx_get_transfer_statistics().

logging_state_t* t85_decode_get_logging_state

(

t85_decode_state_t *

s

)

Get the logging context associated with a T.85 decode context.

Get the logging context associated with a T.85 decode context.

Parameters:

s

The T.85 decode context.

Returns:

A pointer to the logging context

t85_decode_state_t* t85_decode_init	(	t85_decode_state_t *	s,
		t4_row_write_handler_t	handler,
		void *	user_data
	)

Prepare to decode an image in T.85 format.

Parameters:

	s	The T.85 context.
	handler	A callback routine to handle decoded image rows.
	user_data	An opaque pointer passed to handler.

Returns:

A pointer to the context, or NULL if there was a problem.

Referenced by t4_rx_set_rx_encoding().

int t85_decode_put	(	t85_decode_state_t *	s,
		const uint8_t	data[],
		size_t	len
	)

Decode a chunk of T.85 data.

Parameters:

	s	The T.85 context.
	data	The data to be decoded.
	len	The length of the data to be decoded.

Returns:

0 for OK.

References t85_decode_state_s::bytes_per_row, t85_decode_state_s::end_of_data, T4_DECODE_ABORTED, T4_DECODE_INTERRUPT, T4_DECODE_INVALID_DATA, T4_DECODE_MORE_DATA, T4_DECODE_NOMEM, T4_DECODE_OK, T85_LRLTWO, T85_VLENGTH, and t85_decode_state_s::y.

Referenced by t4_rx_end_page(), t4_rx_put(), and t85_decode_rx_status().

void t85_decode_rx_status	(	t85_decode_state_t *	s,
		int	status
	)

Inform the T.85 decode engine of a status change in the signal source (end of tx, rx signal change, etc.).

After the final BIE byte has been delivered to t85_decode_put_xx(), it may still return T85_MORE_DATA when the T85_VLENGTH option was used, and no NEWLEN marker section has appeared yet. This is because such a BIE is not self-terminating (i.e. there could still be a NEWLEN followed by an SDNORM or SDRST at the very end of the final stripe, which needs to be processed before the final row is output. See ITU-T Recommendation T.85, Appendix I). Therefore, after the last byte has been delivered, call this routine to signal the end of the BIE. This is necessary to allow the routine to finish processing BIEs with option T85_VLENGTH that do not actually contain any NEWLEN marker section.

Parameters:

	s	The T.85 context.
	status	The type of status change which occured.

References SIG_STATUS_CARRIER_DOWN, SIG_STATUS_CARRIER_UP, SIG_STATUS_END_OF_DATA, SIG_STATUS_TRAINING_FAILED, SIG_STATUS_TRAINING_IN_PROGRESS, SIG_STATUS_TRAINING_SUCCEEDED, signal_status_to_str(), span_log(), and t85_decode_put().

int t85_decode_set_comment_handler	(	t85_decode_state_t *	s,
		uint32_t	max_comment_len,
		t4_row_write_handler_t	handler,
		void *	user_data
	)

Set the comment handler routine.

Parameters:

	s	The T.85 context.
	max_comment_len	The maximum length of comment to be passed to the handler.
	handler	A callback routine to handle decoded comment.
	user_data	An opaque pointer passed to handler.

Returns:

0 for OK.

int t85_decode_set_image_size_constraints	(	t85_decode_state_t *	s,
		uint32_t	max_xd,
		uint32_t	max_yd
	)

Set constraints on the received image size.

A maliciously constructed T.85 image could consume too much memory, and constitute a denial of service attack on the system. This function allows constraints to be applied.

Parameters:

	s	The T.85 context.
	max_xd	The maximum permitted width of the full image, in pixels
	max_yd	The maximum permitted height of the full image, in pixels

Returns:

0 for OK

Referenced by t4_rx_set_rx_encoding().

int t85_decode_set_row_write_handler	(	t85_decode_state_t *	s,
		t4_row_write_handler_t	handler,
		void *	user_data
	)

Set the row handler routine.

Parameters:

	s	The T.85 context.
	handler	A callback routine to handle decoded image rows.
	user_data	An opaque pointer passed to handler.

Returns:

0 for OK.

Referenced by t4_rx_set_row_write_handler().

void t85_encode_abort

(

t85_encode_state_t *

s

)

Stop image encoding prematurely.

Parameters:

s

The T.85 context.

void t85_encode_comment	(	t85_encode_state_t *	s,
		const uint8_t	comment[],
		size_t	len
	)

Insert a comment in the encoded file.

Parameters:

	s	The T.85 context.
	comment	The comment. Note that this is not a C string, and may contain any bytes.
	len	The length of the comment.

int t85_encode_get	(	t85_encode_state_t *	s,
		uint8_t	buf[],
		size_t	max_len
	)

Get the next chunk of the current document page. The document will be padded for the current minimum scan line time.

Parameters:

	s	The T.85 context.
	buf	The buffer into which the chunk is to written.
	max_len	The maximum length of the chunk.

Returns:

The actual length of the chunk. If this is less than max_len it indicates that the end of the document has been reached.

Referenced by t4_tx_get().

int t85_encode_get_compressed_image_size

(

t85_encode_state_t *

s

)

Get the size of the compressed image, in bits.

Parameters:

s

The T.85 context.

Returns:

The size of the compressed image, in bits.

Referenced by t4_tx_get_transfer_statistics().

uint32_t t85_encode_get_image_length

(

t85_encode_state_t *

s

)

Get the length of the image.

Parameters:

s

The T.85 context.

Returns:

The length of the image, in pixels.

Referenced by t4_tx_get_transfer_statistics().

uint32_t t85_encode_get_image_width

(

t85_encode_state_t *

s

)

Get the width of the image.

Parameters:

s

The T.85 context.

Returns:

The width of the image, in pixels.

Referenced by t4_tx_get_transfer_statistics().

logging_state_t* t85_encode_get_logging_state

(

t85_encode_state_t *

s

)

Get the logging context associated with a T.85 encode context.

Get the logging context associated with a T.85 encode context.

Parameters:

s

The T.85 encode context.

Returns:

A pointer to the logging context

int t85_encode_image_complete

(

t85_encode_state_t *

s

)

Check if we are at the end of the current document page.

Parameters:

s

The T.85 context.

Returns:

0 for more data to come. SIG_STATUS_END_OF_DATA for no more data.

References SIG_STATUS_END_OF_DATA.

Referenced by t4_tx_image_complete().

t85_encode_state_t* t85_encode_init	(	t85_encode_state_t *	s,
		uint32_t	image_width,
		uint32_t	image_length,
		t4_row_read_handler_t	handler,
		void *	user_data
	)

Prepare to encode an image in T.85 format.

Parameters:

	s	The T.85 context.
	image_width	Image width, in pixels.
	image_length	Image length, in pixels.
	handler	A callback routine to handle encoded image rows.
	user_data	An opaque pointer passed to handler.

Returns:

A pointer to the context, or NULL if there was a problem.

References t85_encode_restart(), T85_TPBON, and T85_VLENGTH.

Referenced by t4_tx_set_tx_encoding().

int t85_encode_restart	(	t85_encode_state_t *	s,
		uint32_t	image_width,
		uint32_t	image_length
	)

Restart a T.85 encode context.

Parameters:

	s	The T.85 context.
	image	width The image width, in pixels.

Returns:

0 for success, otherwise -1.

References t85_encode_set_image_width().

Referenced by t4_tx_start_page(), and t85_encode_init().

int t85_encode_set_image_length	(	t85_encode_state_t *	s,
		uint32_t	length
	)

Alter the length of a T.85 encoded image. The new length cannot be greater than the originally specified length. If the new length is less than the current length it will be silently adjusted to the current length. Therefore, adjust the length to 1 will make the currently encoded length the final length.

Parameters:

	s	The T.85 context.
	length	The new image length, in pixels.

Returns:

0 if OK, or -1 if the request was not valid.

References T85_VLENGTH, and t85_decode_state_s::y.

int t85_encode_set_image_width	(	t85_encode_state_t *	s,
		uint32_t	image_width
	)

Set the image width.

Parameters:

	s	The T.85 context.
	width	The width of the image.

Returns:

0 for success, otherwise -1.

Referenced by t4_tx_set_image_width(), and t85_encode_restart().

void t85_encode_set_options	(	t85_encode_state_t *	s,
		uint32_t	l0,
		int	mx,
		int	options
	)

Set the T.85 options.

Parameters:

s

The T.85 context. l0 ??? mx ??? options ???.

References T85_LRLTWO, T85_TPBON, T85_VLENGTH, and t85_decode_state_s::yd.

int t85_encode_set_row_read_handler	(	t85_encode_state_t *	s,
		t4_row_read_handler_t	handler,
		void *	user_data
	)

Set the row read handler for a T.85 encode context.

Parameters:

	s	The T.85 context.
	handler	A pointer to the handler routine.
	user_data	An opaque pointer passed to the handler routine.

Returns:

0 for success, otherwise -1.