Mercurial > hg > audiostuff
comparison spandsp-0.0.3/spandsp-0.0.3/src/spandsp/t4.h @ 5:f762bf195c4b
import spandsp-0.0.3
author | Peter Meerwald <pmeerw@cosy.sbg.ac.at> |
---|---|
date | Fri, 25 Jun 2010 16:00:21 +0200 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
4:26cd8f1ef0b1 | 5:f762bf195c4b |
---|---|
1 /* | |
2 * SpanDSP - a series of DSP components for telephony | |
3 * | |
4 * t4.h - definitions for T.4 fax 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 General Public License version 2, as | |
14 * 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 General Public License for more details. | |
20 * | |
21 * You should have received a copy of the GNU General Public License | |
22 * 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.h,v 1.29 2006/10/24 13:45:28 steveu Exp $ | |
26 */ | |
27 | |
28 /*! \file */ | |
29 | |
30 #if !defined(_T4_H_) | |
31 #define _T4_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 #define T4_COMPRESSION_ITU_T4_1D 1 | |
45 #define T4_COMPRESSION_ITU_T4_2D 2 | |
46 #define T4_COMPRESSION_ITU_T6 3 | |
47 | |
48 #define T4_X_RESOLUTION_R4 4019 | |
49 #define T4_X_RESOLUTION_R8 8037 | |
50 #define T4_X_RESOLUTION_R16 16074 | |
51 | |
52 #define T4_Y_RESOLUTION_STANDARD 3850 | |
53 #define T4_Y_RESOLUTION_FINE 7700 | |
54 #define T4_Y_RESOLUTION_SUPERFINE 15400 | |
55 | |
56 /*! | |
57 T.4 FAX compression/decompression descriptor. This defines the working state | |
58 for a single instance of a T.4 FAX compression or decompression channel. | |
59 */ | |
60 typedef struct | |
61 { | |
62 /* "Background" information about the FAX, which can be stored in a TIFF file. */ | |
63 /*! \brief The vendor of the machine which produced the TIFF file. */ | |
64 const char *vendor; | |
65 /*! \brief The model of machine which produced the TIFF file. */ | |
66 const char *model; | |
67 /*! \brief The local ident string. */ | |
68 const char *local_ident; | |
69 /*! \brief The remote end's ident string. */ | |
70 const char *far_ident; | |
71 /*! \brief The FAX sub-address. */ | |
72 const char *sub_address; | |
73 /*! \brief The text which will be used in FAX page header. No text results | |
74 in no header line. */ | |
75 const char *header_info; | |
76 | |
77 /*! \brief The type of compression used between the FAX machines. */ | |
78 int line_encoding; | |
79 /*! \brief The minimum number of bits per scan row. This is a timing thing | |
80 for hardware FAX machines. */ | |
81 int min_scan_line_bits; | |
82 | |
83 int output_compression; | |
84 int output_t4_options; | |
85 | |
86 time_t page_start_time; | |
87 | |
88 int bytes_per_row; | |
89 int image_size; | |
90 int image_buffer_size; | |
91 uint8_t *image_buffer; | |
92 | |
93 TIFF *tiff_file; | |
94 const char *file; | |
95 int start_page; | |
96 int stop_page; | |
97 | |
98 int pages_transferred; | |
99 /*! Column-to-column (X) resolution in pixels per metre. */ | |
100 int x_resolution; | |
101 /*! Row-to-row (Y) resolution in pixels per metre. */ | |
102 int y_resolution; | |
103 /*! Width of the current page, in pixels. */ | |
104 int image_width; | |
105 /*! Current pixel row number. */ | |
106 int row; | |
107 /*! Total pixel rows in the current page. */ | |
108 int image_length; | |
109 /*! The current number of consecutive bad rows. */ | |
110 int curr_bad_row_run; | |
111 /*! The longest run of consecutive bad rows seen in the current page. */ | |
112 int longest_bad_row_run; | |
113 /*! The total number of bad rows in the current page. */ | |
114 int bad_rows; | |
115 | |
116 /* Decode state */ | |
117 uint32_t bits_to_date; | |
118 int bits; | |
119 | |
120 /*! \brief This variable is set if we are treating the current row as a 2D encoded | |
121 one. */ | |
122 int row_is_2d; | |
123 int its_black; | |
124 int row_len; | |
125 /*! \brief This variable is used to record the fact we have seen at least one EOL | |
126 since we started decoding. We will not try to interpret the received | |
127 data as an image until we have seen the first EOL. */ | |
128 int first_eol_seen; | |
129 /*! \brief This variable is used to count the consecutive EOLS we have seen. If it | |
130 reaches six, this is the end of the image. */ | |
131 int consecutive_eols; | |
132 | |
133 /*! \brief B&W runs for reference line */ | |
134 uint32_t *ref_runs; | |
135 /*! \brief B&W runs for current line */ | |
136 uint32_t *cur_runs; | |
137 | |
138 uint32_t *pa; | |
139 uint32_t *pb; | |
140 int a0; | |
141 int b1; | |
142 /*! \brief The length of the current run of black or white. */ | |
143 int run_length; | |
144 int black_white; | |
145 | |
146 uint32_t data; | |
147 int bit; | |
148 | |
149 /*! \brief A point into the image buffer indicating where the last row begins */ | |
150 int last_row_starts_at; | |
151 /*! \brief A point into the image buffer indicating where the current row begins */ | |
152 int row_starts_at; | |
153 | |
154 /* Encode state */ | |
155 | |
156 /*! Pointer to the buffer for the current pixel row. */ | |
157 uint8_t *row_buf; | |
158 | |
159 int bit_pos; | |
160 int bit_ptr; | |
161 | |
162 /*! \brief The reference pixel row for 2D encoding. */ | |
163 uint8_t *ref_row_buf; | |
164 /*! \brief The maximum contiguous rows that will be 2D encoded. */ | |
165 int max_rows_to_next_1d_row; | |
166 /*! \brief Number of rows left that can be 2D encoded, before a 1D encoded row | |
167 must be used. */ | |
168 int rows_to_next_1d_row; | |
169 /*! \brief The minimum number of encoded bits per row. */ | |
170 int min_row_bits; | |
171 /*! \brief The current number of bits in the current encoded row. */ | |
172 int row_bits; | |
173 | |
174 /*! \brief Error and flow logging control */ | |
175 logging_state_t logging; | |
176 } t4_state_t; | |
177 | |
178 /*! | |
179 T.4 FAX compression/decompression statistics. | |
180 */ | |
181 typedef struct | |
182 { | |
183 /*! \brief The number of pages transferred so far. */ | |
184 int pages_transferred; | |
185 /*! \brief The number of horizontal pixels in the most recent page. */ | |
186 int width; | |
187 /*! \brief The number of vertical pixels in the most recent page. */ | |
188 int length; | |
189 /*! \brief The number of bad pixel rows in the most recent page. */ | |
190 int bad_rows; | |
191 /*! \brief The largest number of bad pixel rows in a block in the most recent page. */ | |
192 int longest_bad_row_run; | |
193 /*! \brief The horizontal resolution of the page in pixels per metre */ | |
194 int x_resolution; | |
195 /*! \brief The vertical resolution of the page in pixels per metre */ | |
196 int y_resolution; | |
197 /*! \brief The type of compression used between the FAX machines */ | |
198 int encoding; | |
199 /*! \brief The size of the image, in bytes */ | |
200 int image_size; | |
201 } t4_stats_t; | |
202 | |
203 #ifdef __cplusplus | |
204 extern "C" { | |
205 #endif | |
206 | |
207 /*! \brief Allocate a T.4 transmit handling context, and | |
208 initialise it. | |
209 \param file The name of the file to be received. | |
210 \param output_encoding The output encoding. | |
211 \return The T.4 context, or NULL. */ | |
212 t4_state_t *t4_rx_create(const char *file, int output_encoding); | |
213 | |
214 /*! \brief Prepare for reception of a document. | |
215 \param s The T.4 context. | |
216 \param file The name of the file to be received. | |
217 \param output_encoding The output encoding. | |
218 \return 0 for success, otherwise -1. */ | |
219 int t4_rx_init(t4_state_t *s, const char *file, int output_encoding); | |
220 | |
221 /*! \brief Prepare to receive the next page of the current document. | |
222 \param s The T.4 context. | |
223 \return zero for success, -1 for failure. */ | |
224 int t4_rx_start_page(t4_state_t *s); | |
225 | |
226 /*! \brief Put a bit of the current document page. | |
227 \param s The T.4 context. | |
228 \param bit The data bit. | |
229 \return TRUE when the bit ends the document page, otherwise FALSE. */ | |
230 int t4_rx_put_bit(t4_state_t *s, int bit); | |
231 | |
232 /*! \brief Complete the reception of a page. | |
233 \param s The T.4 receive context. | |
234 \return 0 for success, otherwise -1. */ | |
235 int t4_rx_end_page(t4_state_t *s); | |
236 | |
237 /*! \brief End reception of a document. Tidy up, close the file and | |
238 free the context. This should be used to end T.4 reception | |
239 started with t4_rx_create. | |
240 \param s The T.4 receive context. | |
241 \return 0 for success, otherwise -1. */ | |
242 int t4_rx_delete(t4_state_t *s); | |
243 | |
244 /*! \brief End reception of a document. Tidy up and close the file. | |
245 This should be used to end T.4 reception started with | |
246 t4_rx_init. | |
247 \param s The T.4 context. | |
248 \return 0 for success, otherwise -1. */ | |
249 int t4_rx_end(t4_state_t *s); | |
250 | |
251 /*! \brief Set the encoding for the received data. | |
252 \param s The T.4 context. | |
253 \param encoding The encoding. */ | |
254 void t4_rx_set_rx_encoding(t4_state_t *s, int encoding); | |
255 | |
256 /*! \brief Set the expected width of the received image, in pixel columns. | |
257 \param s The T.4 context. | |
258 \param columns The number of pixels across the image. */ | |
259 void t4_rx_set_image_width(t4_state_t *s, int width); | |
260 | |
261 /*! \brief Set the row-to-row (y) resolution to expect for a received image. | |
262 \param s The T.4 context. | |
263 \param resolution The resolution, in pixels per metre. */ | |
264 void t4_rx_set_y_resolution(t4_state_t *s, int resolution); | |
265 | |
266 /*! \brief Set the column-to-column (x) resolution to expect for a received image. | |
267 \param s The T.4 context. | |
268 \param resolution The resolution, in pixels per metre. */ | |
269 void t4_rx_set_x_resolution(t4_state_t *s, int resolution); | |
270 | |
271 /*! \brief Set the sub-address of the fax, for inclusion in the file. | |
272 \param s The T.4 context. | |
273 \param sub_address The sub-address string. */ | |
274 void t4_rx_set_sub_address(t4_state_t *s, const char *sub_address); | |
275 | |
276 /*! \brief Set the identity of the remote machine, for inclusion in the file. | |
277 \param s The T.4 context. | |
278 \param ident The identity string. */ | |
279 void t4_rx_set_far_ident(t4_state_t *s, const char *ident); | |
280 | |
281 /*! \brief Set the vendor of the remote machine, for inclusion in the file. | |
282 \param s The T.4 context. | |
283 \param vendor The vendor string, or NULL. */ | |
284 void t4_rx_set_vendor(t4_state_t *s, const char *vendor); | |
285 | |
286 /*! \brief Set the model of the remote machine, for inclusion in the file. | |
287 \param s The T.4 context. | |
288 \param model The model string, or NULL. */ | |
289 void t4_rx_set_model(t4_state_t *s, const char *model); | |
290 | |
291 /*! \brief Allocate a T.4 receive handling context, and | |
292 initialise it. | |
293 \param s The T.4 context. | |
294 \param file The name of the file to be sent. | |
295 \return 0 for success, otherwise -1. */ | |
296 t4_state_t *t4_tx_create(const char *file, int start_page, int stop_page); | |
297 | |
298 /*! \brief Prepare for transmission of a document. | |
299 \param s The T.4 context. | |
300 \param file The name of the file to be sent. | |
301 \param start_page The first page to send. -1 for no restriction. | |
302 \param stop_page The last page to send. -1 for no restriction. | |
303 \return The T.4 context, or NULL. */ | |
304 int t4_tx_init(t4_state_t *s, const char *file, int start_page, int stop_page); | |
305 | |
306 /*! \brief Prepare to send the next page of the current document. | |
307 \param s The T.4 context. | |
308 \return zero for success, -1 for failure. */ | |
309 int t4_tx_start_page(t4_state_t *s); | |
310 | |
311 /*! \brief Prepare the current page for a resend. | |
312 \param s The T.4 context. | |
313 \return zero for success, -1 for failure. */ | |
314 int t4_tx_restart_page(t4_state_t *s); | |
315 | |
316 /*! \brief Check for the existance of the next page. This information can | |
317 be needed before it is determined that the current page is finished with. | |
318 \param s The T.4 context. | |
319 \return zero for next page found, -1 for failure. */ | |
320 int t4_tx_more_pages(t4_state_t *s); | |
321 | |
322 /*! \brief Complete the sending of a page. | |
323 \param s The T.4 context. | |
324 \return zero for success, -1 for failure. */ | |
325 int t4_tx_end_page(t4_state_t *s); | |
326 | |
327 /*! \brief Get the next bit of the current document page. The document will | |
328 be padded for the current minimum scan line time. If the | |
329 file does not contain an RTC (return to control) code at | |
330 the end of the page, one will be added. | |
331 \param s The T.4 context. | |
332 \return The next bit (i.e. 0 or 1). For the last bit of data, bit 1 is | |
333 set (i.e. the returned value is 2 or 3). */ | |
334 int t4_tx_get_bit(t4_state_t *s); | |
335 | |
336 /*! \brief Return the next bit of the current document page, without actually | |
337 moving forward in the buffer. The document will be padded for the | |
338 current minimum scan line time. If the file does not contain an | |
339 RTC (return to control) code at the end of the page, one will be | |
340 added. | |
341 \param s The T.4 context. | |
342 \return The next bit (i.e. 0 or 1). For the last bit of data, bit 1 is | |
343 set (i.e. the returned value is 2 or 3). */ | |
344 int t4_tx_check_bit(t4_state_t *s); | |
345 | |
346 /*! \brief End the transmission of a document. Tidy up, close the file and | |
347 free the context. This should be used to end T.4 transmission | |
348 started with t4_tx_create. | |
349 \param s The T.4 context. | |
350 \return 0 for success, otherwise -1. */ | |
351 int t4_tx_delete(t4_state_t *s); | |
352 | |
353 /*! \brief End the transmission of a document. Tidy up and close the file. | |
354 This should be used to end T.4 transmission started with t4_tx_init. | |
355 \param s The T.4 context. | |
356 \return 0 for success, otherwise -1. */ | |
357 int t4_tx_end(t4_state_t *s); | |
358 | |
359 /*! \brief Set the encoding for the encoded data. | |
360 \param s The T.4 context. | |
361 \param encoding The encoding. */ | |
362 void t4_tx_set_tx_encoding(t4_state_t *s, int encoding); | |
363 | |
364 /*! \brief Set the minimum number of encoded bits per row. This allows the | |
365 makes the encoding process to be set to comply with the minimum row | |
366 time specified by a remote receiving machine. | |
367 \param s The T.4 context. | |
368 \param bits The minimum number of bits per row. */ | |
369 void t4_tx_set_min_row_bits(t4_state_t *s, int bits); | |
370 | |
371 /*! \brief Set the identity of the local machine, for inclusion in page headers. | |
372 \param s The T.4 context. | |
373 \param ident The identity string. */ | |
374 void t4_tx_set_local_ident(t4_state_t *s, const char *ident); | |
375 | |
376 /*! Set the info field, included in the header line included in each page of an encoded | |
377 FAX. This is a string of up to 50 characters. Other information (date, local ident, etc.) | |
378 are automatically included in the header. If the header info is set to NULL or a zero | |
379 length string, no header lines will be added to the encoded FAX. | |
380 \brief Set the header info. | |
381 \param s The T.4 context. | |
382 \param info A string, of up to 50 bytes, which will form the info field. */ | |
383 void t4_tx_set_header_info(t4_state_t *s, const char *info); | |
384 | |
385 /*! \brief Get the row-to-row (y) resolution of the current page. | |
386 \param s The T.4 context. | |
387 \return The resolution, in pixels per metre. */ | |
388 int t4_tx_get_y_resolution(t4_state_t *s); | |
389 | |
390 /*! \brief Get the column-to-column (x) resolution of the current page. | |
391 \param s The T.4 context. | |
392 \return The resolution, in pixels per metre. */ | |
393 int t4_tx_get_x_resolution(t4_state_t *s); | |
394 | |
395 /*! \brief Get the width of the current page, in pixel columns. | |
396 \param s The T.4 context. | |
397 \return The number of columns. */ | |
398 int t4_tx_get_image_width(t4_state_t *s); | |
399 | |
400 /*! Get the current image transfer statistics. | |
401 \brief Get the current transfer statistics. | |
402 \param s The T.4 context. | |
403 \param t A pointer to a statistics structure. */ | |
404 void t4_get_transfer_statistics(t4_state_t *s, t4_stats_t *t); | |
405 | |
406 /*! Get the short text name of an encoding format. | |
407 \brief Get the short text name of an encoding format. | |
408 \param encoding The encoding type. | |
409 \return A pointer to the string. */ | |
410 const char *t4_encoding_to_str(int encoding); | |
411 | |
412 #ifdef __cplusplus | |
413 } | |
414 #endif | |
415 | |
416 #endif | |
417 /*- End of file ------------------------------------------------------------*/ |