istereo2
view libs/imago2/imago2.h @ 35:643f4ab609a4
added readme and license
| author | John Tsiombikas <nuclear@member.fsf.org> |
|---|---|
| date | Sat, 31 Oct 2015 05:45:35 +0200 |
| parents | |
| children |
line source
1 /*
2 libimago - a multi-format image file input/output library.
3 Copyright (C) 2010 John Tsiombikas <nuclear@member.fsf.org>
5 This program is free software: you can redistribute it and/or modify
6 it under the terms of the GNU Lesser General Public License as published
7 by the Free Software Foundation, either version 3 of the License, or
8 (at your option) any later version.
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU Lesser General Public License for more details.
15 You should have received a copy of the GNU Lesser General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
17 */
19 #ifndef IMAGO2_H_
20 #define IMAGO2_H_
22 #include <stdio.h>
24 #ifdef __cplusplus
25 #define IMG_OPTARG(arg, val) arg = val
26 #else
27 #define IMG_OPTARG(arg, val) arg
28 #endif
30 /* XXX if you change this make sure to also change pack/unpack arrays in conv.c */
31 enum img_fmt {
32 IMG_FMT_GREY8,
33 IMG_FMT_RGB24,
34 IMG_FMT_RGBA32,
35 IMG_FMT_GREYF,
36 IMG_FMT_RGBF,
37 IMG_FMT_RGBAF,
39 NUM_IMG_FMT
40 };
42 struct img_pixmap {
43 void *pixels;
44 int width, height;
45 enum img_fmt fmt;
46 int pixelsz;
47 char *name;
48 };
50 struct img_io {
51 void *uptr; /* user-data */
53 size_t (*read)(void *buf, size_t bytes, void *uptr);
54 size_t (*write)(void *buf, size_t bytes, void *uptr);
55 long (*seek)(long offs, int whence, void *uptr);
56 };
58 #ifdef __cplusplus
59 extern "C" {
60 #endif
62 /* initialize the img_pixmap structure */
63 void img_init(struct img_pixmap *img);
64 /* destroys the img_pixmap structure, freeing the pixel buffer (if available)
65 * and any other memory held by the pixmap.
66 */
67 void img_destroy(struct img_pixmap *img);
69 /* convenience function that allocates an img_pixmap struct and then initializes it.
70 * returns null if the malloc fails.
71 */
72 struct img_pixmap *img_create(void);
73 /* frees a pixmap previously allocated with img_create (free followed by img_destroy) */
74 void img_free(struct img_pixmap *img);
76 int img_set_name(struct img_pixmap *img, const char *name);
78 /* set the image pixel format */
79 int img_set_format(struct img_pixmap *img, enum img_fmt fmt);
81 /* copies one pixmap to another.
82 * equivalent to: img_set_pixels(dest, src->width, src->height, src->fmt, src->pixels)
83 */
84 int img_copy(struct img_pixmap *dest, struct img_pixmap *src);
86 /* allocates a pixel buffer of the specified dimensions and format, and copies the
87 * pixels given through the pix pointer into it.
88 * the pix pointer can be null, in which case there's no copy, just allocation.
89 *
90 * C++: fmt and pix have default parameters IMG_FMT_RGBA32 and null respectively.
91 */
92 int img_set_pixels(struct img_pixmap *img, int w, int h, IMG_OPTARG(enum img_fmt fmt, IMG_FMT_RGBA32), IMG_OPTARG(void *pix, 0));
94 /* Simplified image loading
95 * Loads the specified file, and returns a pointer to an array of pixels of the
96 * requested pixel format. The width and height of the image are returned through
97 * the xsz and ysz pointers.
98 * If the image cannot be loaded, the function returns null.
99 *
100 * C++: the format argument is optional and defaults to IMG_FMT_RGBA32
101 */
102 void *img_load_pixels(const char *fname, int *xsz, int *ysz, IMG_OPTARG(enum img_fmt fmt, IMG_FMT_RGBA32));
104 /* Simplified image saving
105 * Reads an array of pixels supplied through the pix pointer, of dimensions xsz
106 * and ysz, and pixel-format fmt, and saves it to a file.
107 * The output filetype is guessed by the filename suffix.
108 *
109 * C++: the format argument is optional and defaults to IMG_FMT_RGBA32
110 */
111 int img_save_pixels(const char *fname, void *pix, int xsz, int ysz, IMG_OPTARG(enum img_fmt fmt, IMG_FMT_RGBA32));
113 /* Frees the memory allocated by img_load_pixels */
114 void img_free_pixels(void *pix);
116 /* Loads an image file into the supplied pixmap */
117 int img_load(struct img_pixmap *img, const char *fname);
118 /* Saves the supplied pixmap to a file. The output filetype is guessed by the filename suffix */
119 int img_save(struct img_pixmap *img, const char *fname);
121 /* Reads an image from an open FILE* into the supplied pixmap */
122 int img_read_file(struct img_pixmap *img, FILE *fp);
123 /* Writes the supplied pixmap to an open FILE* */
124 int img_write_file(struct img_pixmap *img, FILE *fp);
126 /* Reads an image using user-defined file-i/o functions (see img_io_set_*) */
127 int img_read(struct img_pixmap *img, struct img_io *io);
128 /* Writes an image using user-defined file-i/o functions (see img_io_set_*) */
129 int img_write(struct img_pixmap *img, struct img_io *io);
131 /* Converts an image to the specified pixel format */
132 int img_convert(struct img_pixmap *img, enum img_fmt tofmt);
134 /* Converts an image from an integer pixel format to the corresponding floating point one */
135 int img_to_float(struct img_pixmap *img);
136 /* Converts an image from a floating point pixel format to the corresponding integer one */
137 int img_to_integer(struct img_pixmap *img);
139 /* Returns non-zero (true) if the supplied image is in a floating point pixel format */
140 int img_is_float(struct img_pixmap *img);
141 /* Returns non-zero (true) if the supplied image has an alpha channel */
142 int img_has_alpha(struct img_pixmap *img);
145 /* These functions can be used to fill an img_io struct before it's passed to
146 * one of the user-defined i/o image reading/writing functions (img_read/img_write).
147 *
148 * User-defined i/o functions:
149 *
150 * - size_t read_func(void *buffer, size_t bytes, void *user_ptr)
151 * Must try to fill the buffer with the specified number of bytes, and return
152 * the number of bytes actually read.
153 *
154 * - size_t write_func(void *buffer, size_t bytes, void *user_ptr)
155 * Must write the specified number of bytes from the supplied buffer and return
156 * the number of bytes actually written.
157 *
158 * - long seek_func(long offset, int whence, void *user_ptr)
159 * Must seek offset bytes from: the beginning of the file if whence is SEEK_SET,
160 * the current position if whence is SEEK_CUR, or the end of the file if whence is
161 * SEEK_END, and return the resulting file offset from the beginning of the file.
162 * (i.e. seek_func(0, SEEK_CUR, user_ptr); must be equivalent to an ftell).
163 *
164 * All three functions get the user-data pointer set through img_io_set_user_data
165 * as their last argument.
166 *
167 * Note: obviously you don't need to set a write function if you're only going
168 * to call img_read, or the read and seek function if you're only going to call
169 * img_write.
170 *
171 * Note: if the user-supplied write function is buffered, make sure to flush
172 * (or close the file) after img_write returns.
173 */
174 void img_io_set_user_data(struct img_io *io, void *uptr);
175 void img_io_set_read_func(struct img_io *io, size_t (*read)(void*, size_t, void*));
176 void img_io_set_write_func(struct img_io *io, size_t (*write)(void*, size_t, void*));
177 void img_io_set_seek_func(struct img_io *io, long (*seek)(long, int, void*));
180 #ifdef __cplusplus
181 }
182 #endif
185 #endif /* IMAGO_H_ */