00001 /* 00002 * SpanDSP - a series of DSP components for telephony 00003 * 00004 * t85.h - ITU T.85 JBIG for FAX image processing 00005 * 00006 * Written by Steve Underwood <steveu@coppice.org> 00007 * 00008 * Copyright (C) 2008, 2009 Steve Underwood 00009 * 00010 * All rights reserved. 00011 * 00012 * This program is free software; you can redistribute it and/or modify 00013 * it under the terms of the GNU Lesser General Public License version 2.1, 00014 * as published by the Free Software Foundation. 00015 * 00016 * This program is distributed in the hope that it will be useful, 00017 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00018 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00019 * GNU Lesser General Public License for more details. 00020 * 00021 * You should have received a copy of the GNU Lesser General Public 00022 * License along with this program; if not, write to the Free Software 00023 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 00024 */ 00025 00026 /*! \file */ 00027 00028 #if !defined(_SPANDSP_T85_H_) 00029 #define _SPANDSP_T85_H_ 00030 00031 /*! \page t85_page T.85 (JBIG for FAX) image compression and decompression 00032 00033 \section t85_page_sec_1 What does it do? 00034 The T.85 image compression and decompression routines implement the variant of the 00035 JBIG encoding method defined in ITU specification T.85. This is an image compression 00036 algorithm used for black and white FAX transmission. T.85 defines a subset of the 00037 full JBIG spec (T.82), which only handled a single progressively scanned bit plane. 00038 This results in a great deal of simplification, and results in the ability to 00039 compress or decompress progressively, while only buffering the latest 3 pixel rows 00040 of the image. 00041 00042 \section t85_page_sec_1 How does it work? 00043 */ 00044 00045 /*! Bits in the option byte of the T.82 BIH which are valid for T.85 */ 00046 enum 00047 { 00048 /*! Enable typical prediction (bottom) */ 00049 T85_TPBON = 0x08, 00050 /*! Variable length image */ 00051 T85_VLENGTH = 0x20, 00052 /*! Lowest-resolution-layer is a two-line template */ 00053 T85_LRLTWO = 0x40 00054 }; 00055 00056 /*! State of a working instance of the T.85 encoder */ 00057 typedef struct t85_encode_state_s t85_encode_state_t; 00058 00059 /*! State of a working instance of the T.85 decoder */ 00060 typedef struct t85_decode_state_s t85_decode_state_t; 00061 00062 #if defined(__cplusplus) 00063 extern "C" 00064 { 00065 #endif 00066 00067 /*! \brief Check if we are at the end of the current document page. 00068 \param s The T.85 context. 00069 \return 0 for more data to come. SIG_STATUS_END_OF_DATA for no more data. */ 00070 SPAN_DECLARE(int) t85_encode_image_complete(t85_encode_state_t *s); 00071 00072 /*! \brief Get the next chunk of the current document page. The document will 00073 be padded for the current minimum scan line time. 00074 \param s The T.85 context. 00075 \param buf The buffer into which the chunk is to written. 00076 \param max_len The maximum length of the chunk. 00077 \return The actual length of the chunk. If this is less than max_len it 00078 indicates that the end of the document has been reached. */ 00079 SPAN_DECLARE(int) t85_encode_get(t85_encode_state_t *s, uint8_t buf[], size_t max_len); 00080 00081 /*! \brief Set the row read handler for a T.85 encode context. 00082 \param s The T.85 context. 00083 \param handler A pointer to the handler routine. 00084 \param user_data An opaque pointer passed to the handler routine. 00085 \return 0 for success, otherwise -1. */ 00086 SPAN_DECLARE(int) t85_encode_set_row_read_handler(t85_encode_state_t *s, 00087 t4_row_read_handler_t handler, 00088 void *user_data); 00089 00090 /*! Get the logging context associated with a T.85 encode context. 00091 \brief Get the logging context associated with a T.85 encode context. 00092 \param s The T.85 encode context. 00093 \return A pointer to the logging context */ 00094 SPAN_DECLARE(logging_state_t *) t85_encode_get_logging_state(t85_encode_state_t *s); 00095 00096 /*! \brief Prepare to encode an image in T.85 format. 00097 \param s The T.85 context. 00098 \param image_width Image width, in pixels. 00099 \param image_length Image length, in pixels. 00100 \param handler A callback routine to handle encoded image rows. 00101 \param user_data An opaque pointer passed to handler. 00102 \return A pointer to the context, or NULL if there was a problem. */ 00103 SPAN_DECLARE(t85_encode_state_t *) t85_encode_init(t85_encode_state_t *s, 00104 uint32_t image_width, 00105 uint32_t image_length, 00106 t4_row_read_handler_t handler, 00107 void *user_data); 00108 00109 /*! \brief Restart a T.85 encode context. 00110 \param s The T.85 context. 00111 \param image width The image width, in pixels. 00112 \return 0 for success, otherwise -1. */ 00113 SPAN_DECLARE(int) t85_encode_restart(t85_encode_state_t *s, 00114 uint32_t image_width, 00115 uint32_t image_length); 00116 00117 SPAN_DECLARE(int) t85_encode_release(t85_encode_state_t *s); 00118 00119 SPAN_DECLARE(int) t85_encode_free(t85_encode_state_t *s); 00120 00121 /*! \brief Set the T.85 options 00122 \param s The T.85 context. 00123 \brief l0 ??? 00124 \brief mx ??? 00125 \brief options ???. */ 00126 SPAN_DECLARE(void) t85_encode_set_options(t85_encode_state_t *s, 00127 uint32_t l0, 00128 int mx, 00129 int options); 00130 00131 /*! \brief Insert a comment in the encoded file. 00132 \param s The T.85 context. 00133 \param comment The comment. Note that this is not a C string, and may contain any bytes. 00134 \param len The length of the comment. */ 00135 SPAN_DECLARE(void) t85_encode_comment(t85_encode_state_t *s, 00136 const uint8_t comment[], 00137 size_t len); 00138 00139 /*! \brief Set the image width. 00140 \param s The T.85 context. 00141 \param width The width of the image. 00142 \return 0 for success, otherwise -1. */ 00143 SPAN_DECLARE(int) t85_encode_set_image_width(t85_encode_state_t *s, uint32_t image_width); 00144 00145 /*! \brief Alter the length of a T.85 encoded image. The new length cannot be greater than the 00146 originally specified length. If the new length is less than the current length it 00147 will be silently adjusted to the current length. Therefore, adjust the length to 1 00148 will make the currently encoded length the final length. 00149 \param s The T.85 context. 00150 \param length The new image length, in pixels. 00151 \return 0 if OK, or -1 if the request was not valid. */ 00152 SPAN_DECLARE(int) t85_encode_set_image_length(t85_encode_state_t *s, uint32_t length); 00153 00154 /*! \brief Get the width of the image. 00155 \param s The T.85 context. 00156 \return The width of the image, in pixels. */ 00157 SPAN_DECLARE(uint32_t) t85_encode_get_image_width(t85_encode_state_t *s); 00158 00159 /*! \brief Get the length of the image. 00160 \param s The T.85 context. 00161 \return The length of the image, in pixels. */ 00162 SPAN_DECLARE(uint32_t) t85_encode_get_image_length(t85_encode_state_t *s); 00163 00164 /*! \brief Get the size of the compressed image, in bits. 00165 \param s The T.85 context. 00166 \return The size of the compressed image, in bits. */ 00167 SPAN_DECLARE(int) t85_encode_get_compressed_image_size(t85_encode_state_t *s); 00168 00169 /*! \brief Stop image encoding prematurely. 00170 \param s The T.85 context. */ 00171 SPAN_DECLARE(void) t85_encode_abort(t85_encode_state_t *s); 00172 00173 /*! Get the logging context associated with a T.85 decode context. 00174 \brief Get the logging context associated with a T.85 decode context. 00175 \param s The T.85 decode context. 00176 \return A pointer to the logging context */ 00177 SPAN_DECLARE(logging_state_t *) t85_decode_get_logging_state(t85_decode_state_t *s); 00178 00179 /*! \brief Prepare to decode an image in T.85 format. 00180 \param s The T.85 context. 00181 \param handler A callback routine to handle decoded image rows. 00182 \param user_data An opaque pointer passed to handler. 00183 \return A pointer to the context, or NULL if there was a problem. */ 00184 SPAN_DECLARE(t85_decode_state_t *) t85_decode_init(t85_decode_state_t *s, 00185 t4_row_write_handler_t handler, 00186 void *user_data); 00187 00188 SPAN_DECLARE(int) t85_decode_new_plane(t85_decode_state_t *s); 00189 00190 SPAN_DECLARE(int) t85_decode_restart(t85_decode_state_t *s); 00191 00192 SPAN_DECLARE(int) t85_decode_release(t85_decode_state_t *s); 00193 00194 SPAN_DECLARE(int) t85_decode_free(t85_decode_state_t *s); 00195 00196 /*! \brief Get the width of the image. 00197 \param s The T.85 context. 00198 \return The width of the image, in pixels. */ 00199 SPAN_DECLARE(uint32_t) t85_decode_get_image_width(t85_decode_state_t *s); 00200 00201 /*! \brief Get the length of the image. 00202 \param s The T.85 context. 00203 \return The length of the image, in pixels. */ 00204 SPAN_DECLARE(uint32_t) t85_decode_get_image_length(t85_decode_state_t *s); 00205 00206 /*! \brief Get the size of the compressed image, in bits. 00207 \param s The T.85 context. 00208 \return The size of the compressed image, in bits. */ 00209 SPAN_DECLARE(int) t85_decode_get_compressed_image_size(t85_decode_state_t *s); 00210 00211 /*! \brief Set the row handler routine. 00212 \param s The T.85 context. 00213 \param handler A callback routine to handle decoded image rows. 00214 \param user_data An opaque pointer passed to handler. 00215 \return 0 for OK. */ 00216 SPAN_DECLARE(int) t85_decode_set_row_write_handler(t85_decode_state_t *s, 00217 t4_row_write_handler_t handler, 00218 void *user_data); 00219 00220 /*! \brief Set the comment handler routine. 00221 \param s The T.85 context. 00222 \param max_comment_len The maximum length of comment to be passed to the handler. 00223 \param handler A callback routine to handle decoded comment. 00224 \param user_data An opaque pointer passed to handler. 00225 \return 0 for OK. */ 00226 SPAN_DECLARE(int) t85_decode_set_comment_handler(t85_decode_state_t *s, 00227 uint32_t max_comment_len, 00228 t4_row_write_handler_t handler, 00229 void *user_data); 00230 00231 /*! A maliciously constructed T.85 image could consume too much memory, and constitute 00232 a denial of service attack on the system. This function allows constraints to be 00233 applied. 00234 \brief Set constraints on the received image size. 00235 \param s The T.85 context. 00236 \param max_xd The maximum permitted width of the full image, in pixels 00237 \param max_yd The maximum permitted height of the full image, in pixels 00238 \return 0 for OK */ 00239 SPAN_DECLARE(int) t85_decode_set_image_size_constraints(t85_decode_state_t *s, 00240 uint32_t max_xd, 00241 uint32_t max_yd); 00242 00243 /*! After the final BIE byte has been delivered to t85_decode_put_xx(), it may still 00244 return T85_MORE_DATA when the T85_VLENGTH option was used, and no NEWLEN 00245 marker section has appeared yet. This is because such a BIE is not 00246 self-terminating (i.e. there could still be a NEWLEN followed by an SDNORM 00247 or SDRST at the very end of the final stripe, which needs to be processed 00248 before the final row is output. See ITU-T Recommendation T.85, Appendix I). 00249 Therefore, after the last byte has been delivered, call this routine to 00250 signal the end of the BIE. This is necessary to allow the routine to finish 00251 processing BIEs with option T85_VLENGTH that do not actually contain any 00252 NEWLEN marker section. 00253 \brief Inform the T.85 decode engine of a status change in the signal source (end 00254 of tx, rx signal change, etc.). 00255 \param s The T.85 context. 00256 \param status The type of status change which occured. */ 00257 SPAN_DECLARE(void) t85_decode_rx_status(t85_decode_state_t *s, int status); 00258 00259 /*! \brief Decode a chunk of T.85 data. 00260 \param s The T.85 context. 00261 \param data The data to be decoded. 00262 \param len The length of the data to be decoded. 00263 \return 0 for OK. */ 00264 SPAN_DECLARE(int) t85_decode_put(t85_decode_state_t *s, const uint8_t data[], size_t len); 00265 00266 #if defined(__cplusplus) 00267 } 00268 #endif 00269 00270 #endif 00271 /*- End of file ------------------------------------------------------------*/
1.6.1