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 = 0xf,              /* mask for enum color_space */
  59   IMAGE_ALPHA = 0x10,                   /* alpha channel */
  60   IMAGE_PIXELS_ALIGNED = 0x20,          /* align pixel size to the nearest power of two  */
  61   IMAGE_SSE_ALIGNED = 0x40,             /* align scanlines to multiples of 16 bytes (both start and size) */
  62   IMAGE_NEED_DESTROY = 0x80,            /* image is allocated with xmalloc */
  63   IMAGE_GAPS_PROTECTED = 0x100,         /* 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 channels;                 /* number of color channels */
  77   uns pixel_size;               /* size of pixel in bytes (1, 2, 3 or 4) */
  78   uns row_size;                 /* scanline size in bytes */
  79   uns row_pixels_size;          /* scanline size in bytes excluding rows gaps */
  80   uns image_size;               /* rows * row_size */
  81   uns flags;                    /* enum image_flag */
  82 };
  83
  84 struct image *image_new(struct image_context *ctx, uns cols, uns rows, uns flags, struct mempool *pool);
  85 struct image *image_clone(struct image_context *ctx, struct image *src, uns flags, struct mempool *pool);
  86 void image_destroy(struct image *img);
  87 void image_clear(struct image_context *ctx, struct image *img);
  88 struct image *image_init_matrix(struct image_context *ctx, struct image *img, byte *pixels, uns cols, uns rows, uns row_size, uns flags);
  89 struct image *image_init_subimage(struct image_context *ctx, struct image *img, struct image *src, uns left, uns top, uns cols, uns rows);
  90
  91 static inline int
  92 image_dimensions_valid(uns cols, uns rows)
  93 {
  94   return cols && rows && cols <= image_max_dim && rows <= image_max_dim;
  95 }
  96
  97 #define IMAGE_CHANNELS_FORMAT_MAX_SIZE 128
  98 byte *image_channels_format_to_name(uns format, byte *buf);
  99 uns image_name_to_channels_format(byte *name);
 100
 101 struct color {
 102   byte c[3];
 103   byte color_space;
 104 } PACKED;
 105
 106 /* scale.c */
 107
 108 int image_scale(struct image_context *ctx, struct image *dest, struct image *src);
 109 void image_dimensions_fit_to_box(uns *cols, uns *rows, uns max_cols, uns max_rows, uns upsample);
 110
 111 /* alpha.c */
 112
 113 int image_apply_background(struct image_context *ctx, struct image *dest, struct image *src, struct color *background);
 114
 115 /* image-io.c */
 116
 117 enum image_format {
 118   IMAGE_FORMAT_UNDEFINED,
 119   IMAGE_FORMAT_JPEG,
 120   IMAGE_FORMAT_PNG,
 121   IMAGE_FORMAT_GIF,
 122   IMAGE_FORMAT_MAX
 123 };
 124
 125 struct image_io {
 126                                         /*  R - read_header input */
 127                                         /*   H - read_header output */
 128                                         /*    I - read_data input */
 129                                         /*     O - read_data output */
 130                                         /*      W - write input */
 131
 132   struct image *image;                  /* [   OW] - image data */
 133   enum image_format format;             /* [R   W] - file format (IMAGE_FORMAT_x) */
 134   struct fastbuf *fastbuf;              /* [R   W] - source/destination stream */
 135   struct mempool *pool;                 /* [  I  ] - parameter to image_new */
 136   uns cols;                             /* [ HI  ] - number of columns, parameter to image_new */
 137   uns rows;                             /* [ HI  ] - number of rows, parameter to image_new */
 138   uns flags;                            /* [ HI  ] - see enum image_io_flags */
 139   uns jpeg_quality;                     /* [    W] - JPEG compression quality (1..100) */
 140   uns number_of_colors;                 /* [ H   ] - number of image colors */
 141   struct color background_color;        /* [ HI  ] - background color, zero if undefined */
 142   uns exif_size;                        /* [ H  W] - EXIF size in bytes (zero if not present) */
 143   byte *exif_data;                      /* [ H  W] - EXIF data */
 144
 145   /* internals */
 146   struct image_context *context;
 147   struct mempool *internal_pool;
 148   void *read_data;
 149   void (*read_cancel)(struct image_io *io);
 150 };
 151
 152 enum image_io_flags {
 153   IMAGE_IO_IMAGE_FLAGS = 0xffff,        /* [ HI  ] - mask of parameters to image new, read_header fills IMAGE_CHANNELS_FORMAT */
 154   IMAGE_IO_NEED_DESTROY = 0x10000,      /* [   O ] - enables automatic call of image_destroy */
 155   IMAGE_IO_HAS_PALETTE = 0x20000,       /* [ H   ] - true for image with indexed colors */
 156   IMAGE_IO_USE_BACKGROUND = 0x40000,    /* [  I  ] - merge transparent pixels with background_color */
 157   IMAGE_IO_WANT_EXIF = 0x80000,         /* [R    ] - read EXIF data if present */
 158 };
 159
 160 int image_io_init(struct image_context *ctx, struct image_io *io);
 161 void image_io_cleanup(struct image_io *io);
 162 void image_io_reset(struct image_io *io);
 163
 164 int image_io_read_header(struct image_io *io);
 165 struct image *image_io_read_data(struct image_io *io, int ref);
 166 struct image *image_io_read(struct image_io *io, int ref);
 167
 168 int image_io_write(struct image_io *io);
 169
 170 byte *image_format_to_extension(enum image_format format);
 171 enum image_format image_extension_to_format(byte *extension);
 172 enum image_format image_file_name_to_format(byte *file_name);
 173
 174 #endif