1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/libs/imago/imago2.h	Sat Feb 01 19:58:19 2014 +0200
     1.3 @@ -0,0 +1,222 @@
     1.4 +/*
     1.5 +libimago - a multi-format image file input/output library.
     1.6 +Copyright (C) 2010-2012 John Tsiombikas <nuclear@member.fsf.org>
     1.7 +
     1.8 +This program is free software: you can redistribute it and/or modify
     1.9 +it under the terms of the GNU Lesser General Public License as published
    1.10 +by the Free Software Foundation, either version 3 of the License, or
    1.11 +(at your option) any later version.
    1.12 +
    1.13 +This program is distributed in the hope that it will be useful,
    1.14 +but WITHOUT ANY WARRANTY; without even the implied warranty of
    1.15 +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    1.16 +GNU Lesser General Public License for more details.
    1.17 +
    1.18 +You should have received a copy of the GNU Lesser General Public License
    1.19 +along with this program.  If not, see <http://www.gnu.org/licenses/>.
    1.20 +*/
    1.21 +
    1.22 +#ifndef IMAGO2_H_
    1.23 +#define IMAGO2_H_
    1.24 +
    1.25 +#include <stdio.h>
    1.26 +
    1.27 +#ifdef __cplusplus
    1.28 +#define IMG_OPTARG(arg, val)	arg = val
    1.29 +#else
    1.30 +#define IMG_OPTARG(arg, val)	arg
    1.31 +#endif
    1.32 +
    1.33 +/* XXX if you change this make sure to also change pack/unpack arrays in conv.c */
    1.34 +enum img_fmt {
    1.35 +	IMG_FMT_GREY8,
    1.36 +	IMG_FMT_RGB24,
    1.37 +	IMG_FMT_RGBA32,
    1.38 +	IMG_FMT_GREYF,
    1.39 +	IMG_FMT_RGBF,
    1.40 +	IMG_FMT_RGBAF,
    1.41 +
    1.42 +	NUM_IMG_FMT
    1.43 +};
    1.44 +
    1.45 +struct img_pixmap {
    1.46 +	void *pixels;
    1.47 +	int width, height;
    1.48 +	enum img_fmt fmt;
    1.49 +	int pixelsz;
    1.50 +	char *name;
    1.51 +};
    1.52 +
    1.53 +struct img_io {
    1.54 +	void *uptr;	/* user-data */
    1.55 +
    1.56 +	size_t (*read)(void *buf, size_t bytes, void *uptr);
    1.57 +	size_t (*write)(void *buf, size_t bytes, void *uptr);
    1.58 +	long (*seek)(long offs, int whence, void *uptr);
    1.59 +};
    1.60 +
    1.61 +#ifdef __cplusplus
    1.62 +extern "C" {
    1.63 +#endif
    1.64 +
    1.65 +/* initialize the img_pixmap structure */
    1.66 +void img_init(struct img_pixmap *img);
    1.67 +/* destroys the img_pixmap structure, freeing the pixel buffer (if available)
    1.68 + * and any other memory held by the pixmap.
    1.69 + */
    1.70 +void img_destroy(struct img_pixmap *img);
    1.71 +
    1.72 +/* convenience function that allocates an img_pixmap struct and then initializes it.
    1.73 + * returns null if the malloc fails.
    1.74 + */
    1.75 +struct img_pixmap *img_create(void);
    1.76 +/* frees a pixmap previously allocated with img_create (free followed by img_destroy) */
    1.77 +void img_free(struct img_pixmap *img);
    1.78 +
    1.79 +int img_set_name(struct img_pixmap *img, const char *name);
    1.80 +
    1.81 +/* set the image pixel format */
    1.82 +int img_set_format(struct img_pixmap *img, enum img_fmt fmt);
    1.83 +
    1.84 +/* copies one pixmap to another.
    1.85 + * equivalent to: img_set_pixels(dest, src->width, src->height, src->fmt, src->pixels)
    1.86 + */
    1.87 +int img_copy(struct img_pixmap *dest, struct img_pixmap *src);
    1.88 +
    1.89 +/* allocates a pixel buffer of the specified dimensions and format, and copies the
    1.90 + * pixels given through the pix pointer into it.
    1.91 + * the pix pointer can be null, in which case there's no copy, just allocation.
    1.92 + *
    1.93 + * C++: fmt and pix have default parameters IMG_FMT_RGBA32 and null respectively.
    1.94 + */
    1.95 +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));
    1.96 +
    1.97 +/* Simplified image loading
    1.98 + * Loads the specified file, and returns a pointer to an array of pixels of the
    1.99 + * requested pixel format. The width and height of the image are returned through
   1.100 + * the xsz and ysz pointers.
   1.101 + * If the image cannot be loaded, the function returns null.
   1.102 + *
   1.103 + * C++: the format argument is optional and defaults to IMG_FMT_RGBA32
   1.104 + */
   1.105 +void *img_load_pixels(const char *fname, int *xsz, int *ysz, IMG_OPTARG(enum img_fmt fmt, IMG_FMT_RGBA32));
   1.106 +
   1.107 +/* Simplified image saving
   1.108 + * Reads an array of pixels supplied through the pix pointer, of dimensions xsz
   1.109 + * and ysz, and pixel-format fmt, and saves it to a file.
   1.110 + * The output filetype is guessed by the filename suffix.
   1.111 + *
   1.112 + * C++: the format argument is optional and defaults to IMG_FMT_RGBA32
   1.113 + */
   1.114 +int img_save_pixels(const char *fname, void *pix, int xsz, int ysz, IMG_OPTARG(enum img_fmt fmt, IMG_FMT_RGBA32));
   1.115 +
   1.116 +/* Frees the memory allocated by img_load_pixels */
   1.117 +void img_free_pixels(void *pix);
   1.118 +
   1.119 +/* Loads an image file into the supplied pixmap */
   1.120 +int img_load(struct img_pixmap *img, const char *fname);
   1.121 +/* Saves the supplied pixmap to a file. The output filetype is guessed by the filename suffix */
   1.122 +int img_save(struct img_pixmap *img, const char *fname);
   1.123 +
   1.124 +/* Reads an image from an open FILE* into the supplied pixmap */
   1.125 +int img_read_file(struct img_pixmap *img, FILE *fp);
   1.126 +/* Writes the supplied pixmap to an open FILE* */
   1.127 +int img_write_file(struct img_pixmap *img, FILE *fp);
   1.128 +
   1.129 +/* Reads an image using user-defined file-i/o functions (see img_io_set_*) */
   1.130 +int img_read(struct img_pixmap *img, struct img_io *io);
   1.131 +/* Writes an image using user-defined file-i/o functions (see img_io_set_*) */
   1.132 +int img_write(struct img_pixmap *img, struct img_io *io);
   1.133 +
   1.134 +/* Converts an image to the specified pixel format */
   1.135 +int img_convert(struct img_pixmap *img, enum img_fmt tofmt);
   1.136 +
   1.137 +/* Converts an image from an integer pixel format to the corresponding floating point one */
   1.138 +int img_to_float(struct img_pixmap *img);
   1.139 +/* Converts an image from a floating point pixel format to the corresponding integer one */
   1.140 +int img_to_integer(struct img_pixmap *img);
   1.141 +
   1.142 +/* Returns non-zero (true) if the supplied image is in a floating point pixel format */
   1.143 +int img_is_float(struct img_pixmap *img);
   1.144 +/* Returns non-zero (true) if the supplied image has an alpha channel */
   1.145 +int img_has_alpha(struct img_pixmap *img);
   1.146 +
   1.147 +
   1.148 +/* don't use these for anything performance-critical */
   1.149 +void img_setpixel(struct img_pixmap *img, int x, int y, void *pixel);
   1.150 +void img_getpixel(struct img_pixmap *img, int x, int y, void *pixel);
   1.151 +
   1.152 +void img_setpixel1i(struct img_pixmap *img, int x, int y, int pix);
   1.153 +void img_setpixel1f(struct img_pixmap *img, int x, int y, float pix);
   1.154 +void img_setpixel4i(struct img_pixmap *img, int x, int y, int r, int g, int b, int a);
   1.155 +void img_setpixel4f(struct img_pixmap *img, int x, int y, float r, float g, float b, float a);
   1.156 +
   1.157 +void img_getpixel1i(struct img_pixmap *img, int x, int y, int *pix);
   1.158 +void img_getpixel1f(struct img_pixmap *img, int x, int y, float *pix);
   1.159 +void img_getpixel4i(struct img_pixmap *img, int x, int y, int *r, int *g, int *b, int *a);
   1.160 +void img_getpixel4f(struct img_pixmap *img, int x, int y, float *r, float *g, float *b, float *a);
   1.161 +
   1.162 +
   1.163 +/* OpenGL helper functions */
   1.164 +
   1.165 +/* Returns the equivalent OpenGL "format" as expected by the 7th argument of glTexImage2D */
   1.166 +unsigned int img_fmt_glfmt(enum img_fmt fmt);
   1.167 +/* Returns the equivalent OpenGL "type" as expected by the 8th argument of glTexImage2D */
   1.168 +unsigned int img_fmt_gltype(enum img_fmt fmt);
   1.169 +/* Returns the equivalent OpenGL "internal format" as expected by the 3rd argument of glTexImage2D */
   1.170 +unsigned int img_fmt_glintfmt(enum img_fmt fmt);
   1.171 +
   1.172 +/* Same as above, based on the pixel format of the supplied image */
   1.173 +unsigned int img_glfmt(struct img_pixmap *img);
   1.174 +unsigned int img_gltype(struct img_pixmap *img);
   1.175 +unsigned int img_glintfmt(struct img_pixmap *img);
   1.176 +
   1.177 +/* Creates an OpenGL texture from the image, and returns the texture id, or 0 for failure */
   1.178 +unsigned int img_gltexture(struct img_pixmap *img);
   1.179 +
   1.180 +/* Load an image and create an OpenGL texture out of it */
   1.181 +unsigned int img_gltexture_load(const char *fname);
   1.182 +unsigned int img_gltexture_read_file(FILE *fp);
   1.183 +unsigned int img_gltexture_read(struct img_io *io);
   1.184 +
   1.185 +/* These functions can be used to fill an img_io struct before it's passed to
   1.186 + * one of the user-defined i/o image reading/writing functions (img_read/img_write).
   1.187 + *
   1.188 + * User-defined i/o functions:
   1.189 + *
   1.190 + * - size_t read_func(void *buffer, size_t bytes, void *user_ptr)
   1.191 + * Must try to fill the buffer with the specified number of bytes, and return
   1.192 + * the number of bytes actually read.
   1.193 + *
   1.194 + * - size_t write_func(void *buffer, size_t bytes, void *user_ptr)
   1.195 + * Must write the specified number of bytes from the supplied buffer and return
   1.196 + * the number of bytes actually written.
   1.197 + *
   1.198 + * - long seek_func(long offset, int whence, void *user_ptr)
   1.199 + * Must seek offset bytes from: the beginning of the file if whence is SEEK_SET,
   1.200 + * the current position if whence is SEEK_CUR, or the end of the file if whence is
   1.201 + * SEEK_END, and return the resulting file offset from the beginning of the file.
   1.202 + * (i.e. seek_func(0, SEEK_CUR, user_ptr); must be equivalent to an ftell).
   1.203 + *
   1.204 + * All three functions get the user-data pointer set through img_io_set_user_data
   1.205 + * as their last argument.
   1.206 + *
   1.207 + * Note: obviously you don't need to set a write function if you're only going
   1.208 + * to call img_read, or the read and seek function if you're only going to call
   1.209 + * img_write.
   1.210 + *
   1.211 + * Note: if the user-supplied write function is buffered, make sure to flush
   1.212 + * (or close the file) after img_write returns.
   1.213 + */
   1.214 +void img_io_set_user_data(struct img_io *io, void *uptr);
   1.215 +void img_io_set_read_func(struct img_io *io, size_t (*read)(void*, size_t, void*));
   1.216 +void img_io_set_write_func(struct img_io *io, size_t (*write)(void*, size_t, void*));
   1.217 +void img_io_set_seek_func(struct img_io *io, long (*seek)(long, int, void*));
   1.218 +
   1.219 +
   1.220 +#ifdef __cplusplus
   1.221 +}
   1.222 +#endif
   1.223 +
   1.224 +
   1.225 +#endif	/* IMAGO_H_ */