spandsp  3.0.0
image_translate.h
Go to the documentation of this file.
1 /*
2  * SpanDSP - a series of DSP components for telephony
3  *
4  * image_translate.h - Image translation routines for reworking colour
5  * and gray scale images to be colour, gray scale or
6  * bi-level images of an appropriate size to be FAX
7  * compatible.
8  *
9  * Written by Steve Underwood <steveu@coppice.org>
10  *
11  * Copyright (C) 2009 Steve Underwood
12  *
13  * All rights reserved.
14  *
15  * This program is free software; you can redistribute it and/or modify
16  * it under the terms of the GNU Lesser General Public License version 2.1,
17  * as published by the Free Software Foundation.
18  *
19  * This program is distributed in the hope that it will be useful,
20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22  * GNU Lesser General Public License for more details.
23  *
24  * You should have received a copy of the GNU Lesser General Public
25  * License along with this program; if not, write to the Free Software
26  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
27  */
28 
29 /*! \file */
30 
31 #if !defined(_SPANDSP_IMAGE_TRANSLATE_H_)
32 #define _SPANDSP_IMAGE_TRANSLATE_H_
33 
34 /*! \page image_translate_page Image translation
35 \section image_translate_page_sec_1 What does it do?
36 
37 The image translate functions allow an image to be translated and resized between
38 various colour an monochrome formats. It also allows a colour or gray-scale image
39 to be reduced to a bi-level monochrome image. This is useful for preparing images
40 to be sent as traditional bi-level FAX pages.
41 
42 \section image_translate_page_sec_2 How does it work?
43 
44 \section image_translate_page_sec_3 How do I use it?
45 */
46 
48 
49 #if defined(__cplusplus)
50 extern "C"
51 {
52 #endif
53 
54 /*! \brief Get the next row of a translated image.
55  \param s The image translation context.
56  \return the length of the row buffer, in bytes */
57 SPAN_DECLARE(int) image_translate_row(image_translate_state_t *s, uint8_t buf[], size_t len);
58 
59 /*! \brief Get the width of the image being produced by an image translation context.
60  \param s The image translation context.
61  \return The width of the output image, in pixel. */
63 
64 /*! \brief Get the length of the image being produced by an image translation context.
65  \param s The image translation context.
66  \return The length of the output image, in pixel. */
68 
69 /*! \brief Set the row read callback routine for an image translation context.
70  \param s The image translation context.
71  \param row_read_handler A callback routine used to pull rows of pixels from the source image
72  into the translation process.
73  \param row_read_user_data An opaque pointer passed to read_row_handler
74  \return 0 for success, else -1. */
75 SPAN_DECLARE(int) image_translate_set_row_read_handler(image_translate_state_t *s, t4_row_read_handler_t row_read_handler, void *row_read_user_data);
76 
77 SPAN_DECLARE(int) image_translate_restart(image_translate_state_t *s, int input_length);
78 
79 /*! \brief Initialise an image translation context for rescaling and squashing a gray scale
80  or colour image to a bi-level FAX type image.
81  \param s The image translation context.
82  \param output_format The type of output image
83  \param output_width The width of the output image, in pixels. If this is set <= 0 the image
84  will not be resized.
85  \param output_length The length of the output image, in pixels. If this is set to <= 0 the
86  output length will be derived automatically from the width, to maintain the geometry
87  of the original image.
88  \param input_format The type of source image
89  \param input_width The width of the source image, in pixels.
90  \param input_length The length of the source image, in pixels.
91  \param row_read_handler A callback routine used to pull rows of pixels from the source image
92  into the translation process.
93  \param row_read_user_data An opaque pointer passed to read_row_handler
94  \return A pointer to the context, or NULL if there was a problem. */
96  int output_format,
97  int output_width,
98  int output_length,
99  int input_format,
100  int input_width,
101  int input_length,
102  t4_row_read_handler_t row_read_handler,
103  void *row_read_user_data);
104 
105 /*! \brief Release the resources associated with an image translation context.
106  \param s The image translation context.
107  \return 0 for success, otherwise -1. */
109 
110 /*! \brief Free the resources associated with an image translation context.
111  \param s The image translation context.
112  \return 0 for success, otherwise -1. */
113 SPAN_DECLARE(int) image_translate_free(image_translate_state_t *s);
114 
115 #if defined(__cplusplus)
116 }
117 #endif
118 
119 #endif
120 /*- End of file ------------------------------------------------------------*/
int image_translate_free(image_translate_state_t *s)
Free the resources associated with an image translation context.
Definition: image_translate.c:805
int image_translate_set_row_read_handler(image_translate_state_t *s, t4_row_read_handler_t row_read_handler, void *row_read_user_data)
Set the row read callback routine for an image translation context.
Definition: image_translate.c:658
Definition: private/image_translate.h:31
int image_translate_row(image_translate_state_t *s, uint8_t buf[], size_t len)
Get the next row of a translated image.
Definition: image_translate.c:612
int image_translate_get_output_length(image_translate_state_t *s)
Get the length of the image being produced by an image translation context.
Definition: image_translate.c:652
image_translate_state_t * image_translate_init(image_translate_state_t *s, int output_format, int output_width, int output_length, int input_format, int input_width, int input_length, t4_row_read_handler_t row_read_handler, void *row_read_user_data)
Initialise an image translation context for rescaling and squashing a gray scale or colour image to a...
Definition: image_translate.c:746
int image_translate_release(image_translate_state_t *s)
Release the resources associated with an image translation context.
Definition: image_translate.c:784
int image_translate_get_output_width(image_translate_state_t *s)
Get the width of the image being produced by an image translation context.
Definition: image_translate.c:646
int(* t4_row_read_handler_t)(void *user_data, uint8_t buf[], size_t len)
Definition: t4_tx.h:34