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 <ucw/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 #define IMAGE_MAX_CHANNELS 4
  72 #define IMAGE_CHANNELS_FORMAT_MAX_SIZE 128
  73 byte *image_channels_format_to_name(uns format, byte *buf);
  74 uns image_name_to_channels_format(byte *name);
  75
  76 struct color {
  77   byte c[IMAGE_MAX_CHANNELS];
  78   byte color_space;
  79 };
  80
  81 struct image {
  82   byte *pixels;                 /* aligned top left pixel, there are at least sizeof(uns)
  83                                    unused bytes after the buffer (possible optimizations) */
  84   uns cols;                     /* number of columns */
  85   uns rows;                     /* number of rows */
  86   uns channels;                 /* number of color channels including the alpha channel */
  87   uns pixel_size;               /* size of pixel in bytes (1, 2, 3 or 4) */
  88   uns row_size;                 /* scanline size in bytes */
  89   uns row_pixels_size;          /* scanline size in bytes excluding rows gaps */
  90   uns image_size;               /* rows * row_size */
  91   uns flags;                    /* enum image_flag */
  92 };
  93
  94 struct image *image_new(struct image_context *ctx, uns cols, uns rows, uns flags, struct mempool *pool);
  95 struct image *image_clone(struct image_context *ctx, struct image *src, uns flags, struct mempool *pool);
  96 void image_destroy(struct image *img);
  97 void image_clear(struct image_context *ctx, struct image *img);
  98 struct image *image_init_matrix(struct image_context *ctx, struct image *img, byte *pixels, uns cols, uns rows, uns row_size, uns flags);
  99 struct image *image_init_subimage(struct image_context *ctx, struct image *img, struct image *src, uns left, uns top, uns cols, uns rows);
 100
 101 static inline int
 102 image_dimensions_valid(uns cols, uns rows)
 103 {
 104   return cols && rows && cols <= image_max_dim && rows <= image_max_dim;
 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 /* image-io.c */
 112
 113 enum image_format {
 114   IMAGE_FORMAT_UNDEFINED,
 115   IMAGE_FORMAT_JPEG,
 116   IMAGE_FORMAT_PNG,
 117   IMAGE_FORMAT_GIF,
 118   IMAGE_FORMAT_MAX
 119 };
 120
 121 struct image_io {
 122                                         /*  R - read_header input */
 123                                         /*   H - read_header output */
 124                                         /*    I - read_data input */
 125                                         /*     O - read_data output */
 126                                         /*      W - write input */
 127
 128   struct image *image;                  /* [   OW] - image data */
 129   enum image_format format;             /* [R   W] - file format (IMAGE_FORMAT_x) */
 130   struct fastbuf *fastbuf;              /* [R   W] - source/destination stream */
 131   struct mempool *pool;                 /* [  I  ] - parameter to image_new */
 132   uns cols;                             /* [ HI  ] - number of columns, parameter to image_new */
 133   uns rows;                             /* [ HI  ] - number of rows, parameter to image_new */
 134   uns flags;                            /* [ HI  ] - see enum image_io_flags */
 135   uns jpeg_quality;                     /* [    W] - JPEG compression quality (1..100) */
 136   uns number_of_colors;                 /* [ H   ] - number of image colors */
 137   struct color background_color;        /* [ HI  ] - background color, zero if undefined */
 138   uns exif_size;                        /* [ H  W] - EXIF size in bytes (zero if not present) */
 139   byte *exif_data;                      /* [ H  W] - EXIF data */
 140
 141   /* internals */
 142   struct image_context *context;
 143   struct mempool *internal_pool;
 144   void *read_data;
 145   void (*read_cancel)(struct image_io *io);
 146 };
 147
 148 enum image_io_flags {
 149   IMAGE_IO_IMAGE_FLAGS = 0xffff,        /* [ HI  ] - mask of parameters to image new, read_header fills IMAGE_CHANNELS_FORMAT */
 150   IMAGE_IO_NEED_DESTROY = 0x10000,      /* [   O ] - enables automatic call of image_destroy */
 151   IMAGE_IO_HAS_PALETTE = 0x20000,       /* [ H   ] - true for image with indexed colors */
 152   IMAGE_IO_USE_BACKGROUND = 0x40000,    /* [  I  ] - merge transparent pixels with background_color */
 153   IMAGE_IO_WANT_EXIF = 0x80000,         /* [R    ] - read EXIF data if present */
 154 };
 155
 156 int image_io_init(struct image_context *ctx, struct image_io *io);
 157 void image_io_cleanup(struct image_io *io);
 158 void image_io_reset(struct image_io *io);
 159
 160 int image_io_read_header(struct image_io *io);
 161 struct image *image_io_read_data(struct image_io *io, int ref);
 162 struct image *image_io_read(struct image_io *io, int ref);
 163
 164 int image_io_write(struct image_io *io);
 165
 166 byte *image_format_to_extension(enum image_format format);
 167 enum image_format image_extension_to_format(byte *extension);
 168 enum image_format image_file_name_to_format(byte *file_name);
 169
 170 #endif