spandsp 3.0.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?
34The T.85 image compression and decompression routines implement the variant of the
35JBIG encoding method defined in ITU specification T.85. This is an image compression
36algorithm used for black and white FAX transmission. T.85 defines a subset of the
37full JBIG spec (T.82), which only handled a single progressively scanned bit plane.
38This results in a great deal of simplification, and results in the ability to
39compress or decompress progressively, while only buffering the latest 3 pixel rows
40of 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 */
46enum
47{
48 /*! Enable typical prediction (bottom) */
49 T85_TPBON = 0x08,
50 /*! Variable length image */
52 /*! Lowest-resolution-layer is a two-line template */
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)
63extern "C"
64{
65#endif
66
67SPAN_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. */
81SPAN_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. */
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 ???. */
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. */
112SPAN_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. */
120SPAN_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. */
129SPAN_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. */
134SPAN_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. */
139SPAN_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. */
148SPAN_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. */
155SPAN_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. */
175SPAN_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. */
180SPAN_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. */
191SPAN_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. */
196SPAN_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
203SPAN_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. */
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,
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. */
251SPAN_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. */
258SPAN_DECLARE(int) t85_decode_put(t85_decode_state_t *s, const uint8_t data[], size_t len);
259
260SPAN_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. */
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. */
274SPAN_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. */
279SPAN_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 ------------------------------------------------------------*/
struct logging_state_s logging_state_t
Definition logging.h:72
Definition private/t85.h:117
uint8_t * comment
Definition private/t85.h:174
uint32_t max_yd
Definition private/t85.h:134
t81_t82_arith_decode_state_t s
Definition private/t85.h:202
uint32_t max_comment_len
Definition private/t85.h:127
uint32_t max_xd
Definition private/t85.h:132
int options
Definition private/t85.h:149
int mx
Definition private/t85.h:147
uint32_t l0
Definition private/t85.h:145
Definition private/t85.h:52
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
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:898
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:696
int t85_decode_release(t85_decode_state_t *s)
Release a T.85 decode context.
Definition t85_decode.c:970
int t85_decode_free(t85_decode_state_t *s)
Free a T.85 decode context.
Definition t85_decode.c:988
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:810
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:739
uint32_t t85_encode_get_image_length(t85_encode_state_t *s)
Get the length of the image.
Definition t85_encode.c:674
int t85_encode_set_image_width(t85_encode_state_t *s, uint32_t image_width)
Set the image width.
Definition t85_encode.c:549
int t85_encode_free(t85_encode_state_t *s)
Free a T.85 encode context.
Definition t85_encode.c:797
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:406
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:633
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:686
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:429
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:642
void t85_encode_abort(t85_encode_state_t *s)
Stop image encoding prematurely.
Definition t85_encode.c:617
@ T85_TPBON
Definition t85.h:49
@ T85_LRLTWO
Definition t85.h:53
@ T85_VLENGTH
Definition t85.h:51
uint32_t t85_decode_get_image_length(t85_decode_state_t *s)
Get the length of the image.
Definition t85_decode.c:838
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:800
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:680
struct t85_decode_state_s t85_decode_state_t
Definition t85.h:60
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:844
uint32_t t85_encode_get_image_width(t85_encode_state_t *s)
Get the width of the image.
Definition t85_encode.c:668
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:626
struct t85_encode_state_s t85_encode_state_t
Definition t85.h:57
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:702
int t85_encode_release(t85_encode_state_t *s)
Release a T.85 encode context.
Definition t85_encode.c:778
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:211
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:940
uint32_t t85_decode_get_image_width(t85_decode_state_t *s)
Get the width of the image.
Definition t85_decode.c:832
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:575
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:822