spandsp  3.0.0
t42.h
Go to the documentation of this file.
1 /*
2  * SpanDSP - a series of DSP components for telephony
3  *
4  * t42.h - ITU T.42 JPEG for FAX image processing
5  *
6  * Written by Steve Underwood <steveu@coppice.org>
7  *
8  * Copyright (C) 2011 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_T42_H_)
29 #define _SPANDSP_T42_H_
30 
31 /*! \page t42_page T.42 (JPEG for FAX) image compression and decompression
32 
33 \section t42_page_sec_1 What does it do?
34 
35 \section t42_page_sec_1 How does it work?
36 */
37 
38 /*! State of a working instance of the T.42 encoder */
40 
41 /*! State of a working instance of the T.42 decoder */
43 
44 typedef struct lab_params_s lab_params_t;
45 
46 #if defined(__cplusplus)
47 extern "C"
48 {
49 #endif
50 
51 /*! \brief Convert an X0, Y0, Z0 coordinate to a colour tempature */
52 SPAN_DECLARE(int) xyz_to_corrected_color_temp(float *temp, float xyz[3]);
53 
54 /*! \brief Convert a colour temperature to an X0, Y0, Z0 coordinate */
55 SPAN_DECLARE(int) colour_temp_to_xyz(float xyz[3], float temp);
56 
57 /*! \brief Convert a row of 8 bit pixels from Lab to sRGB
58  \param s The Lab parameters context.
59  \param lab The output pixels
60  \param srgb The input pixels
61  \param pixel The number of pixels in the row. */
62 SPAN_DECLARE(void) srgb_to_lab(lab_params_t *s, uint8_t lab[], const uint8_t srgb[], int pixels);
63 
64 /*! \brief Convert a row of 8 bit pixels from sRGB to Lab
65  \param s The Lab parameters context.
66  \param srgb The output pixels
67  \param lab The input pixels
68  \param pixel The number of pixels in the row. */
69 SPAN_DECLARE(void) lab_to_srgb(lab_params_t *s, uint8_t srgb[], const uint8_t lab[], int pixels);
70 
71 SPAN_DECLARE(void) set_lab_illuminant(lab_params_t *s, float new_xn, float new_yn, float new_zn);
72 
73 SPAN_DECLARE(void) set_lab_gamut(lab_params_t *s, int L_min, int L_max, int a_min, int a_max, int b_min, int b_max, int ab_are_signed);
74 
75 SPAN_DECLARE(void) set_lab_gamut2(lab_params_t *s, int L_P, int L_Q, int a_P, int a_Q, int b_P, int b_Q);
76 
77 SPAN_DECLARE(void) get_lab_gamut2(lab_params_t *s, int *L_P, int *L_Q, int *a_P, int *a_Q, int *b_P, int *b_Q);
78 
79 SPAN_DECLARE(bool) t42_analyse_header(uint32_t *width, uint32_t *length, const uint8_t data[], size_t len);
80 
81 SPAN_DECLARE(void) t42_encode_set_options(t42_encode_state_t *s, uint32_t l0, int quality, int options);
82 
83 SPAN_DECLARE(int) t42_encode_set_image_width(t42_encode_state_t *s, uint32_t image_width);
84 
85 SPAN_DECLARE(int) t42_encode_set_image_length(t42_encode_state_t *s, uint32_t length);
86 
87 SPAN_DECLARE(int) t42_encode_set_image_type(t42_encode_state_t *s, int image_type);
88 
89 SPAN_DECLARE(void) t42_encode_abort(t42_encode_state_t *s);
90 
91 SPAN_DECLARE(void) t42_encode_comment(t42_encode_state_t *s, const uint8_t comment[], size_t len);
92 
93 /*! \brief Check if we are at the end of the current document page.
94  \param s The T.42 context.
95  \return 0 for more data to come. SIG_STATUS_END_OF_DATA for no more data. */
96 SPAN_DECLARE(int) t42_encode_image_complete(t42_encode_state_t *s);
97 
98 SPAN_DECLARE(int) t42_encode_get(t42_encode_state_t *s, uint8_t buf[], size_t max_len);
99 
100 SPAN_DECLARE(uint32_t) t42_encode_get_image_width(t42_encode_state_t *s);
101 
102 SPAN_DECLARE(uint32_t) t42_encode_get_image_length(t42_encode_state_t *s);
103 
104 /*! \brief Get the size of the compressed image in bits.
105  \param s The T.42 context.
106  \return The size of the image, in bits. */
108 
109 SPAN_DECLARE(int) t42_encode_set_row_read_handler(t42_encode_state_t *s, t4_row_read_handler_t handler, void *user_data);
110 
111 /*! Get the logging context associated with a T.42 encode context.
112  \brief Get the logging context associated with a T.42 encode context.
113  \param s The T.42 encode context.
114  \return A pointer to the logging context */
116 
117 /*! \brief Restart a T.42 encode context.
118  \param s The T.42 context.
119  \param image image_width The image width, in pixels.
120  \param image image_width The image length, in pixels.
121  \return 0 for success, otherwise -1. */
122 SPAN_DECLARE(int) t42_encode_restart(t42_encode_state_t *s, uint32_t image_width, uint32_t image_length);
123 
124 /*! \brief Prepare to encode an image in T.42 format.
125  \param s The T.42 context.
126  \param image_width Image width, in pixels.
127  \param image_length Image length, in pixels.
128  \param handler A callback routine to handle encoded image rows.
129  \param user_data An opaque pointer passed to handler.
130  \return A pointer to the context, or NULL if there was a problem. */
132  uint32_t image_width,
133  uint32_t image_length,
134  t4_row_read_handler_t handler,
135  void *user_data);
136 
137 /*! \brief Release a T.42 encode context.
138  \param s The T.42 encode context.
139  \return 0 for OK, else -1. */
140 SPAN_DECLARE(int) t42_encode_release(t42_encode_state_t *s);
141 
142 /*! \brief Free a T.42 encode context.
143  \param s The T.42 encode context.
144  \return 0 for OK, else -1. */
145 SPAN_DECLARE(int) t42_encode_free(t42_encode_state_t *s);
146 
147 SPAN_DECLARE(void) t42_decode_rx_status(t42_decode_state_t *s, int status);
148 
149 /*! \brief Decode a chunk of T.42 data.
150  \param s The T.42 context.
151  \param data The data to be decoded.
152  \param len The length of the data to be decoded.
153  \return 0 for OK. */
154 SPAN_DECLARE(int) t42_decode_put(t42_decode_state_t *s, const uint8_t data[], size_t len);
155 
156 /*! \brief Set the row handler routine.
157  \param s The T.42 context.
158  \param handler A callback routine to handle decoded image rows.
159  \param user_data An opaque pointer passed to handler.
160  \return 0 for OK. */
162  t4_row_write_handler_t handler,
163  void *user_data);
164 
165 /*! \brief Set the comment handler routine.
166  \param s The T.42 context.
167  \param max_comment_len The maximum length of comment to be passed to the handler.
168  \param handler A callback routine to handle decoded comment.
169  \param user_data An opaque pointer passed to handler.
170  \return 0 for OK. */
172  uint32_t max_comment_len,
173  t4_row_write_handler_t handler,
174  void *user_data);
175 
176 /*! A maliciously constructed T.42 image could consume too much memory, and constitute
177  a denial of service attack on the system. This function allows constraints to be
178  applied.
179  \brief Set constraints on the received image size.
180  \param s The T.42 context.
181  \param max_xd The maximum permitted width of the full image, in pixels
182  \param max_yd The maximum permitted height of the full image, in pixels
183  \return 0 for OK */
185  uint32_t max_xd,
186  uint32_t max_yd);
187 
188 /*! \brief Get the width of the image.
189  \param s The T.42 context.
190  \return The width of the image, in pixels. */
191 SPAN_DECLARE(uint32_t) t42_decode_get_image_width(t42_decode_state_t *s);
192 
193 /*! \brief Get the length of the image.
194  \param s The T.42 context.
195  \return The length of the image, in pixels. */
196 SPAN_DECLARE(uint32_t) t42_decode_get_image_length(t42_decode_state_t *s);
197 
198 /*! \brief Get the size of the compressed image in bits.
199  \param s The T.42 context.
200  \return The size of the image, in bits. */
202 
203 /*! Get the logging context associated with a T.42 decode context.
204  \brief Get the logging context associated with a T.42 decode context.
205  \param s The T.42 decode context.
206  \return A pointer to the logging context */
208 
209 /*! \brief Restart a T.42 decode context.
210  \param s The T.42 context. */
211 SPAN_DECLARE(int) t42_decode_restart(t42_decode_state_t *s);
212 
213 /*! \brief Prepare to decode an image in T.42 format.
214  \param s The T.42 context.
215  \param handler A callback routine to handle decoded image rows.
216  \param user_data An opaque pointer passed to handler.
217  \return A pointer to the context, or NULL if there was a problem. */
219  t4_row_write_handler_t handler,
220  void *user_data);
221 
222 /*! \brief Release a T.42 decode context.
223  \param s The T.42 decode context.
224  \return 0 for OK, else -1. */
225 SPAN_DECLARE(int) t42_decode_release(t42_decode_state_t *s);
226 
227 /*! \brief Free a T.42 decode context.
228  \param s The T.42 decode context.
229  \return 0 for OK, else -1. */
230 SPAN_DECLARE(int) t42_decode_free(t42_decode_state_t *s);
231 
232 #if defined(__cplusplus)
233 }
234 #endif
235 
236 #endif
237 /*- End of file ------------------------------------------------------------*/
Definition: private/t42.h:33
Definition: private/logging.h:34
Definition: private/t42.h:99
Definition: private/t42.h:54
int t42_encode_free(t42_encode_state_t *s)
Free a T.42 encode context.
Definition: t42.c:1058
int t42_encode_get_compressed_image_size(t42_encode_state_t *s)
Get the size of the compressed image in bits.
Definition: t42.c:955
t42_decode_state_t * t42_decode_init(t42_decode_state_t *s, t4_row_write_handler_t handler, void *user_data)
Prepare to decode an image in T.42 format.
Definition: t42.c:1375
void lab_to_srgb(lab_params_t *s, uint8_t srgb[], const uint8_t lab[], int pixels)
Convert a row of 8 bit pixels from sRGB to Lab.
Definition: t42.c:534
void srgb_to_lab(lab_params_t *s, uint8_t lab[], const uint8_t srgb[], int pixels)
Convert a row of 8 bit pixels from Lab to sRGB.
Definition: t42.c:478
int t42_decode_release(t42_decode_state_t *s)
Release a T.42 decode context.
Definition: t42.c:1400
int t42_decode_put(t42_decode_state_t *s, const uint8_t data[], size_t len)
Decode a chunk of T.42 data.
Definition: t42.c:1265
int t42_decode_set_image_size_constraints(t42_decode_state_t *s, uint32_t max_xd, uint32_t max_yd)
Set constraints on the received image size.
Definition: t42.c:1315
int t42_encode_restart(t42_encode_state_t *s, uint32_t image_width, uint32_t image_length)
Restart a T.42 encode context.
Definition: t42.c:977
logging_state_t * t42_encode_get_logging_state(t42_encode_state_t *s)
Get the logging context associated with a T.42 encode context.
Definition: t42.c:971
int t42_decode_free(t42_decode_state_t *s)
Free a T.42 decode context.
Definition: t42.c:1427
int colour_temp_to_xyz(float xyz[3], float temp)
Convert a colour temperature to an X0, Y0, Z0 coordinate.
Definition: t42.c:303
uint32_t t42_decode_get_image_length(t42_decode_state_t *s)
Get the length of the image.
Definition: t42.c:1329
int t42_decode_set_row_write_handler(t42_decode_state_t *s, t4_row_write_handler_t handler, void *user_data)
Set the row handler routine.
Definition: t42.c:1293
int t42_decode_get_compressed_image_size(t42_decode_state_t *s)
Get the size of the compressed image in bits.
Definition: t42.c:1335
int t42_decode_restart(t42_decode_state_t *s)
Restart a T.42 decode context.
Definition: t42.c:1347
int t42_encode_image_complete(t42_encode_state_t *s)
Check if we are at the end of the current document page.
Definition: t42.c:749
int xyz_to_corrected_color_temp(float *temp, float xyz[3])
Convert an X0, Y0, Z0 coordinate to a colour tempature.
Definition: t42.c:267
uint32_t t42_decode_get_image_width(t42_decode_state_t *s)
Get the width of the image.
Definition: t42.c:1323
int t42_decode_set_comment_handler(t42_decode_state_t *s, uint32_t max_comment_len, t4_row_write_handler_t handler, void *user_data)
Set the comment handler routine.
Definition: t42.c:1303
logging_state_t * t42_decode_get_logging_state(t42_decode_state_t *s)
Get the logging context associated with a T.42 decode context.
Definition: t42.c:1341
int t42_encode_release(t42_encode_state_t *s)
Release a T.42 encode context.
Definition: t42.c:1052
t42_encode_state_t * t42_encode_init(t42_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.42 format.
Definition: t42.c:1025
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