spandsp: t4_rx.h File Reference

spandsp 0.0.6

t4_rx.h File Reference

Go to the source code of this file.

## Classes
struct | t4_stats_t

## Typedefs
typedef int(* | t4_row_write_handler_t) (void *user_data, const uint8_t buf[], size_t len)
typedef struct t4_state_s | t4_state_t
typedef struct t4_state_s | t4_rx_state_t

## Enumerations
enum | t4_image_compression_t { T4_COMPRESSION_NONE = 0 , T4_COMPRESSION_ITU_T4_1D = 1 , T4_COMPRESSION_ITU_T4_2D = 2 , T4_COMPRESSION_ITU_T6 = 3 , T4_COMPRESSION_ITU_T85 = 4 , T4_COMPRESSION_ITU_T85_L0 = 5 , T4_COMPRESSION_ITU_T43 = 6 , T4_COMPRESSION_ITU_T45 = 7 , T4_COMPRESSION_ITU_T42 = 8 , T4_COMPRESSION_ITU_SYCC_T42 = 9 }
enum | t4_image_types_t { T4_IMAGE_TYPE_BILEVEL = 0 , T4_IMAGE_TYPE_GRAY_8BIT = 1 , T4_IMAGE_TYPE_GRAY_12BIT = 2 , T4_IMAGE_TYPE_COLOUR_8BIT = 3 , T4_IMAGE_TYPE_COLOUR_12BIT = 4 }
enum | t4_image_x_resolution_t { T4_X_RESOLUTION_R4 = 4016 , T4_X_RESOLUTION_R8 = 8031 , T4_X_RESOLUTION_300 = 11811 , T4_X_RESOLUTION_R16 = 16063 , T4_X_RESOLUTION_600 = 23622 , T4_X_RESOLUTION_800 = 31496 , T4_X_RESOLUTION_1200 = 47244 }
enum | t4_image_y_resolution_t { T4_Y_RESOLUTION_STANDARD = 3850 , T4_Y_RESOLUTION_FINE = 7700 , T4_Y_RESOLUTION_300 = 11811 , T4_Y_RESOLUTION_SUPERFINE = 15400 , T4_Y_RESOLUTION_600 = 23622 , T4_Y_RESOLUTION_800 = 31496 , T4_Y_RESOLUTION_1200 = 47244 }
enum | t4_image_width_t { T4_WIDTH_R4_A4 = 864 , T4_WIDTH_R4_B4 = 1024 , T4_WIDTH_R4_A3 = 1216 , T4_WIDTH_R8_A4 = 1728 , T4_WIDTH_R8_B4 = 2048 , T4_WIDTH_R8_A3 = 2432 , T4_WIDTH_300_A4 = 2592 , T4_WIDTH_300_B4 = 3072 , T4_WIDTH_300_A3 = 3648 , T4_WIDTH_R16_A4 = 3456 , T4_WIDTH_R16_B4 = 4096 , T4_WIDTH_R16_A3 = 4864 , T4_WIDTH_600_A4 = 5184 , T4_WIDTH_600_B4 = 6144 , T4_WIDTH_600_A3 = 7296 , T4_WIDTH_1200_A4 = 10368 , T4_WIDTH_1200_B4 = 12288 , T4_WIDTH_1200_A3 = 14592 }
enum | t4_image_length_t { T4_LENGTH_STANDARD_A4 = 1143 , T4_LENGTH_FINE_A4 = 2286 , T4_LENGTH_300_A4 = 4665 , T4_LENGTH_SUPERFINE_A4 = 4573 , T4_LENGTH_600_A4 = 6998 , T4_LENGTH_800_A4 = 9330 , T4_LENGTH_1200_A4 = 13996 , T4_LENGTH_STANDARD_B4 = 1401 , T4_LENGTH_FINE_B4 = 2802 , T4_LENGTH_300_B4 = 0 , T4_LENGTH_SUPERFINE_B4 = 5605 , T4_LENGTH_600_B4 = 0 , T4_LENGTH_800_B4 = 0 , T4_LENGTH_1200_B4 = 0 , T4_LENGTH_STANDARD_US_LETTER = 1075 , T4_LENGTH_FINE_US_LETTER = 2151 , T4_LENGTH_300_US_LETTER = 0 , T4_LENGTH_SUPERFINE_US_LETTER = 4302 , T4_LENGTH_600_US_LETTER = 0 , T4_LENGTH_800_US_LETTER = 0 , T4_LENGTH_1200_US_LETTER = 0 , T4_LENGTH_STANDARD_US_LEGAL = 1369 , T4_LENGTH_FINE_US_LEGAL = 2738 , T4_LENGTH_300_US_LEGAL = 0 , T4_LENGTH_SUPERFINE_US_LEGAL = 5476 , T4_LENGTH_600_US_LEGAL = 0 , T4_LENGTH_800_US_LEGAL = 0 , T4_LENGTH_1200_US_LEGAL = 0 }

