images/images.h

   1 /*
   2  *      Image Library -- Main header file
   3  *
   4  *      (c) 2006 Pavel Charvat <pchar@ucw.cz>
   5  *
   6  *      This software may be freely distributed and used according to the terms
   7  *      of the GNU Lesser General Public License.
   8  */
   9
  10 #ifndef _IMAGES_IMAGES_H
  11 #define _IMAGES_IMAGES_H
  12
  13 #include "lib/bbuf.h"
  14
  15 struct mempool;
  16 struct fastbuf;
  17
  18
  19 /* context.c
  20  * - contexts with error/message handling
  21  * - imagelib is thread-safe as long as threads work in different contexts */
  22
  23 struct image_context {
  24   byte *msg;                            /* last message */
  25   uns msg_code;                         /* last message code (see images/error.h for details) */
  26   bb_t msg_buf;                         /* message buffer */
  27   void (*msg_callback)(struct image_context *ctx); /* called for each message (in msg_{str,code}) */
  28   uns tracing_level;                    /* tracing level (zero to disable) */
  29 };
  30
  31 /* initialization/cleanup */
  32 void image_context_init(struct image_context *ctx);
  33 void image_context_cleanup(struct image_context *ctx);
  34
  35 /* message handling, see images/error.h for useful macros */
  36 void image_context_msg(struct image_context *ctx, uns code, char *msg, ...);
  37 void image_context_vmsg(struct image_context *ctx, uns code, char *msg, va_list args);
  38
  39 /* default callback, displays messages with standard libucw's log() routine */
  40 void image_context_msg_default(struct image_context *ctx);
  41
  42 /* empty callback */
  43 void image_context_msg_silent(struct image_context *ctx);
  44
  45
  46 /* image.c
  47  * - basic manipulation with images
  48  * - image structure is not directly connected to a single context
  49  *   but manipulation routines are (user must synchronize the access himself)! */
  50
  51 extern uns image_max_dim;               /* ImageLib.ImageMaxDim */
  52 extern uns image_max_bytes;             /* ImageLib.ImageMaxBytes */
  53
  54 /* SSE aligning size, see IMAGE_SSE_ALIGNED */
  55 #define IMAGE_SSE_ALIGN_SIZE 16
  56
  57 enum image_flag {
  58   IMAGE_COLOR_SPACE = 0x7,              /* mask for enum color_space */
  59   IMAGE_ALPHA = 0x8,                    /* alpha channel */
  60   IMAGE_PIXELS_ALIGNED = 0x10,          /* align pixel size to the nearest power of two  */
  61   IMAGE_SSE_ALIGNED = 0x20,             /* align scanlines to multiples of 16 bytes (both start and size) */
  62   IMAGE_NEED_DESTROY = 0x40,            /* image is allocated with xmalloc */
  63   IMAGE_GAPS_PROTECTED = 0x80,          /* cannot access gaps between rows */
  64   IMAGE_CHANNELS_FORMAT = IMAGE_COLOR_SPACE | IMAGE_ALPHA,
  65   IMAGE_PIXEL_FORMAT = IMAGE_CHANNELS_FORMAT | IMAGE_PIXELS_ALIGNED,
  66   IMAGE_ALIGNED = IMAGE_PIXELS_ALIGNED | IMAGE_SSE_ALIGNED,
  67   IMAGE_NEW_FLAGS = IMAGE_PIXEL_FORMAT | IMAGE_SSE_ALIGNED,
  68   IMAGE_INTERNAL_FLAGS = IMAGE_NEED_DESTROY | IMAGE_GAPS_PROTECTED,
  69 };
  70
  71 struct image {
  72   byte *pixels;                 /* aligned top left pixel, there are at least sizeof(uns)
  73                                    unused bytes after the buffer (possible optimizations) */
  74   uns cols;                     /* number of columns */
  75   uns rows;                     /* number of rows */
  76   uns pixel_size;               /* size of pixel in bytes (1, 2, 3 or 4) */
  77   uns row_size;                 /* scanline size in bytes */
  78   uns row_pixels_size;          /* scanline size in bytes excluding rows gaps */
  79   uns image_size;               /* rows * row_size */
  80   uns flags;                    /* enum image_flag */
  81 };
  82
  83 struct image *image_new(struct image_context *ctx, uns cols, uns rows, uns flags, struct mempool *pool);
  84 struct image *image_clone(struct image_context *ctx, struct image *src, uns flags, struct mempool *pool);
  85 void image_destroy(struct image *img);
  86 void image_clear(struct image_context *ctx, struct image *img);
  87 struct image *image_init_matrix(struct image_context *ctx, struct image *img, byte *pixels, uns cols, uns rows, uns row_size, uns flags);
  88 struct image *image_init_subimage(struct image_context *ctx, struct image *img, struct image *src, uns left, uns top, uns cols, uns rows);
  89
  90 static inline int
  91 image_dimensions_valid(uns cols, uns rows)
  92 {
  93   return cols && rows && cols <= image_max_dim && rows <= image_max_dim;
  94 }
  95
  96 byte *color_space_to_name(uns cs);
  97 byte *image_channels_format_to_name(uns format);
  98 uns image_name_to_channels_format(byte *name);
  99
 100 struct color {
 101   byte c[3];
 102   byte color_space;
 103 } PACKED;
 104
 105 /* scale.c */
 106
 107 int image_scale(struct image_context *ctx, struct image *dest, struct image *src);
 108 void image_dimensions_fit_to_box(uns *cols, uns *rows, uns max_cols, uns max_rows, uns upsample);
 109
 110 /* alpha.c */
 111
 112 int image_apply_background(struct image_context *ctx, struct image *dest, struct image *src, struct color *background);
 113
 114 /* image-io.c */
 115
 116 enum image_format {
 117   IMAGE_FORMAT_UNDEFINED,
 118   IMAGE_FORMAT_JPEG,
 119   IMAGE_FORMAT_PNG,
 120   IMAGE_FORMAT_GIF,
 121   IMAGE_FORMAT_MAX
 122 };
 123
 124 struct image_io {
 125                                         /*  R - read_header input */
 126                                         /*   H - read_header output */
 127                                         /*    I - read_data input */
 128                                         /*     O - read_data output */
 129                                         /*      W - write input */
 130
 131   struct image *image;                  /* [   OW] - image data */
 132   enum image_format format;             /* [R   W] - file format (IMAGE_FORMAT_x) */
 133   struct fastbuf *fastbuf;              /* [R   W] - source/destination stream */
 134   struct mempool *pool;                 /* [  I  ] - parameter to image_new */
 135   uns cols;                             /* [ HI  ] - number of columns, parameter to image_new */
 136   uns rows;                             /* [ HI  ] - number of rows, parameter to image_new */
 137   uns flags;                            /* [ HI  ] - see enum image_io_flags */
 138   uns jpeg_quality;                     /* [    W] - JPEG compression quality (1..100) */
 139   uns number_of_colors;                 /* [ H   ] - number of image colors */
 140   struct color background_color;        /* [ HI  ] - background color, zero if undefined */
 141   uns exif_size;                        /* [ H  W] - EXIF size in bytes (zero if not present) */
 142   byte *exif_data;                      /* [ H  W] - EXIF data */
 143
 144   /* internals */
 145   struct image_context *context;
 146   struct mempool *internal_pool;
 147   void *read_data;
 148   void (*read_cancel)(struct image_io *io);
 149 };
 150
 151 enum image_io_flags {
 152   IMAGE_IO_IMAGE_FLAGS = 0xffff,        /* [ HI  ] - mask of parameters to image new, read_header fills IMAGE_CHANNELS_FORMAT */
 153   IMAGE_IO_NEED_DESTROY = 0x10000,      /* [   O ] - enables automatic call of image_destroy */
 154   IMAGE_IO_HAS_PALETTE = 0x20000,       /* [ H   ] - true for image with indexed colors */
 155   IMAGE_IO_USE_BACKGROUND = 0x40000,    /* [  I  ] - merge transparent pixels with background_color */
 156   IMAGE_IO_WANT_EXIF = 0x80000,         /* [R    ] - read EXIF data if present */
 157 };
 158
 159 int image_io_init(struct image_context *ctx, struct image_io *io);
 160 void image_io_cleanup(struct image_io *io);
 161 void image_io_reset(struct image_io *io);
 162
 163 int image_io_read_header(struct image_io *io);
 164 struct image *image_io_read_data(struct image_io *io, int ref);
 165 struct image *image_io_read(struct image_io *io, int ref);
 166
 167 int image_io_write(struct image_io *io);
 168
 169 byte *image_format_to_extension(enum image_format format);
 170 enum image_format image_extension_to_format(byte *extension);
 171 enum image_format image_file_name_to_format(byte *file_name);
 172
 173 #endif