1 /* 2 * SpanDSP - a series of DSP components for telephony 3 * 4 * t4_t6_encode.h - definitions for T.4/T.6 fax encoding 5 * 6 * Written by Steve Underwood <steveu@coppice.org> 7 * 8 * Copyright (C) 2003, 2009 Steve Underwood 9 * 10 * All rights reserved. 11 * 12 * This program is free software; you can redistribute it and/or modify 13 * it under the terms of the GNU Lesser General Public License version 2.1, 14 * as published by the Free Software Foundation. 15 * 16 * This program is distributed in the hope that it will be useful, 17 * but WITHOUT ANY WARRANTY; without even the implied warranty of 18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 19 * GNU Lesser General Public License for more details. 20 * 21 * You should have received a copy of the GNU Lesser General Public 22 * License along with this program; if not, write to the Free Software 23 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 24 */ 25 26 /*! \file */ 27 28 #if !defined(_SPANDSP_T4_T6_ENCODE_H_) 29 #define _SPANDSP_T4_T6_ENCODE_H_ 30 31 typedef struct t4_t6_encode_state_s t4_t6_encode_state_t; 32 33 #if defined(__cplusplus) 34 extern "C" { 35 #endif 36 37 /*! \brief Return the next bit of the current document page, without actually 38 moving forward in the buffer. The document will be padded for the 39 current minimum scan line time. 40 \param s The T.4/T.6 context. 41 \return 0 for more data to come. SIG_STATUS_END_OF_DATA for no more data. */ 42 SPAN_DECLARE(int) t4_t6_encode_image_complete(t4_t6_encode_state_t *s); 43 44 /*! \brief Get the next bit of the current image. The image will 45 be padded for the current minimum scan line time. 46 \param s The T.4/T.6 context. 47 \return The next bit (i.e. 0 or 1). SIG_STATUS_END_OF_DATA for no more data. */ 48 SPAN_DECLARE(int) t4_t6_encode_get_bit(t4_t6_encode_state_t *s); 49 50 /*! \brief Get the next chunk of the current document page. The document will 51 be padded for the current minimum scan line time. 52 \param s The T.4/T.6 context. 53 \param buf The buffer into which the chunk is to written. 54 \param max_len The maximum length of the chunk. 55 \return The actual length of the chunk. If this is less than max_len it 56 indicates that the end of the document has been reached. */ 57 SPAN_DECLARE(int) t4_t6_encode_get(t4_t6_encode_state_t *s, uint8_t buf[], int max_len); 58 59 /*! \brief Set the row read handler for a T.4/T.6 encode context. 60 \param s The T.4/T.6 context. 61 \param handler A pointer to the handler routine. 62 \param user_data An opaque pointer passed to the handler routine. 63 \return 0 for success, otherwise -1. */ 64 SPAN_DECLARE(int) t4_t6_encode_set_row_read_handler(t4_t6_encode_state_t *s, 65 t4_row_read_handler_t handler, 66 void *user_data); 67 68 /*! \brief Set the encoding for the encoded data. 69 \param s The T.4/T.6 context. 70 \param encoding The encoding. 71 \return 0 for success, otherwise -1. */ 72 SPAN_DECLARE(int) t4_t6_encode_set_encoding(t4_t6_encode_state_t *s, int encoding); 73 74 /*! \brief Set the width of the image. 75 \param s The T.4/T.6 context. 76 \param image_width The image width, in pixels. 77 \return 0 for success, otherwise -1. */ 78 SPAN_DECLARE(int) t4_t6_encode_set_image_width(t4_t6_encode_state_t *s, int image_width); 79 80 /*! \brief Set the length of the image. 81 \param s The T.4/T.6 context. 82 \param image_length The image length, in pixels. 83 \return 0 for success, otherwise -1. */ 84 SPAN_DECLARE(int) t4_t6_encode_set_image_length(t4_t6_encode_state_t *s, int image_length); 85 86 /*! \brief Get the width of the image. 87 \param s The T.4/T.6 context. 88 \return The width of the image, in pixels. */ 89 SPAN_DECLARE(uint32_t) t4_t6_encode_get_image_width(t4_t6_encode_state_t *s); 90 91 /*! \brief Get the length of the image. 92 \param s The T.4/T.6 context. 93 \return The length of the image, in pixels. */ 94 SPAN_DECLARE(uint32_t) t4_t6_encode_get_image_length(t4_t6_encode_state_t *s); 95 96 /*! \brief Get the size of the compressed image, in bits. 97 \param s The T.4/T.6 context. 98 \return The size of the compressed image, in bits. */ 99 SPAN_DECLARE(int) t4_t6_encode_get_compressed_image_size(t4_t6_encode_state_t *s); 100 101 /*! \brief Set the minimum number of encoded bits per row. This allows the 102 makes the encoding process to be set to comply with the minimum row 103 time specified by a remote receiving machine. 104 \param s The T.4/T.6 context. 105 \param bits The minimum number of bits per row. */ 106 SPAN_DECLARE(void) t4_t6_encode_set_min_bits_per_row(t4_t6_encode_state_t *s, int bits); 107 108 /*! \brief Set the maximum number of 2D encoded rows between 1D encoded rows. This 109 is only valid for T.4 2D encoding. 110 \param s The T.4/T.6 context. 111 \param max The "K" parameter defined in the T.4 specification. This means the value is one 112 greater than the maximum number of 2D rows between each 1D row. */ 113 SPAN_DECLARE(void) t4_t6_encode_set_max_2d_rows_per_1d_row(t4_t6_encode_state_t *s, int max); 114 115 /*! Get the logging context associated with a T.4 or T.6 encode context. 116 \brief Get the logging context associated with a T.4 or T.6 encode context. 117 \param s The T.4/T.6 context. 118 \return A pointer to the logging context */ 119 SPAN_DECLARE(logging_state_t *) t4_t6_encode_get_logging_state(t4_t6_encode_state_t *s); 120 121 /*! \brief Restart a T.4 or T.6 encode context. 122 \param s The T.4/T.6 context. 123 \param image_width The image width, in pixels. 124 \param image_length The image length, in pixels. This can be set to -1, if the length is not known. 125 \return 0 for success, otherwise -1. */ 126 SPAN_DECLARE(int) t4_t6_encode_restart(t4_t6_encode_state_t *s, int image_width, int image_length); 127 128 /*! \brief Prepare to encode an image in T.4 or T.6 format. 129 \param s The T.4/T.6 context. 130 \param encoding The encoding mode. 131 \param image_width The image width, in pixels. 132 \param image_length The image length, in pixels. This can be set to -1, if the length is not known. 133 \param handler A callback routine to handle decoded image rows. 134 \param user_data An opaque pointer passed to handler. 135 \return A pointer to the context, or NULL if there was a problem. */ 136 SPAN_DECLARE(t4_t6_encode_state_t *) t4_t6_encode_init(t4_t6_encode_state_t *s, 137 int encoding, 138 int image_width, 139 int image_length, 140 t4_row_read_handler_t handler, 141 void *user_data); 142 143 SPAN_DECLARE(int) t4_t6_encode_release(t4_t6_encode_state_t *s); 144 145 SPAN_DECLARE(int) t4_t6_encode_free(t4_t6_encode_state_t *s); 146 147 #if defined(__cplusplus) 148 } 149 #endif 150 151 #endif 152 /*- End of file ------------------------------------------------------------*/ 153