## Functions
int | t4_rx_start_page (t4_rx_state_t *s)
| Prepare to receive the next page of the current document.
int | t4_rx_put_bit (t4_rx_state_t *s, int bit)
| Put a bit of the current document page.
int | t4_rx_put_byte (t4_rx_state_t *s, uint8_t byte)
| Put a byte of the current document page.
int | t4_rx_put_chunk (t4_rx_state_t *s, const uint8_t buf[], int len)
| Put a byte of the current document page.
int | t4_rx_end_page (t4_rx_state_t *s)
| Complete the reception of a page.
int | t4_rx_set_row_write_handler (t4_rx_state_t *s, t4_row_write_handler_t handler, void *user_data)
| Set the row write handler for a T.4 receive context.
void | t4_rx_set_rx_encoding (t4_rx_state_t *s, int encoding)
| Set the encoding for the received data.
void | t4_rx_set_image_width (t4_rx_state_t *s, int width)
| Set the expected width of the received image, in pixel columns.
void | t4_rx_set_y_resolution (t4_rx_state_t *s, int resolution)
| Set the row-to-row (y) resolution to expect for a received image.
void | t4_rx_set_x_resolution (t4_rx_state_t *s, int resolution)
| Set the column-to-column (x) resolution to expect for a received image.
void | t4_rx_set_dcs (t4_rx_state_t *s, const char *dcs)
| Set the DCS information of the fax, for inclusion in the file.
void | t4_rx_set_sub_address (t4_rx_state_t *s, const char *sub_address)
| Set the sub-address of the fax, for inclusion in the file.
void | t4_rx_set_far_ident (t4_rx_state_t *s, const char *ident)
| Set the identity of the remote machine, for inclusion in the file.
void | t4_rx_set_vendor (t4_rx_state_t *s, const char *vendor)
| Set the vendor of the remote machine, for inclusion in the file.
void | t4_rx_set_model (t4_rx_state_t *s, const char *model)
| Set the model of the remote machine, for inclusion in the file.
void | t4_rx_get_transfer_statistics (t4_rx_state_t *s, t4_stats_t *t)
| Get the current transfer statistics.
const char * | t4_encoding_to_str (int encoding)
| Get the short text name of an encoding format.
t4_rx_state_t * | t4_rx_init (t4_rx_state_t *s, const char *file, int output_encoding)
| Prepare for reception of a document.
int | t4_rx_release (t4_rx_state_t *s)
| End reception of a document. Tidy up and close the file. This should be used to end T.4 reception started with t4_rx_init.
int | t4_rx_free (t4_rx_state_t *s)
| End reception of a document. Tidy up, close the file and free the context. This should be used to end T.4 reception started with t4_rx_init.

## Typedef Documentation

## ◆ t4_row_write_handler_t

typedef int(* t4_row_write_handler_t) (void *user_data, const uint8_t buf[], size_t len)

This function is a callback from the image decoders, to write the decoded bi-level image, row by row. It is called for each row, with len set to the number of bytes per row. At the end of the image it is called with len set to zero, to indicate the end of image condition.

Returns
  0 for OK, or non-zero for a problem that requires the image be interrupted.

## ◆ t4_state_t

typedef struct t4_state_s t4_state_t

T.4 FAX compression/decompression descriptor. This defines the working state for a single instance of a T.4 FAX compression or decompression channel.

## Enumeration Type Documentation

## ◆ t4_image_compression_t

enum t4_image_compression_t

Supported compression modes.

Enumerator
T4_COMPRESSION_NONE | No compression
T4_COMPRESSION_ITU_T4_1D | T.1 1D compression
T4_COMPRESSION_ITU_T4_2D | T.4 2D compression
T4_COMPRESSION_ITU_T6 | T.6 2D compression
T4_COMPRESSION_ITU_T85 | T.85 monochrome JBIG coding with L0 fixed.
T4_COMPRESSION_ITU_T85_L0 | T.85 monochrome JBIG coding with L0 variable.
T4_COMPRESSION_ITU_T43 | T.43 colour JBIG coding
T4_COMPRESSION_ITU_T45 | T.45 run length colour compression
T4_COMPRESSION_ITU_T42 | T.42 + T.81 + T.30 Annex E colour JPEG coding
T4_COMPRESSION_ITU_SYCC_T42 | T.42 + T.81 + T.30 Annex K colour sYCC-JPEG coding

