spandsp  1.99.0
t85.h
Go to the documentation of this file.
1 /*
2  * SpanDSP - a series of DSP components for telephony
3  *
4  * t85.h - ITU T.85 JBIG for FAX image processing
5  *
6  * Written by Steve Underwood <steveu@coppice.org>
7  *
8  * Copyright (C) 2008, 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_T85_H_)
29 #define _SPANDSP_T85_H_
30 
31 /*! \page t85_page T.85 (JBIG for FAX) image compression and decompression
32 
33 \section t85_page_sec_1 What does it do?
34 The T.85 image compression and decompression routines implement the variant of the
35 JBIG encoding method defined in ITU specification T.85. This is an image compression
36 algorithm used for black and white FAX transmission. T.85 defines a subset of the
37 full JBIG spec (T.82), which only handled a single progressively scanned bit plane.
38 This results in a great deal of simplification, and results in the ability to
39 compress or decompress progressively, while only buffering the latest 3 pixel rows
40 of the image.
41 
42 \section t85_page_sec_1 How does it work?
43 */
44 
45 /*! Bits in the option byte of the T.82 BIH which are valid for T.85 */
46 enum
47 {
48  /*! Enable typical prediction (bottom) */
49  T85_TPBON = 0x08,
50  /*! Variable length image */
51  T85_VLENGTH = 0x20,
52  /*! Lowest-resolution-layer is a two-line template */
53  T85_LRLTWO = 0x40
54 };
55 
56 /*! State of a working instance of the T.85 encoder */
58 
59 /*! State of a working instance of the T.85 decoder */
61 
62 #if defined(__cplusplus)
63 extern "C"
64 {
65 #endif
66 
67 SPAN_DECLARE(bool) t85_analyse_header(uint32_t *width, uint32_t *length, const uint8_t data[], size_t len);
68 
69 /*! \brief Check if we are at the end of the current document page.
70  \param s The T.85 context.
71  \return 0 for more data to come. SIG_STATUS_END_OF_DATA for no more data. */
73 
74 /*! \brief Get the next chunk of the current document page. The document will
75  be padded for the current minimum scan line time.
76  \param s The T.85 context.
77  \param buf The buffer into which the chunk is to written.
78  \param max_len The maximum length of the chunk.
79  \return The actual length of the chunk. If this is less than max_len it
80  indicates that the end of the document has been reached. */
81 SPAN_DECLARE(int) t85_encode_get(t85_encode_state_t *s, uint8_t buf[], size_t max_len);
82 
83 /*! \brief Set the row read handler for a T.85 encode context.
84  \param s The T.85 context.
85  \param handler A pointer to the handler routine.
86  \param user_data An opaque pointer passed to the handler routine.
87  \return 0 for success, otherwise -1. */
89  t4_row_read_handler_t handler,
90  void *user_data);
91 
92 /*! Get the logging context associated with a T.85 encode context.
93  \brief Get the logging context associated with a T.85 encode context.
94  \param s The T.85 encode context.
95  \return A pointer to the logging context */
97 
98 /*! \brief Set the T.85 options
99  \param s The T.85 context.
100  \brief l0 ???
101  \brief mx ???
102  \brief options ???. */
103 SPAN_DECLARE(void) t85_encode_set_options(t85_encode_state_t *s,
104  uint32_t l0,
105  int mx,
106  int options);
107 
108 /*! \brief Insert a comment in the encoded file.
109  \param s The T.85 context.
110  \param comment The comment. Note that this is not a C string, and may contain any bytes.
111  \param len The length of the comment. */
112 SPAN_DECLARE(void) t85_encode_comment(t85_encode_state_t *s,
113  const uint8_t comment[],
114  size_t len);
115 
116 /*! \brief Set the image width.
117  \param s The T.85 context.
118  \param image_width The width of the image.
119  \return 0 for success, otherwise -1. */
120 SPAN_DECLARE(int) t85_encode_set_image_width(t85_encode_state_t *s, uint32_t image_width);
121 
122 /*! \brief Alter the length of a T.85 encoded image. The new length cannot be greater than the
123  originally specified length. If the new length is less than the current length it
124  will be silently adjusted to the current length. Therefore, adjust the length to 1
125  will make the currently encoded length the final length.
126  \param s The T.85 context.
127  \param image_length The new image length, in pixels.
128  \return 0 if OK, or -1 if the request was not valid. */
129 SPAN_DECLARE(int) t85_encode_set_image_length(t85_encode_state_t *s, uint32_t image_length);
130 
131 /*! \brief Get the width of the image.
132  \param s The T.85 context.
133  \return The width of the image, in pixels. */
134 SPAN_DECLARE(uint32_t) t85_encode_get_image_width(t85_encode_state_t *s);
135 
136 /*! \brief Get the length of the image.
137  \param s The T.85 context.
138  \return The length of the image, in pixels. */
139 SPAN_DECLARE(uint32_t) t85_encode_get_image_length(t85_encode_state_t *s);
140 
141 /*! \brief Get the size of the compressed image, in bits.
142  \param s The T.85 context.
143  \return The size of the compressed image, in bits. */
145 
146 /*! \brief Stop image encoding prematurely.
147  \param s The T.85 context. */
148 SPAN_DECLARE(void) t85_encode_abort(t85_encode_state_t *s);
149 
150 /*! \brief Restart a T.85 encode context.
151  \param s The T.85 context.
152  \param image_width The image width, in pixels.
153  \param image_length The image length, in pixels.
154  \return 0 for success, otherwise -1. */
155 SPAN_DECLARE(int) t85_encode_restart(t85_encode_state_t *s,
156  uint32_t image_width,
157  uint32_t image_length);
158 
159 /*! \brief Prepare to encode an image in T.85 format.
160  \param s The T.85 context.
161  \param image_width The image width, in pixels.
162  \param image_length The image length, in pixels.
163  \param handler A callback routine to handle encoded image rows.
164  \param user_data An opaque pointer passed to handler.
165  \return A pointer to the context, or NULL if there was a problem. */
167  uint32_t image_width,
168  uint32_t image_length,
169  t4_row_read_handler_t handler,
170  void *user_data);
171 
172 /*! \brief Release a T.85 encode context.
173  \param s The T.85 encode context.
174  \return 0 for OK, else -1. */
175 SPAN_DECLARE(int) t85_encode_release(t85_encode_state_t *s);
176 
177 /*! \brief Free a T.85 encode context.
178  \param s The T.85 encode context.
179  \return 0 for OK, else -1. */
180 SPAN_DECLARE(int) t85_encode_free(t85_encode_state_t *s);
181 
182 /*! Get the logging context associated with a T.85 decode context.
183  \brief Get the logging context associated with a T.85 decode context.
184  \param s The T.85 decode context.
185  \return A pointer to the logging context */
187 
188 /*! \brief Get the width of the image.
189  \param s The T.85 context.
190  \return The width of the image, in pixels. */
191 SPAN_DECLARE(uint32_t) t85_decode_get_image_width(t85_decode_state_t *s);
192 
193 /*! \brief Get the length of the image.
194  \param s The T.85 context.
195  \return The length of the image, in pixels. */
196 SPAN_DECLARE(uint32_t) t85_decode_get_image_length(t85_decode_state_t *s);
197 
198 /*! \brief Get the size of the compressed image, in bits.
199  \param s The T.85 context.
200  \return The size of the compressed image, in bits. */
202 
203 SPAN_DECLARE(int) t85_decode_new_plane(t85_decode_state_t *s);
204 
205 /*! \brief Set the row handler routine.
206  \param s The T.85 context.
207  \param handler A callback routine to handle decoded image rows.
208  \param user_data An opaque pointer passed to handler.
209  \return 0 for OK. */
211  t4_row_write_handler_t handler,
212  void *user_data);
213 
214 /*! \brief Set the comment handler routine.
215  \param s The T.85 context.
216  \param max_comment_len The maximum length of comment to be passed to the handler.
217  \param handler A callback routine to handle decoded comment.
218  \param user_data An opaque pointer passed to handler.
219  \return 0 for OK. */
221  uint32_t max_comment_len,
222  t4_row_write_handler_t handler,
223  void *user_data);
224 
225 /*! A maliciously constructed T.85 image could consume too much memory, and constitute
226  a denial of service attack on the system. This function allows constraints to be
227  applied.
228  \brief Set constraints on the received image size.
229  \param s The T.85 context.
230  \param max_xd The maximum permitted width of the full image, in pixels
231  \param max_yd The maximum permitted height of the full image, in pixels
232  \return 0 for OK */
234  uint32_t max_xd,
235  uint32_t max_yd);
236 
237 /*! After the final BIE byte has been delivered to t85_decode_put_xx(), it may still
238  return T85_MORE_DATA when the T85_VLENGTH option was used, and no NEWLEN
239  marker section has appeared yet. This is because such a BIE is not
240  self-terminating (i.e. there could still be a NEWLEN followed by an SDNORM
241  or SDRST at the very end of the final stripe, which needs to be processed
242  before the final row is output. See ITU-T Recommendation T.85, Appendix I).
243  Therefore, after the last byte has been delivered, call this routine to
244  signal the end of the BIE. This is necessary to allow the routine to finish
245  processing BIEs with option T85_VLENGTH that do not actually contain any
246  NEWLEN marker section.
247  \brief Inform the T.85 decode engine of a status change in the signal source (end
248  of tx, rx signal change, etc.).
249  \param s The T.85 context.
250  \param status The type of status change which occured. */
251 SPAN_DECLARE(void) t85_decode_rx_status(t85_decode_state_t *s, int status);
252 
253 /*! \brief Decode a chunk of T.85 data.
254  \param s The T.85 context.
255  \param data The data to be decoded.
256  \param len The length of the data to be decoded.
257  \return 0 for OK. */
258 SPAN_DECLARE(int) t85_decode_put(t85_decode_state_t *s, const uint8_t data[], size_t len);
259 
260 SPAN_DECLARE(int) t85_decode_restart(t85_decode_state_t *s);
261 
262 /*! \brief Prepare to decode an image in T.85 format.
263  \param s The T.85 context.
264  \param handler A callback routine to handle decoded image rows.
265  \param user_data An opaque pointer passed to handler.
266  \return A pointer to the context, or NULL if there was a problem. */
268  t4_row_write_handler_t handler,
269  void *user_data);
270 
271 /*! \brief Release a T.85 decode context.
272  \param s The T.85 decode context.
273  \return 0 for OK, else -1. */
274 SPAN_DECLARE(int) t85_decode_release(t85_decode_state_t *s);
275 
276 /*! \brief Free a T.85 decode context.
277  \param s The T.85 decode context.
278  \return 0 for OK, else -1. */
279 SPAN_DECLARE(int) t85_decode_free(t85_decode_state_t *s);
280 
281 #if defined(__cplusplus)
282 }
283 #endif
284 
285 #endif
286 /*- End of file ------------------------------------------------------------*/
int t85_decode_release(t85_decode_state_t *s)
Release a T.85 decode context.
Definition: t85_decode.c:925
int t85_encode_set_image_width(t85_encode_state_t *s, uint32_t image_width)
Set the image width.
Definition: t85_encode.c:515
int t85_decode_set_row_write_handler(t85_decode_state_t *s, t4_row_write_handler_t handler, void *user_data)
Set the row handler routine.
Definition: t85_decode.c:760
int t85_encode_release(t85_encode_state_t *s)
Release a T.85 encode context.
Definition: t85_encode.c:727
int t85_encode_image_complete(t85_encode_state_t *s)
Check if we are at the end of the current document page.
Definition: t85_encode.c:590
void t85_encode_comment(t85_encode_state_t *s, const uint8_t comment[], size_t len)
Insert a comment in the encoded file.
Definition: t85_encode.c:583
uint32_t t85_encode_get_image_width(t85_encode_state_t *s)
Get the width of the image.
Definition: t85_encode.c:620
int t85_decode_free(t85_decode_state_t *s)
Free a T.85 decode context.
Definition: t85_decode.c:941
void t85_encode_abort(t85_encode_state_t *s)
Stop image encoding prematurely.
Definition: t85_encode.c:574
int mx
Definition: private/t85.h:147
int t85_decode_get_compressed_image_size(t85_decode_state_t *s)
Get the size of the compressed image, in bits.
Definition: t85_decode.c:804
int t85_decode_set_image_size_constraints(t85_decode_state_t *s, uint32_t max_xd, uint32_t max_yd)
Set constraints on the received image size.
Definition: t85_decode.c:782
void t85_encode_set_options(t85_encode_state_t *s, uint32_t l0, int mx, int options)
Set the T.85 options.
Definition: t85_encode.c:216
Definition: t85.h:53
Definition: t85.h:49
t85_encode_state_t * t85_encode_init(t85_encode_state_t *s, uint32_t image_width, uint32_t image_length, t4_row_read_handler_t handler, void *user_data)
Prepare to encode an image in T.85 format.
Definition: t85_encode.c:690
t81_t82_arith_decode_state_t s
Definition: private/t85.h:202
uint32_t t85_encode_get_image_length(t85_encode_state_t *s)
Get the length of the image.
Definition: t85_encode.c:626
uint32_t max_yd
Definition: private/t85.h:134
uint32_t l0
Definition: private/t85.h:145
int t85_encode_set_row_read_handler(t85_encode_state_t *s, t4_row_read_handler_t handler, void *user_data)
Set the row read handler for a T.85 encode context.
Definition: t85_encode.c:638
t85_decode_state_t * t85_decode_init(t85_decode_state_t *s, t4_row_write_handler_t handler, void *user_data)
Prepare to decode an image in T.85 format.
Definition: t85_decode.c:897
int t85_encode_get(t85_encode_state_t *s, uint8_t buf[], size_t max_len)
Get the next chunk of the current document page. The document will be padded for the current minimum ...
Definition: t85_encode.c:598
uint32_t max_xd
Definition: private/t85.h:132
uint32_t t85_decode_get_image_width(t85_decode_state_t *s)
Get the width of the image.
Definition: t85_decode.c:792
logging_state_t * t85_encode_get_logging_state(t85_encode_state_t *s)
Get the logging context associated with a T.85 encode context.
Definition: t85_encode.c:648
void t85_decode_rx_status(t85_decode_state_t *s, int status)
Inform the T.85 decode engine of a status change in the signal source (end of tx, rx signal change...
Definition: t85_decode.c:414
int t85_encode_restart(t85_encode_state_t *s, uint32_t image_width, uint32_t image_length)
Restart a T.85 encode context.
Definition: t85_encode.c:654
uint8_t * comment
Definition: private/t85.h:174
int t85_encode_set_image_length(t85_encode_state_t *s, uint32_t image_length)
Alter the length of a T.85 encoded image. The new length cannot be greater than the originally specif...
Definition: t85_encode.c:538
Definition: private/logging.h:33
Definition: private/t85.h:116
logging_state_t * t85_decode_get_logging_state(t85_decode_state_t *s)
Get the logging context associated with a T.85 decode context.
Definition: t85_decode.c:856
Definition: t85.h:51
int t85_encode_get_compressed_image_size(t85_encode_state_t *s)
Get the size of the compressed image, in bits.
Definition: t85_encode.c:632
Definition: private/t85.h:51
uint32_t max_comment_len
Definition: private/t85.h:127
uint32_t t85_decode_get_image_length(t85_decode_state_t *s)
Get the length of the image.
Definition: t85_decode.c:798
int t85_decode_put(t85_decode_state_t *s, const uint8_t data[], size_t len)
Decode a chunk of T.85 data.
Definition: t85_decode.c:437
int t85_decode_set_comment_handler(t85_decode_state_t *s, uint32_t max_comment_len, t4_row_write_handler_t handler, void *user_data)
Set the comment handler routine.
Definition: t85_decode.c:770
int(* t4_row_write_handler_t)(void *user_data, const uint8_t buf[], size_t len)
Definition: t4_rx.h:46
int(* t4_row_read_handler_t)(void *user_data, uint8_t buf[], size_t len)
Definition: t4_tx.h:34
int options
Definition: private/t85.h:149
int t85_encode_free(t85_encode_state_t *s)
Free a T.85 encode context.
Definition: t85_encode.c:744