git.mutantstargoat.com Git - retroray/blob - libs/imago/src/imago2.h

   1 /*
   2 libimago - a multi-format image file input/output library.
   3 Copyright (C) 2010-2021 John Tsiombikas <nuclear@member.fsf.org>
   4
   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.
   9
  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.
  14
  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 */
  18
  19 #ifndef IMAGO2_H_
  20 #define IMAGO2_H_
  21
  22 #include <stdio.h>
  23
  24 #ifdef __cplusplus
  25 #define IMG_OPTARG(arg, val)    arg = val
  26 #else
  27 #define IMG_OPTARG(arg, val)    arg
  28 #endif
  29
  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,
  38         IMG_FMT_BGRA32,
  39         IMG_FMT_RGB565,
  40         IMG_FMT_IDX8,
  41
  42         NUM_IMG_FMT
  43 };
  44
  45 struct img_pixmap {
  46         void *pixels;
  47         int width, height;
  48         enum img_fmt fmt;
  49         int pixelsz;
  50         char *name;
  51 };
  52
  53 struct img_colormap {
  54         int ncolors;
  55         struct {
  56                 unsigned char r, g, b;
  57         } color[256];
  58 };
  59
  60 struct img_io {
  61         void *uptr;     /* user-data */
  62
  63         size_t (*read)(void *buf, size_t bytes, void *uptr);
  64         size_t (*write)(void *buf, size_t bytes, void *uptr);
  65         long (*seek)(long offs, int whence, void *uptr);
  66 };
  67
  68 #ifdef __cplusplus
  69 extern "C" {
  70 #endif
  71
  72 /* initialize the img_pixmap structure */
  73 void img_init(struct img_pixmap *img);
  74 /* destroys the img_pixmap structure, freeing the pixel buffer (if available)
  75  * and any other memory held by the pixmap.
  76  */
  77 void img_destroy(struct img_pixmap *img);
  78
  79 /* convenience function that allocates an img_pixmap struct and then initializes it.
  80  * returns null if the malloc fails.
  81  */
  82 struct img_pixmap *img_create(void);
  83 /* frees a pixmap previously allocated with img_create (free followed by img_destroy) */
  84 void img_free(struct img_pixmap *img);
  85
  86 int img_set_name(struct img_pixmap *img, const char *name);
  87
  88 /* set the image pixel format */
  89 int img_set_format(struct img_pixmap *img, enum img_fmt fmt);
  90
  91 /* copies one pixmap to another.
  92  * equivalent to: img_set_pixels(dest, src->width, src->height, src->fmt, src->pixels)
  93  */
  94 int img_copy(struct img_pixmap *dest, struct img_pixmap *src);
  95
  96 /* allocates a pixel buffer of the specified dimensions and format, and copies the
  97  * pixels given through the pix pointer into it.
  98  * the pix pointer can be null, in which case there's no copy, just allocation.
  99  *
 100  * C++: fmt and pix have default parameters IMG_FMT_RGBA32 and null respectively.
 101  */
 102 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));
 103
 104 /* Simplified image loading
 105  * Loads the specified file, and returns a pointer to an array of pixels of the
 106  * requested pixel format. The width and height of the image are returned through
 107  * the xsz and ysz pointers.
 108  * If the image cannot be loaded, the function returns null.
 109  *
 110  * C++: the format argument is optional and defaults to IMG_FMT_RGBA32
 111  */
 112 void *img_load_pixels(const char *fname, int *xsz, int *ysz, IMG_OPTARG(enum img_fmt fmt, IMG_FMT_RGBA32));
 113
 114 /* Simplified image saving
 115  * Reads an array of pixels supplied through the pix pointer, of dimensions xsz
 116  * and ysz, and pixel-format fmt, and saves it to a file.
 117  * The output filetype is guessed by the filename suffix.
 118  *
 119  * C++: the format argument is optional and defaults to IMG_FMT_RGBA32
 120  */
 121 int img_save_pixels(const char *fname, void *pix, int xsz, int ysz, IMG_OPTARG(enum img_fmt fmt, IMG_FMT_RGBA32));
 122
 123 /* Frees the memory allocated by img_load_pixels */
 124 void img_free_pixels(void *pix);
 125
 126 /* Loads an image file into the supplied pixmap */
 127 int img_load(struct img_pixmap *img, const char *fname);
 128 /* Saves the supplied pixmap to a file. The output filetype is guessed by the filename suffix */
 129 int img_save(struct img_pixmap *img, const char *fname);
 130
 131 /* Reads an image from an open FILE* into the supplied pixmap */
 132 int img_read_file(struct img_pixmap *img, FILE *fp);
 133 /* Writes the supplied pixmap to an open FILE* */
 134 int img_write_file(struct img_pixmap *img, FILE *fp);
 135
 136 /* Reads an image using user-defined file-i/o functions (see img_io_set_*) */
 137 int img_read(struct img_pixmap *img, struct img_io *io);
 138 /* Writes an image using user-defined file-i/o functions (see img_io_set_*) */
 139 int img_write(struct img_pixmap *img, struct img_io *io);
 140
 141 /* Converts an image to the specified pixel format */
 142 int img_convert(struct img_pixmap *img, enum img_fmt tofmt);
 143
 144 /* Converts an image from an integer pixel format to the corresponding floating point one */
 145 int img_to_float(struct img_pixmap *img);
 146 /* Converts an image from a floating point pixel format to the corresponding integer one */
 147 int img_to_integer(struct img_pixmap *img);
 148
 149 /* Returns non-zero (true) if the supplied image is in a floating point pixel format */
 150 int img_is_float(struct img_pixmap *img);
 151 /* Returns non-zero (true) if the supplied image has an alpha channel */
 152 int img_has_alpha(struct img_pixmap *img);
 153 /* Returns non-zero (true) if the supplied image is greyscale */
 154 int img_is_greyscale(struct img_pixmap *img);
 155
 156
 157 /* don't use these for anything performance-critical */
 158 void img_setpixel(struct img_pixmap *img, int x, int y, void *pixel);
 159 void img_getpixel(struct img_pixmap *img, int x, int y, void *pixel);
 160
 161 void img_setpixel1i(struct img_pixmap *img, int x, int y, int pix);
 162 void img_setpixel1f(struct img_pixmap *img, int x, int y, float pix);
 163 void img_setpixel4i(struct img_pixmap *img, int x, int y, int r, int g, int b, int a);
 164 void img_setpixel4f(struct img_pixmap *img, int x, int y, float r, float g, float b, float a);
 165
 166 void img_getpixel1i(struct img_pixmap *img, int x, int y, int *pix);
 167 void img_getpixel1f(struct img_pixmap *img, int x, int y, float *pix);
 168 void img_getpixel4i(struct img_pixmap *img, int x, int y, int *r, int *g, int *b, int *a);
 169 void img_getpixel4f(struct img_pixmap *img, int x, int y, float *r, float *g, float *b, float *a);
 170
 171 /* For IMG_FMT_IDX8 pixmaps, returns a pointer to the colormap, null otherwise */
 172 struct img_colormap *img_colormap(struct img_pixmap *img);
 173
 174
 175 /* OpenGL helper functions */
 176
 177 /* Returns the equivalent OpenGL "format" as expected by the 7th argument of glTexImage2D */
 178 unsigned int img_fmt_glfmt(enum img_fmt fmt);
 179 /* Returns the equivalent OpenGL "type" as expected by the 8th argument of glTexImage2D */
 180 unsigned int img_fmt_gltype(enum img_fmt fmt);
 181 /* Returns the equivalent OpenGL "internal format" as expected by the 3rd argument of glTexImage2D */
 182 unsigned int img_fmt_glintfmt(enum img_fmt fmt);
 183 /* same as above, but will return the sRGB variant type for 8bit per color channel images */
 184 unsigned int img_fmt_glintfmt_srgb(enum img_fmt fmt);
 185
 186 /* Same as above, based on the pixel format of the supplied image */
 187 unsigned int img_glfmt(struct img_pixmap *img);
 188 unsigned int img_gltype(struct img_pixmap *img);
 189 unsigned int img_glintfmt(struct img_pixmap *img);
 190 unsigned int img_glintfmt_srgb(struct img_pixmap *img);
 191
 192 /* Creates an OpenGL texture from the image, and returns the texture id, or 0 for failure */
 193 unsigned int img_gltexture(struct img_pixmap *img);
 194
 195 /* Load an image and create an OpenGL texture out of it */
 196 unsigned int img_gltexture_load(const char *fname);
 197 unsigned int img_gltexture_read_file(FILE *fp);
 198 unsigned int img_gltexture_read(struct img_io *io);
 199
 200 /* These functions can be used to fill an img_io struct before it's passed to
 201  * one of the user-defined i/o image reading/writing functions (img_read/img_write).
 202  *
 203  * User-defined i/o functions:
 204  *
 205  * - size_t read_func(void *buffer, size_t bytes, void *user_ptr)
 206  * Must try to fill the buffer with the specified number of bytes, and return
 207  * the number of bytes actually read.
 208  *
 209  * - size_t write_func(void *buffer, size_t bytes, void *user_ptr)
 210  * Must write the specified number of bytes from the supplied buffer and return
 211  * the number of bytes actually written.
 212  *
 213  * - long seek_func(long offset, int whence, void *user_ptr)
 214  * Must seek offset bytes from: the beginning of the file if whence is SEEK_SET,
 215  * the current position if whence is SEEK_CUR, or the end of the file if whence is
 216  * SEEK_END, and return the resulting file offset from the beginning of the file.
 217  * (i.e. seek_func(0, SEEK_CUR, user_ptr); must be equivalent to an ftell).
 218  *
 219  * All three functions get the user-data pointer set through img_io_set_user_data
 220  * as their last argument.
 221  *
 222  * Note: obviously you don't need to set a write function if you're only going
 223  * to call img_read, or the read and seek function if you're only going to call
 224  * img_write.
 225  *
 226  * Note: if the user-supplied write function is buffered, make sure to flush
 227  * (or close the file) after img_write returns.
 228  */
 229 void img_io_set_user_data(struct img_io *io, void *uptr);
 230 void img_io_set_read_func(struct img_io *io, size_t (*read)(void*, size_t, void*));
 231 void img_io_set_write_func(struct img_io *io, size_t (*write)(void*, size_t, void*));
 232 void img_io_set_seek_func(struct img_io *io, long (*seek)(long, int, void*));
 233
 234
 235 #ifdef __cplusplus
 236 }
 237 #endif
 238
 239
 240 #endif  /* IMAGO_H_ */