## ◆ t4_image_length_t

enum t4_image_length_t

Length of the various supported paper sizes, in pixels at the various Y resolutions. Paper sizes are A4 (215mm x 297mm) B4 (255mm x 364mm) A3 (303mm x 418.56mm) North American Letter (215.9mm x 279.4mm) North American Legal (215.9mm x 355.6mm) Unlimited

T.4 does not accurately define the maximum number of scan lines in a page. A wide variety of maximum row counts are used in the real world. It is important not to set our sending limit too high, or a receiving machine might split pages. It is important not to set it too low, or we might clip pages.

Values seen for standard resolution A4 pages include 1037, 1045, 1109, 1126 and 1143. 1109 seems the most-popular. At fine res 2150, 2196, 2200, 2237, 2252-2262, 2264, 2286, and 2394 are used. 2255 seems the most popular. We try to use balanced choices here.

## ◆ t4_image_types_t

enum t4_image_types_t

Image type

## ◆ t4_image_width_t

enum t4_image_width_t

Exact widths in PELs for the difference resolutions, and page widths. Note: The A4 widths also apply to North American letter and legal. The R4 resolution widths are not supported in recent versions of T.30 Only images of exactly these widths are acceptable for FAX transmisson.

R4 864 pels/215mm for ISO A4, North American Letter and Legal R4 1024 pels/255mm for ISO B4 R4 1216 pels/303mm for ISO A3 R8 1728 pels/215mm for ISO A4, North American Letter and Legal R8 2048 pels/255mm for ISO B4 R8 2432 pels/303mm for ISO A3 R16 3456 pels/215mm for ISO A4, North American Letter and Legal R16 4096 pels/255mm for ISO B4 R16 4864 pels/303mm for ISO A3

## ◆ t4_image_x_resolution_t

enum t4_image_x_resolution_t

Supported X resolutions, in pixels per metre.

## ◆ t4_image_y_resolution_t

enum t4_image_y_resolution_t

Supported Y resolutions, in pixels per metre.

## Function Documentation

## ◆ t4_encoding_to_str()

const char * t4_encoding_to_str | ( | int | encoding | ) |

Get the short text name of an encoding format.

Get the short text name of an encoding format.

Parameters

  encoding | The encoding type.

Returns
  A pointer to the string.

References T4_COMPRESSION_ITU_SYCC_T42, T4_COMPRESSION_ITU_T42, T4_COMPRESSION_ITU_T43, T4_COMPRESSION_ITU_T45, T4_COMPRESSION_ITU_T4_1D, T4_COMPRESSION_ITU_T4_2D, T4_COMPRESSION_ITU_T6, T4_COMPRESSION_ITU_T85, T4_COMPRESSION_ITU_T85_L0, and T4_COMPRESSION_NONE.

## ◆ t4_rx_end_page()

int t4_rx_end_page | ( | t4_rx_state_t * | s | ) |

Complete the reception of a page.

Parameters

  s | The T.4 receive context.

Returns
  0 for success, otherwise -1.

References t4_state_s::bytes_per_row, t4_t6_decode_state_s::consecutive_eols, t4_t6_decode_state_s::curr_bad_row_run, EOLS_TO_END_ANY_RX_PAGE, t4_state_s::image_buffer, t4_state_s::image_length, t4_state_s::image_size, t4_state_s::line_encoding, t4_state_s::logging, t4_t6_decode_state_s::longest_bad_row_run, t4_t6_decode_state_s::row_write_handler, t4_t6_decode_state_s::row_write_user_data, t4_t6_decode_state_s::rx_bits, t4_t6_decode_state_s::rx_bitstream, t4_t6_decode_state_s::rx_skip_bits, span_log(), T4_COMPRESSION_ITU_T6, and t4_rx_put_bit().

## ◆ t4_rx_free()

int t4_rx_free | ( | t4_rx_state_t * | s | ) |

End reception of a document. Tidy up, close the file and free the context. This should be used to end T.4 reception started with t4_rx_init.

Parameters

  s | The T.4 receive context.

Returns
  0 for success, otherwise -1.

References t4_rx_release().

## ◆ t4_rx_get_transfer_statistics()

