spandsp  1.99.0
t4_t6_encode.h
Go to the documentation of this file.
1 /*
2  * SpanDSP - a series of DSP components for telephony
3  *
4  * t4_t6_encode.h - definitions for T.4/T.6 fax encoding
5  *
6  * Written by Steve Underwood <steveu@coppice.org>
7  *
8  * Copyright (C) 2003, 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_T4_T6_ENCODE_H_)
29 #define _SPANDSP_T4_T6_ENCODE_H_
30 
32 
33 #if defined(__cplusplus)
34 extern "C" {
35 #endif
36 
37 /*! \brief Return the next bit of the current document page, without actually
38  moving forward in the buffer. The document will be padded for the
39  current minimum scan line time.
40  \param s The T.4/T.6 context.
41  \return 0 for more data to come. SIG_STATUS_END_OF_DATA for no more data. */
43 
44 /*! \brief Get the next bit of the current image. The image will
45  be padded for the current minimum scan line time.
46  \param s The T.4/T.6 context.
47  \return The next bit (i.e. 0 or 1). SIG_STATUS_END_OF_DATA for no more data. */
48 SPAN_DECLARE(int) t4_t6_encode_get_bit(t4_t6_encode_state_t *s);
49 
50 /*! \brief Get the next chunk of the current document page. The document will
51  be padded for the current minimum scan line time.
52  \param s The T.4/T.6 context.
53  \param buf The buffer into which the chunk is to written.
54  \param max_len The maximum length of the chunk.
55  \return The actual length of the chunk. If this is less than max_len it
56  indicates that the end of the document has been reached. */
57 SPAN_DECLARE(int) t4_t6_encode_get(t4_t6_encode_state_t *s, uint8_t buf[], int max_len);
58 
59 /*! \brief Set the row read handler for a T.4/T.6 encode context.
60  \param s The T.4/T.6 context.
61  \param handler A pointer to the handler routine.
62  \param user_data An opaque pointer passed to the handler routine.
63  \return 0 for success, otherwise -1. */
65  t4_row_read_handler_t handler,
66  void *user_data);
67 
68 /*! \brief Set the encoding for the encoded data.
69  \param s The T.4/T.6 context.
70  \param encoding The encoding.
71  \return 0 for success, otherwise -1. */
73 
74 /*! \brief Set the width of the image.
75  \param s The T.4/T.6 context.
76  \param image_width The image width, in pixels.
77  \return 0 for success, otherwise -1. */
79 
80 /*! \brief Set the length of the image.
81  \param s The T.4/T.6 context.
82  \param image_length The image length, in pixels.
83  \return 0 for success, otherwise -1. */
85 
86 /*! \brief Get the width of the image.
87  \param s The T.4/T.6 context.
88  \return The width of the image, in pixels. */
89 SPAN_DECLARE(uint32_t) t4_t6_encode_get_image_width(t4_t6_encode_state_t *s);
90 
91 /*! \brief Get the length of the image.
92  \param s The T.4/T.6 context.
93  \return The length of the image, in pixels. */
94 SPAN_DECLARE(uint32_t) t4_t6_encode_get_image_length(t4_t6_encode_state_t *s);
95 
96 /*! \brief Get the size of the compressed image, in bits.
97  \param s The T.4/T.6 context.
98  \return The size of the compressed image, in bits. */
100 
101 /*! \brief Set the minimum number of encoded bits per row. This allows the
102  makes the encoding process to be set to comply with the minimum row
103  time specified by a remote receiving machine.
104  \param s The T.4/T.6 context.
105  \param bits The minimum number of bits per row. */
106 SPAN_DECLARE(void) t4_t6_encode_set_min_bits_per_row(t4_t6_encode_state_t *s, int bits);
107 
108 /*! \brief Set the maximum number of 2D encoded rows between 1D encoded rows. This
109  is only valid for T.4 2D encoding.
110  \param s The T.4/T.6 context.
111  \param max The "K" parameter defined in the T.4 specification. This means the value is one
112  greater than the maximum number of 2D rows between each 1D row. */
113 SPAN_DECLARE(void) t4_t6_encode_set_max_2d_rows_per_1d_row(t4_t6_encode_state_t *s, int max);
114 
115 /*! Get the logging context associated with a T.4 or T.6 encode context.
116  \brief Get the logging context associated with a T.4 or T.6 encode context.
117  \param s The T.4/T.6 context.
118  \return A pointer to the logging context */
120 
121 /*! \brief Restart a T.4 or T.6 encode context.
122  \param s The T.4/T.6 context.
123  \param image_width The image width, in pixels.
124  \param image_length The image length, in pixels. This can be set to -1, if the length is not known.
125  \return 0 for success, otherwise -1. */
126 SPAN_DECLARE(int) t4_t6_encode_restart(t4_t6_encode_state_t *s, int image_width, int image_length);
127 
128 /*! \brief Prepare to encode an image in T.4 or T.6 format.
129  \param s The T.4/T.6 context.
130  \param encoding The encoding mode.
131  \param image_width The image width, in pixels.
132  \param image_length The image length, in pixels. This can be set to -1, if the length is not known.
133  \param handler A callback routine to handle decoded image rows.
134  \param user_data An opaque pointer passed to handler.
135  \return A pointer to the context, or NULL if there was a problem. */
137  int encoding,
138  int image_width,
139  int image_length,
140  t4_row_read_handler_t handler,
141  void *user_data);
142 
143 SPAN_DECLARE(int) t4_t6_encode_release(t4_t6_encode_state_t *s);
144 
145 SPAN_DECLARE(int) t4_t6_encode_free(t4_t6_encode_state_t *s);
146 
147 #if defined(__cplusplus)
148 }
149 #endif
150 
151 #endif
152 /*- End of file ------------------------------------------------------------*/
uint32_t t4_t6_encode_get_image_width(t4_t6_encode_state_t *s)
Get the width of the image.
Definition: t4_t6_encode.c:1050
int t4_t6_encode_get(t4_t6_encode_state_t *s, uint8_t buf[], int max_len)
Get the next chunk of the current document page. The document will be padded for the current minimum ...
Definition: t4_t6_encode.c:952
int t4_t6_encode_restart(t4_t6_encode_state_t *s, int image_width, int image_length)
Restart a T.4 or T.6 encode context.
Definition: t4_t6_encode.c:1118
uint32_t t4_t6_encode_get_image_length(t4_t6_encode_state_t *s)
Get the length of the image.
Definition: t4_t6_encode.c:1056
int t4_t6_encode_get_bit(t4_t6_encode_state_t *s)
Get the next bit of the current image. The image will be padded for the current minimum scan line tim...
Definition: t4_t6_encode.c:933
void t4_t6_encode_set_min_bits_per_row(t4_t6_encode_state_t *s, int bits)
Set the minimum number of encoded bits per row. This allows the makes the encoding process to be set ...
Definition: t4_t6_encode.c:1002
int t4_t6_encode_set_image_width(t4_t6_encode_state_t *s, int image_width)
Set the width of the image.
Definition: t4_t6_encode.c:1017
int t4_t6_encode_get_compressed_image_size(t4_t6_encode_state_t *s)
Get the size of the compressed image, in bits.
Definition: t4_t6_encode.c:1062
int t4_t6_encode_set_row_read_handler(t4_t6_encode_state_t *s, t4_row_read_handler_t handler, void *user_data)
Set the row read handler for a T.4/T.6 encode context.
Definition: t4_t6_encode.c:974
int encoding
The type of compression used.
Definition: private/t4_t6_encode.h:40
int t4_t6_encode_image_complete(t4_t6_encode_state_t *s)
Return the next bit of the current document page, without actually moving forward in the buffer...
Definition: t4_t6_encode.c:922
void t4_t6_encode_set_max_2d_rows_per_1d_row(t4_t6_encode_state_t *s, int max)
Set the maximum number of 2D encoded rows between 1D encoded rows. This is only valid for T...
Definition: t4_t6_encode.c:1068
int t4_t6_encode_set_encoding(t4_t6_encode_state_t *s, int encoding)
Set the encoding for the encoded data.
Definition: t4_t6_encode.c:982
Definition: private/logging.h:33
int image_width
Width of the current page, in pixels.
Definition: private/t4_t6_encode.h:42
t4_t6_encode_state_t * t4_t6_encode_init(t4_t6_encode_state_t *s, int encoding, int image_width, int image_length, t4_row_read_handler_t handler, void *user_data)
Prepare to encode an image in T.4 or T.6 format.
Definition: t4_t6_encode.c:1146
logging_state_t * t4_t6_encode_get_logging_state(t4_t6_encode_state_t *s)
Get the logging context associated with a T.4 or T.6 encode context.
Definition: t4_t6_encode.c:1112
int t4_t6_encode_set_image_length(t4_t6_encode_state_t *s, int image_length)
Set the length of the image.
Definition: t4_t6_encode.c:1044
Definition: private/t4_t6_encode.h:32
int image_length
Length of the current page, in pixels.
Definition: private/t4_t6_encode.h:50
int(* t4_row_read_handler_t)(void *user_data, uint8_t buf[], size_t len)
Definition: t4_tx.h:34