Mercurial > hg > audiostuff
comparison spandsp-0.0.6pre17/src/spandsp/t4_rx.h @ 4:26cd8f1ef0b1
import spandsp-0.0.6pre17
author | Peter Meerwald <pmeerw@cosy.sbg.ac.at> |
---|---|
date | Fri, 25 Jun 2010 15:50:58 +0200 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
3:c6c5a16ce2f2 | 4:26cd8f1ef0b1 |
---|---|
1 /* | |
2 * SpanDSP - a series of DSP components for telephony | |
3 * | |
4 * t4_rx.h - definitions for T.4 FAX receive processing | |
5 * | |
6 * Written by Steve Underwood <steveu@coppice.org> | |
7 * | |
8 * Copyright (C) 2003 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 * $Id: t4_rx.h,v 1.3.2.3 2009/12/21 17:18:40 steveu Exp $ | |
26 */ | |
27 | |
28 /*! \file */ | |
29 | |
30 #if !defined(_SPANDSP_T4_RX_H_) | |
31 #define _SPANDSP_T4_RX_H_ | |
32 | |
33 /*! \page t4_page T.4 image compression and decompression | |
34 | |
35 \section t4_page_sec_1 What does it do? | |
36 The T.4 image compression and decompression routines implement the 1D and 2D | |
37 encoding methods defined in ITU specification T.4. They also implement the pure | |
38 2D encoding method defined in T.6. These are image compression algorithms used | |
39 for FAX transmission. | |
40 | |
41 \section t4_page_sec_1 How does it work? | |
42 */ | |
43 | |
44 typedef int (*t4_row_write_handler_t)(void *user_data, const uint8_t buf[], size_t len); | |
45 | |
46 /*! Supported compression modes. */ | |
47 typedef enum | |
48 { | |
49 /*! No compression */ | |
50 T4_COMPRESSION_NONE = 0, | |
51 /*! T.1 1D compression */ | |
52 T4_COMPRESSION_ITU_T4_1D = 1, | |
53 /*! T.4 2D compression */ | |
54 T4_COMPRESSION_ITU_T4_2D = 2, | |
55 /*! T.6 2D compression */ | |
56 T4_COMPRESSION_ITU_T6 = 3, | |
57 /*! T.85 monochrome JBIG coding */ | |
58 T4_COMPRESSION_ITU_T85 = 4, | |
59 /*! T.43 colour JBIG coding */ | |
60 T4_COMPRESSION_ITU_T43 = 5, | |
61 /*! T.45 run length colour compression */ | |
62 T4_COMPRESSION_ITU_T45 = 6, | |
63 /*! T.81 + T.30 Annex E colour JPEG coding */ | |
64 T4_COMPRESSION_ITU_T81 = 7, | |
65 /*! T.81 + T.30 Annex K colour sYCC-JPEG coding */ | |
66 T4_COMPRESSION_ITU_SYCC_T81 = 8 | |
67 } t4_image_compression_t; | |
68 | |
69 /*! Supported X resolutions, in pixels per metre. */ | |
70 typedef enum | |
71 { | |
72 T4_X_RESOLUTION_R4 = 4016, | |
73 T4_X_RESOLUTION_R8 = 8031, | |
74 T4_X_RESOLUTION_300 = 11811, | |
75 T4_X_RESOLUTION_R16 = 16063, | |
76 T4_X_RESOLUTION_600 = 23622, | |
77 T4_X_RESOLUTION_800 = 31496, | |
78 T4_X_RESOLUTION_1200 = 47244 | |
79 } t4_image_x_resolution_t; | |
80 | |
81 /*! Supported Y resolutions, in pixels per metre. */ | |
82 typedef enum | |
83 { | |
84 T4_Y_RESOLUTION_STANDARD = 3850, | |
85 T4_Y_RESOLUTION_FINE = 7700, | |
86 T4_Y_RESOLUTION_300 = 11811, | |
87 T4_Y_RESOLUTION_SUPERFINE = 15400, /* 400 is 15748 */ | |
88 T4_Y_RESOLUTION_600 = 23622, | |
89 T4_Y_RESOLUTION_800 = 31496, | |
90 T4_Y_RESOLUTION_1200 = 47244 | |
91 } t4_image_y_resolution_t; | |
92 | |
93 /*! | |
94 Exact widths in PELs for the difference resolutions, and page widths. | |
95 Note: | |
96 The A4 widths also apply to North American letter and legal. | |
97 The R4 resolution widths are not supported in recent versions of T.30 | |
98 Only images of exactly these widths are acceptable for FAX transmisson. | |
99 | |
100 R4 864 pels/215mm for ISO A4, North American Letter and Legal | |
101 R4 1024 pels/255mm for ISO B4 | |
102 R4 1216 pels/303mm for ISO A3 | |
103 R8 1728 pels/215mm for ISO A4, North American Letter and Legal | |
104 R8 2048 pels/255mm for ISO B4 | |
105 R8 2432 pels/303mm for ISO A3 | |
106 R16 3456 pels/215mm for ISO A4, North American Letter and Legal | |
107 R16 4096 pels/255mm for ISO B4 | |
108 R16 4864 pels/303mm for ISO A3 | |
109 */ | |
110 typedef enum | |
111 { | |
112 T4_WIDTH_R4_A4 = 864, | |
113 T4_WIDTH_R4_B4 = 1024, | |
114 T4_WIDTH_R4_A3 = 1216, | |
115 T4_WIDTH_R8_A4 = 1728, | |
116 T4_WIDTH_R8_B4 = 2048, | |
117 T4_WIDTH_R8_A3 = 2432, | |
118 T4_WIDTH_300_A4 = 2592, | |
119 T4_WIDTH_300_B4 = 3072, | |
120 T4_WIDTH_300_A3 = 3648, | |
121 T4_WIDTH_R16_A4 = 3456, | |
122 T4_WIDTH_R16_B4 = 4096, | |
123 T4_WIDTH_R16_A3 = 4864, | |
124 T4_WIDTH_600_A4 = 5184, | |
125 T4_WIDTH_600_B4 = 6144, | |
126 T4_WIDTH_600_A3 = 7296, | |
127 T4_WIDTH_1200_A4 = 10368, | |
128 T4_WIDTH_1200_B4 = 12288, | |
129 T4_WIDTH_1200_A3 = 14592 | |
130 } t4_image_width_t; | |
131 | |
132 /*! | |
133 Length of the various supported paper sizes, in pixels at the various Y resolutions. | |
134 Paper sizes are | |
135 A4 (215mm x 297mm) | |
136 B4 (255mm x 364mm) | |
137 A3 (303mm x 418.56mm) | |
138 North American Letter (215.9mm x 279.4mm) | |
139 North American Legal (215.9mm x 355.6mm) | |
140 Unlimited | |
141 | |
142 T.4 does not accurately define the maximum number of scan lines in a page. A wide | |
143 variety of maximum row counts are used in the real world. It is important not to | |
144 set our sending limit too high, or a receiving machine might split pages. It is | |
145 important not to set it too low, or we might clip pages. | |
146 | |
147 Values seen for standard resolution A4 pages include 1037, 1045, 1109, 1126 and 1143. | |
148 1109 seems the most-popular. At fine res 2150, 2196, 2200, 2237, 2252-2262, 2264, | |
149 2286, and 2394 are used. 2255 seems the most popular. We try to use balanced choices | |
150 here. | |
151 */ | |
152 typedef enum | |
153 { | |
154 /* A4 is 297mm long */ | |
155 T4_LENGTH_STANDARD_A4 = 1143, | |
156 T4_LENGTH_FINE_A4 = 2286, | |
157 T4_LENGTH_300_A4 = 4665, | |
158 T4_LENGTH_SUPERFINE_A4 = 4573, | |
159 T4_LENGTH_600_A4 = 6998, | |
160 T4_LENGTH_800_A4 = 9330, | |
161 T4_LENGTH_1200_A4 = 13996, | |
162 /* B4 is 364mm long */ | |
163 T4_LENGTH_STANDARD_B4 = 1401, | |
164 T4_LENGTH_FINE_B4 = 2802, | |
165 T4_LENGTH_300_B4 = 0, | |
166 T4_LENGTH_SUPERFINE_B4 = 5605, | |
167 T4_LENGTH_600_B4 = 0, | |
168 T4_LENGTH_800_B4 = 0, | |
169 T4_LENGTH_1200_B4 = 0, | |
170 /* North American letter is 279.4mm long */ | |
171 T4_LENGTH_STANDARD_US_LETTER = 1075, | |
172 T4_LENGTH_FINE_US_LETTER = 2151, | |
173 T4_LENGTH_300_US_LETTER = 0, | |
174 T4_LENGTH_SUPERFINE_US_LETTER = 4302, | |
175 T4_LENGTH_600_US_LETTER = 0, | |
176 T4_LENGTH_800_US_LETTER = 0, | |
177 T4_LENGTH_1200_US_LETTER = 0, | |
178 /* North American legal is 355.6mm long */ | |
179 T4_LENGTH_STANDARD_US_LEGAL = 1369, | |
180 T4_LENGTH_FINE_US_LEGAL = 2738, | |
181 T4_LENGTH_300_US_LEGAL = 0, | |
182 T4_LENGTH_SUPERFINE_US_LEGAL = 5476, | |
183 T4_LENGTH_600_US_LEGAL = 0, | |
184 T4_LENGTH_800_US_LEGAL = 0, | |
185 T4_LENGTH_1200_US_LEGAL = 0 | |
186 } t4_image_length_t; | |
187 | |
188 /*! | |
189 T.4 FAX compression/decompression descriptor. This defines the working state | |
190 for a single instance of a T.4 FAX compression or decompression channel. | |
191 */ | |
192 typedef struct t4_state_s t4_state_t; | |
193 | |
194 /*! | |
195 T.4 FAX compression/decompression statistics. | |
196 */ | |
197 typedef struct | |
198 { | |
199 /*! \brief The number of pages transferred so far. */ | |
200 int pages_transferred; | |
201 /*! \brief The number of pages in the file (<0 if unknown). */ | |
202 int pages_in_file; | |
203 /*! \brief The number of horizontal pixels in the most recent page. */ | |
204 int width; | |
205 /*! \brief The number of vertical pixels in the most recent page. */ | |
206 int length; | |
207 /*! \brief The number of bad pixel rows in the most recent page. */ | |
208 int bad_rows; | |
209 /*! \brief The largest number of bad pixel rows in a block in the most recent page. */ | |
210 int longest_bad_row_run; | |
211 /*! \brief The horizontal resolution of the page in pixels per metre */ | |
212 int x_resolution; | |
213 /*! \brief The vertical resolution of the page in pixels per metre */ | |
214 int y_resolution; | |
215 /*! \brief The type of compression used between the FAX machines */ | |
216 int encoding; | |
217 /*! \brief The size of the image on the line, in bytes */ | |
218 int line_image_size; | |
219 } t4_stats_t; | |
220 | |
221 #if defined(__cplusplus) | |
222 extern "C" { | |
223 #endif | |
224 | |
225 /*! \brief Prepare for reception of a document. | |
226 \param s The T.4 context. | |
227 \param file The name of the file to be received. | |
228 \param output_encoding The output encoding. | |
229 \return A pointer to the context, or NULL if there was a problem. */ | |
230 SPAN_DECLARE(t4_state_t *) t4_rx_init(t4_state_t *s, const char *file, int output_encoding); | |
231 | |
232 /*! \brief Prepare to receive the next page of the current document. | |
233 \param s The T.4 context. | |
234 \return zero for success, -1 for failure. */ | |
235 SPAN_DECLARE(int) t4_rx_start_page(t4_state_t *s); | |
236 | |
237 /*! \brief Put a bit of the current document page. | |
238 \param s The T.4 context. | |
239 \param bit The data bit. | |
240 \return TRUE when the bit ends the document page, otherwise FALSE. */ | |
241 SPAN_DECLARE(int) t4_rx_put_bit(t4_state_t *s, int bit); | |
242 | |
243 /*! \brief Put a byte of the current document page. | |
244 \param s The T.4 context. | |
245 \param byte The data byte. | |
246 \return TRUE when the byte ends the document page, otherwise FALSE. */ | |
247 SPAN_DECLARE(int) t4_rx_put_byte(t4_state_t *s, uint8_t byte); | |
248 | |
249 /*! \brief Put a byte of the current document page. | |
250 \param s The T.4 context. | |
251 \param buf The buffer containing the chunk. | |
252 \param len The length of the chunk. | |
253 \return TRUE when the byte ends the document page, otherwise FALSE. */ | |
254 SPAN_DECLARE(int) t4_rx_put_chunk(t4_state_t *s, const uint8_t buf[], int len); | |
255 | |
256 /*! \brief Complete the reception of a page. | |
257 \param s The T.4 receive context. | |
258 \return 0 for success, otherwise -1. */ | |
259 SPAN_DECLARE(int) t4_rx_end_page(t4_state_t *s); | |
260 | |
261 /*! \brief End reception of a document. Tidy up and close the file. | |
262 This should be used to end T.4 reception started with | |
263 t4_rx_init. | |
264 \param s The T.4 receive context. | |
265 \return 0 for success, otherwise -1. */ | |
266 SPAN_DECLARE(int) t4_rx_release(t4_state_t *s); | |
267 | |
268 /*! \brief End reception of a document. Tidy up, close the file and | |
269 free the context. This should be used to end T.4 reception | |
270 started with t4_rx_init. | |
271 \param s The T.4 receive context. | |
272 \return 0 for success, otherwise -1. */ | |
273 SPAN_DECLARE(int) t4_rx_free(t4_state_t *s); | |
274 | |
275 /*! \brief Set the row write handler for a T.4 receive context. | |
276 \param s The T.4 receive context. | |
277 \param handler A pointer to the handler routine. | |
278 \param user_data An opaque pointer passed to the handler routine. | |
279 \return 0 for success, otherwise -1. */ | |
280 SPAN_DECLARE(int) t4_rx_set_row_write_handler(t4_state_t *s, t4_row_write_handler_t handler, void *user_data); | |
281 | |
282 /*! \brief Set the encoding for the received data. | |
283 \param s The T.4 context. | |
284 \param encoding The encoding. */ | |
285 SPAN_DECLARE(void) t4_rx_set_rx_encoding(t4_state_t *s, int encoding); | |
286 | |
287 /*! \brief Set the expected width of the received image, in pixel columns. | |
288 \param s The T.4 context. | |
289 \param width The number of pixels across the image. */ | |
290 SPAN_DECLARE(void) t4_rx_set_image_width(t4_state_t *s, int width); | |
291 | |
292 /*! \brief Set the row-to-row (y) resolution to expect for a received image. | |
293 \param s The T.4 context. | |
294 \param resolution The resolution, in pixels per metre. */ | |
295 SPAN_DECLARE(void) t4_rx_set_y_resolution(t4_state_t *s, int resolution); | |
296 | |
297 /*! \brief Set the column-to-column (x) resolution to expect for a received image. | |
298 \param s The T.4 context. | |
299 \param resolution The resolution, in pixels per metre. */ | |
300 SPAN_DECLARE(void) t4_rx_set_x_resolution(t4_state_t *s, int resolution); | |
301 | |
302 /*! \brief Set the DCS information of the fax, for inclusion in the file. | |
303 \param s The T.4 context. | |
304 \param dcs The DCS information, formatted as an ASCII string. */ | |
305 SPAN_DECLARE(void) t4_rx_set_dcs(t4_state_t *s, const char *dcs); | |
306 | |
307 /*! \brief Set the sub-address of the fax, for inclusion in the file. | |
308 \param s The T.4 context. | |
309 \param sub_address The sub-address string. */ | |
310 SPAN_DECLARE(void) t4_rx_set_sub_address(t4_state_t *s, const char *sub_address); | |
311 | |
312 /*! \brief Set the identity of the remote machine, for inclusion in the file. | |
313 \param s The T.4 context. | |
314 \param ident The identity string. */ | |
315 SPAN_DECLARE(void) t4_rx_set_far_ident(t4_state_t *s, const char *ident); | |
316 | |
317 /*! \brief Set the vendor of the remote machine, for inclusion in the file. | |
318 \param s The T.4 context. | |
319 \param vendor The vendor string, or NULL. */ | |
320 SPAN_DECLARE(void) t4_rx_set_vendor(t4_state_t *s, const char *vendor); | |
321 | |
322 /*! \brief Set the model of the remote machine, for inclusion in the file. | |
323 \param s The T.4 context. | |
324 \param model The model string, or NULL. */ | |
325 SPAN_DECLARE(void) t4_rx_set_model(t4_state_t *s, const char *model); | |
326 | |
327 /*! Get the current image transfer statistics. | |
328 \brief Get the current transfer statistics. | |
329 \param s The T.4 context. | |
330 \param t A pointer to a statistics structure. */ | |
331 SPAN_DECLARE(void) t4_get_transfer_statistics(t4_state_t *s, t4_stats_t *t); | |
332 | |
333 /*! Get the short text name of an encoding format. | |
334 \brief Get the short text name of an encoding format. | |
335 \param encoding The encoding type. | |
336 \return A pointer to the string. */ | |
337 SPAN_DECLARE(const char *) t4_encoding_to_str(int encoding); | |
338 | |
339 #if defined(__cplusplus) | |
340 } | |
341 #endif | |
342 | |
343 #endif | |
344 /*- End of file ------------------------------------------------------------*/ |