void t4_rx_get_transfer_statistics | ( | t4_rx_state_t * | s,
|  | t4_stats_t * | t )

Get the current transfer statistics.

Get the current image transfer statistics.

Parameters

  s | The T.4 context.
  t | A pointer to a statistics structure.

References t4_stats_t::bad_rows, t4_t6_decode_state_s::bad_rows, t4_state_s::current_page, t4_stats_t::encoding, t4_state_s::image_length, t4_state_s::image_width, t4_stats_t::length, t4_state_s::line_encoding, t4_state_s::line_image_size, t4_stats_t::line_image_size, t4_stats_t::longest_bad_row_run, t4_t6_decode_state_s::longest_bad_row_run, t4_stats_t::pages_in_file, t4_tiff_state_t::pages_in_file, t4_stats_t::pages_transferred, t4_tiff_state_t::start_page, t4_state_s::tiff, t4_stats_t::width, t4_state_s::x_resolution, t4_stats_t::x_resolution, t4_state_s::y_resolution, and t4_stats_t::y_resolution.

Referenced by t30_get_transfer_statistics().

## ◆ t4_rx_init()

t4_rx_state_t * t4_rx_init | ( | t4_rx_state_t * | s,
|  | const char * | file,
|  | int | output_encoding )

Prepare for reception of a document.

Parameters

  s | The T.4 context.
  file | The name of the file to be received.
  output_encoding | The output encoding.

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

References t4_state_s::bytes_per_row, t4_state_s::current_page, t4_tiff_state_t::file, t4_state_s::image_buffer, t4_state_s::image_buffer_size, t4_state_s::image_width, t4_state_s::logging, t4_tiff_state_t::output_compression, t4_tiff_state_t::output_t4_options, t4_tiff_state_t::pages_in_file, t4_state_s::rx, span_log(), t4_tiff_state_t::start_page, t4_tiff_state_t::stop_page, T4_COMPRESSION_ITU_T4_1D, T4_COMPRESSION_ITU_T4_2D, T4_COMPRESSION_ITU_T6, t4_state_s::tiff, t4_state_s::x_resolution, and t4_state_s::y_resolution.

## ◆ t4_rx_put_bit()

int t4_rx_put_bit | ( | t4_rx_state_t * | s,
|  | int | bit )

Put a bit of the current document page.

Parameters

  s | The T.4 context.
  bit | The data bit.

Returns
  TRUE when the bit ends the document page, otherwise FALSE.

Referenced by t4_rx_end_page().

## ◆ t4_rx_put_byte()

int t4_rx_put_byte | ( | t4_rx_state_t * | s,
|  | uint8_t | byte )

Put a byte of the current document page.

Parameters

  s | The T.4 context.
  byte | The data byte.

Returns
  TRUE when the byte ends the document page, otherwise FALSE.

Referenced by t30_non_ecm_put_byte().

## ◆ t4_rx_put_chunk()

int t4_rx_put_chunk | ( | t4_rx_state_t * | s,
|  | const uint8_t | buf[],
|  | int | len )

Put a byte of the current document page.

Parameters

  s | The T.4 context.
  buf | The buffer containing the chunk.
  len | The length of the chunk.

Returns
  TRUE when the byte ends the document page, otherwise FALSE.

Referenced by t30_non_ecm_put_chunk().

## ◆ t4_rx_release()

int t4_rx_release | ( | t4_rx_state_t * | s | ) |

End reception of a document. Tidy up and close the file. This should be used to end T.4 reception started with t4_rx_init.

Parameters

  s | The T.4 receive context.

Returns
  0 for success, otherwise -1.

References t4_state_s::rx, t4_state_s::tiff, and t4_tiff_state_t::tiff_file.

Referenced by t4_rx_free().

## ◆ t4_rx_set_dcs()

void t4_rx_set_dcs | ( | t4_rx_state_t * | s,
|  | const char * | dcs )

Set the DCS information of the fax, for inclusion in the file.

Parameters

  s | The T.4 context.
  dcs | The DCS information, formatted as an ASCII string.

References t4_rx_metadata_t::dcs, and t4_state_s::tiff.

## ◆ t4_rx_set_far_ident()

void t4_rx_set_far_ident | ( | t4_rx_state_t * | s,
|  | const char * | ident )

Set the identity of the remote machine, for inclusion in the file.

Parameters

  s | The T.4 context.
  ident | The identity string.

References t4_rx_metadata_t::far_ident, and t4_state_s::tiff.

## ◆ t4_rx_set_image_width()

