Mercurial > hg > audiostuff
comparison spandsp-0.0.6pre17/src/spandsp/t38_non_ecm_buffer.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 * t38_non_ecm_buffer.h - A rate adapting buffer for T.38 non-ECM image | |
5 * and TCF data | |
6 * | |
7 * Written by Steve Underwood <steveu@coppice.org> | |
8 * | |
9 * Copyright (C) 2005, 2006, 2007, 2008 Steve Underwood | |
10 * | |
11 * All rights reserved. | |
12 * | |
13 * This program is free software; you can redistribute it and/or modify | |
14 * it under the terms of the GNU Lesser General Public License version 2.1, | |
15 * as published by the Free Software Foundation. | |
16 * | |
17 * This program is distributed in the hope that it will be useful, | |
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
20 * GNU Lesser General Public License for more details. | |
21 * | |
22 * You should have received a copy of the GNU Lesser General Public | |
23 * License along with this program; if not, write to the Free Software | |
24 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. | |
25 * | |
26 * $Id: t38_non_ecm_buffer.h,v 1.7.4.1 2009/12/19 06:43:28 steveu Exp $ | |
27 */ | |
28 | |
29 /*! \file */ | |
30 | |
31 #if !defined(_SPANDSP_T38_NON_ECM_BUFFER_H_) | |
32 #define _SPANDSP_T38_NON_ECM_BUFFER_H_ | |
33 | |
34 /*! \page t38_non_ecm_buffer_page T.38 rate adapting non-ECM image data buffer | |
35 \section t38_non_ecm_buffer_page_sec_1 What does it do? | |
36 | |
37 The T.38 rate adapting non-ECM image data buffer is used to buffer TCF and non-ECM | |
38 FAX image data being gatewayed from a T.38 link to an analogue FAX modem link. | |
39 | |
40 As well as rate adapting, the buffer has the ability to impose a minimum on the number | |
41 of bits per row of image data. This allows any row padding zeros to be stripped from | |
42 the data stream, to minimise the data sent as T.38 packets, and be reinserted before | |
43 the data is sent to its final destination. Not all T.38 implementations support this | |
44 feature, so it's use must be negotiated. | |
45 | |
46 \section t38_non_ecm_buffer_page_sec_2 How does it work? | |
47 | |
48 When inserting padding bits, whether to ensure a minimum row time or for flow control, | |
49 it is important the right value is inserted at the right point in the data sequence. | |
50 If we are in the optional initial period of all ones, we can insert a byte of extra | |
51 ones at any time. Once we pass that initial stage, TCF and image data need separate | |
52 handling. | |
53 | |
54 TCF data is all zeros. Once the period of all zeros has begun it is OK to insert | |
55 additional bytes of zeros at any point. | |
56 | |
57 Image data consists of rows, separated by EOL (end of line) markers. Inserting | |
58 zeros at arbitrary times would corrupt the image. However, it is OK to insert a | |
59 considerable number of extra zeros just before an EOL. Therefore we track where the | |
60 EOL markers occur as we fill the buffer. As we empty the buffer stop outputting real | |
61 data, and start outputting bytes of zero, if we reach this last EOL marker location. | |
62 The EOL marker is 11 zeros following by 1 (1D mode) or 2 (2D mode) ones. Therefore, it | |
63 always spills across 2 bytes in the buffer, and there is always a point where we can | |
64 insert our extra zeros between bytes. | |
65 | |
66 Padding between the group of successive EOL markers which for the RTC (return to control) | |
67 marker that ends an image causes some FAX machines not to recognise them as an RTC condition. | |
68 Therefore, our padding applies special protection so padding never occurs between two | |
69 successive EOL markers, with no pixel data between them. | |
70 */ | |
71 | |
72 /*! The buffer length much be a power of two. The chosen length is big enough for | |
73 over 9s of data at the V.17 14,400bps rate. */ | |
74 #define T38_NON_ECM_TX_BUF_LEN 16384 | |
75 | |
76 /*! \brief A flow controlled non-ECM image data buffer, for buffering T.38 to analogue | |
77 modem data. | |
78 */ | |
79 typedef struct t38_non_ecm_buffer_state_s t38_non_ecm_buffer_state_t; | |
80 | |
81 #if defined(__cplusplus) | |
82 extern "C" | |
83 { | |
84 #endif | |
85 | |
86 /*! \brief Initialise a T.38 rate adapting non-ECM buffer context. | |
87 \param s The buffer context. | |
88 \param mode TRUE for image data mode, or FALSE for TCF mode. | |
89 \param bits The minimum number of bits per FAX image row. | |
90 \return A pointer to the buffer context, or NULL if there was a problem. */ | |
91 SPAN_DECLARE(t38_non_ecm_buffer_state_t *) t38_non_ecm_buffer_init(t38_non_ecm_buffer_state_t *s, int mode, int min_row_bits); | |
92 | |
93 SPAN_DECLARE(int) t38_non_ecm_buffer_release(t38_non_ecm_buffer_state_t *s); | |
94 | |
95 SPAN_DECLARE(int) t38_non_ecm_buffer_free(t38_non_ecm_buffer_state_t *s); | |
96 | |
97 /*! \brief Set the mode of a T.38 rate adapting non-ECM buffer context. | |
98 \param s The buffer context. | |
99 \param mode TRUE for image data mode, or FALSE for TCF mode. | |
100 \param bits The minimum number of bits per FAX image row. */ | |
101 SPAN_DECLARE(void) t38_non_ecm_buffer_set_mode(t38_non_ecm_buffer_state_t *s, int mode, int min_row_bits); | |
102 | |
103 /*! \brief Inject data to T.38 rate adapting non-ECM buffer context. | |
104 \param s The buffer context. | |
105 \param buf The data buffer to be injected. | |
106 \param len The length of the data to be injected. */ | |
107 SPAN_DECLARE(void) t38_non_ecm_buffer_inject(t38_non_ecm_buffer_state_t *s, const uint8_t *buf, int len); | |
108 | |
109 /*! \brief Inform a T.38 rate adapting non-ECM buffer context that the incoming data has finished, | |
110 and the contents of the buffer should be played out as quickly as possible. | |
111 \param s The buffer context. */ | |
112 SPAN_DECLARE(void) t38_non_ecm_buffer_push(t38_non_ecm_buffer_state_t *s); | |
113 | |
114 /*! \brief Report the input status of a T.38 rate adapting non-ECM buffer context to the specified | |
115 logging context. | |
116 \param s The buffer context. | |
117 \param logging The logging context. */ | |
118 SPAN_DECLARE(void) t38_non_ecm_buffer_report_input_status(t38_non_ecm_buffer_state_t *s, logging_state_t *logging); | |
119 | |
120 /*! \brief Report the output status of a T.38 rate adapting non-ECM buffer context to the specified | |
121 logging context. | |
122 \param s The buffer context. | |
123 \param logging The logging context. */ | |
124 SPAN_DECLARE(void) t38_non_ecm_buffer_report_output_status(t38_non_ecm_buffer_state_t *s, logging_state_t *logging); | |
125 | |
126 /*! \brief Get the next bit of data from a T.38 rate adapting non-ECM buffer context. | |
127 \param user_data The buffer context, cast to a void pointer. | |
128 \return The next bit, or one of the values indicating a change of modem status. */ | |
129 SPAN_DECLARE_NONSTD(int) t38_non_ecm_buffer_get_bit(void *user_data); | |
130 | |
131 #if defined(__cplusplus) | |
132 } | |
133 #endif | |
134 | |
135 #endif | |
136 /*- End of file ------------------------------------------------------------*/ |