void t4_rx_set_image_width | ( | t4_rx_state_t * | s,
|  | int | width )

Set the expected width of the received image, in pixel columns.

Parameters

  s | The T.4 context.
  width | The number of pixels across the image.

References t4_state_s::image_width.

## ◆ t4_rx_set_model()

void t4_rx_set_model | ( | t4_rx_state_t * | s,
|  | const char * | model )

Set the model of the remote machine, for inclusion in the file.

Parameters

  s | The T.4 context.
  model | The model string, or NULL.

References t4_rx_metadata_t::model, and t4_state_s::tiff.

## ◆ t4_rx_set_row_write_handler()

int t4_rx_set_row_write_handler | ( | t4_rx_state_t * | s,
|  | t4_row_write_handler_t | handler,
|  | void * | user_data )

Set the row write handler for a T.4 receive context.

Parameters

  s | The T.4 receive context.
  handler | A pointer to the handler routine.
  user_data | An opaque pointer passed to the handler routine.

Returns
  0 for success, otherwise -1.

References t4_t6_decode_state_s::row_write_handler, and t4_t6_decode_state_s::row_write_user_data.

## ◆ t4_rx_set_rx_encoding()

void t4_rx_set_rx_encoding | ( | t4_rx_state_t * | s,
|  | int | encoding )

Set the encoding for the received data.

Parameters

  s | The T.4 context.
  encoding | The encoding.

References t4_state_s::line_encoding.

## ◆ t4_rx_set_sub_address()

void t4_rx_set_sub_address | ( | t4_rx_state_t * | s,
|  | const char * | sub_address )

Set the sub-address of the fax, for inclusion in the file.

Parameters

  s | The T.4 context.
  sub_address | The sub-address string.

References t4_rx_metadata_t::sub_address, and t4_state_s::tiff.

## ◆ t4_rx_set_vendor()

void t4_rx_set_vendor | ( | t4_rx_state_t * | s,
|  | const char * | vendor )

Set the vendor of the remote machine, for inclusion in the file.

Parameters

  s | The T.4 context.
  vendor | The vendor string, or NULL.

References t4_state_s::tiff, and t4_rx_metadata_t::vendor.

## ◆ t4_rx_set_x_resolution()

void t4_rx_set_x_resolution | ( | t4_rx_state_t * | s,
|  | int | resolution )

Set the column-to-column (x) resolution to expect for a received image.

Parameters

  s | The T.4 context.
  resolution | The resolution, in pixels per metre.

References t4_state_s::x_resolution.

## ◆ t4_rx_set_y_resolution()

void t4_rx_set_y_resolution | ( | t4_rx_state_t * | s,
|  | int | resolution )

Set the row-to-row (y) resolution to expect for a received image.

Parameters

  s | The T.4 context.
  resolution | The resolution, in pixels per metre.

References t4_state_s::y_resolution.

## ◆ t4_rx_start_page()

int t4_rx_start_page | ( | t4_rx_state_t * | s | ) |

Prepare to receive the next page of the current document.

Parameters

  s | The T.4 context.

Returns
  zero for success, -1 for failure.

References t4_t6_decode_state_s::a0, t4_t6_decode_state_s::a_cursor, t4_t6_decode_state_s::b1, t4_t6_decode_state_s::b_cursor, t4_t6_decode_state_s::bad_rows, t4_t6_decode_state_s::black_white, t4_state_s::bytes_per_row, t4_t6_decode_state_s::consecutive_eols, t4_state_s::cur_runs, t4_t6_decode_state_s::curr_bad_row_run, t4_state_s::image_length, t4_state_s::image_size, t4_state_s::image_width, t4_t6_decode_state_s::its_black, t4_t6_decode_state_s::last_row_starts_at, t4_state_s::line_encoding, t4_state_s::line_image_size, t4_state_s::logging, t4_t6_decode_state_s::longest_bad_row_run, t4_state_s::max_row_bits, t4_state_s::min_row_bits, t4_state_s::page_start_time, t4_state_s::ref_runs, t4_state_s::row_bits, t4_state_s::row_is_2d, t4_state_s::row_len, t4_t6_decode_state_s::run_length, t4_t6_decode_state_s::rx_bits, t4_t6_decode_state_s::rx_bitstream, t4_t6_decode_state_s::rx_skip_bits, span_log(), T4_COMPRESSION_ITU_T6, t4_state_s::tiff, t4_tiff_state_t::tiff_file, t4_state_s::tx_bits, and t4_state_s::tx_bitstream.