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 #ifdef CONFIG_UCW_CLEAN_ABI
  16 #define image_channels_format_to_name ucw_image_channels_format_to_name
  17 #define image_clear ucw_image_clear
  18 #define image_clone ucw_image_clone
  19 #define image_context_cleanup ucw_image_context_cleanup
  20 #define image_context_init ucw_image_context_init
  21 #define image_context_msg ucw_image_context_msg
  22 #define image_context_msg_default ucw_image_context_msg_default
  23 #define image_context_msg_silent ucw_image_context_msg_silent
  24 #define image_context_vmsg ucw_image_context_vmsg
  25 #define image_destroy ucw_image_destroy
  26 #define image_dimensions_fit_to_box ucw_image_dimensions_fit_to_box
  27 #define image_extension_to_format ucw_image_extension_to_format
  28 #define image_file_name_to_format ucw_image_file_name_to_format
  29 #define image_format_to_extension ucw_image_format_to_extension
  30 #define image_init_matrix ucw_image_init_matrix
  31 #define image_init_subimage ucw_image_init_subimage
  32 #define image_io_cleanup ucw_image_io_cleanup
  33 #define image_io_init ucw_image_io_init
  34 #define image_io_read ucw_image_io_read
  35 #define image_io_read_data ucw_image_io_read_data
  36 #define image_io_read_header ucw_image_io_read_header
  37 #define image_io_reset ucw_image_io_reset
  38 #define image_io_write ucw_image_io_write
  39 #define image_max_bytes ucw_image_max_bytes
  40 #define image_max_dim ucw_image_max_dim
  41 #define image_name_to_channels_format ucw_image_name_to_channels_format
  42 #define image_new ucw_image_new
  43 #define image_scale ucw_image_scale
  44 #endif
  45
  46 struct mempool;
  47 struct fastbuf;
  48
  49
  50 /* context.c
  51  * - contexts with error/message handling
  52  * - imagelib is thread-safe as long as threads work in different contexts */
  53
  54 struct image_context {
  55   byte *msg;                            /* last message */
  56   uint msg_code;                        /* last message code (see images/error.h for details) */
  57   bb_t msg_buf;                         /* message buffer */
  58   void (*msg_callback)(struct image_context *ctx); /* called for each message (in msg_{str,code}) */
  59   uint tracing_level;                   /* tracing level (zero to disable) */
  60 };
  61
  62 /* initialization/cleanup */
  63 void image_context_init(struct image_context *ctx);
  64 void image_context_cleanup(struct image_context *ctx);
  65
  66 /* message handling, see images/error.h for useful macros */
  67 void image_context_msg(struct image_context *ctx, uint code, char *msg, ...);
  68 void image_context_vmsg(struct image_context *ctx, uint code, char *msg, va_list args);
  69
  70 /* default callback, displays messages with standard libucw's log() routine */
  71 void image_context_msg_default(struct image_context *ctx);
  72
  73 /* empty callback */
  74 void image_context_msg_silent(struct image_context *ctx);
  75
  76
  77 /* image.c
  78  * - basic manipulation with images
  79  * - image structure is not directly connected to a single context
  80  *   but manipulation routines are (user must synchronize the access himself)! */
  81
  82 extern uint image_max_dim;              /* ImageLib.ImageMaxDim */
  83 extern uint image_max_bytes;            /* ImageLib.ImageMaxBytes */
  84
  85 /* SSE aligning size, see IMAGE_SSE_ALIGNED */
  86 #define IMAGE_SSE_ALIGN_SIZE 16
  87
  88 enum image_flag {
  89   IMAGE_COLOR_SPACE = 0xf,              /* mask for enum color_space */
  90   IMAGE_ALPHA = 0x10,                   /* alpha channel */
  91   IMAGE_PIXELS_ALIGNED = 0x20,          /* align pixel size to the nearest power of two  */
  92   IMAGE_SSE_ALIGNED = 0x40,             /* align scanlines to multiples of 16 bytes (both start and size) */
  93   IMAGE_NEED_DESTROY = 0x80,            /* image is allocated with xmalloc */
  94   IMAGE_GAPS_PROTECTED = 0x100,         /* cannot access gaps between rows */
  95   IMAGE_CHANNELS_FORMAT = IMAGE_COLOR_SPACE | IMAGE_ALPHA,
  96   IMAGE_PIXEL_FORMAT = IMAGE_CHANNELS_FORMAT | IMAGE_PIXELS_ALIGNED,
  97   IMAGE_ALIGNED = IMAGE_PIXELS_ALIGNED | IMAGE_SSE_ALIGNED,
  98   IMAGE_NEW_FLAGS = IMAGE_PIXEL_FORMAT | IMAGE_SSE_ALIGNED,
  99   IMAGE_INTERNAL_FLAGS = IMAGE_NEED_DESTROY | IMAGE_GAPS_PROTECTED,
 100 };
 101
 102 #define IMAGE_MAX_CHANNELS 4
 103 #define IMAGE_CHANNELS_FORMAT_MAX_SIZE 128
 104 byte *image_channels_format_to_name(uint format, byte *buf);
 105 uint image_name_to_channels_format(byte *name);
 106
 107 struct color {
 108   byte c[IMAGE_MAX_CHANNELS];
 109   byte color_space;
 110 };
 111
 112 struct image {
 113   byte *pixels;                 /* aligned top left pixel, there are at least sizeof(uint)
 114                                    unused bytes after the buffer (possible optimizations) */
 115   uint cols;                    /* number of columns */
 116   uint rows;                    /* number of rows */
 117   uint channels;                /* number of color channels including the alpha channel */
 118   uint pixel_size;              /* size of pixel in bytes (1, 2, 3 or 4) */
 119   uint row_size;                /* scanline size in bytes */
 120   uint row_pixels_size;         /* scanline size in bytes excluding rows gaps */
 121   uint image_size;              /* rows * row_size */
 122   uint flags;                   /* enum image_flag */
 123 };
 124
 125 struct image *image_new(struct image_context *ctx, uint cols, uint rows, uint flags, struct mempool *pool);
 126 struct image *image_clone(struct image_context *ctx, struct image *src, uint flags, struct mempool *pool);
 127 void image_destroy(struct image *img);
 128 void image_clear(struct image_context *ctx, struct image *img);
 129 struct image *image_init_matrix(struct image_context *ctx, struct image *img, byte *pixels, uint cols, uint rows, uint row_size, uint flags);
 130 struct image *image_init_subimage(struct image_context *ctx, struct image *img, struct image *src, uint left, uint top, uint cols, uint rows);
 131
 132 static inline int image_dimensions_valid(uint cols, uint rows)
 133 {
 134   return cols && rows && cols <= image_max_dim && rows <= image_max_dim;
 135 }
 136 /* scale.c */
 137
 138 int image_scale(struct image_context *ctx, struct image *dest, struct image *src);
 139 void image_dimensions_fit_to_box(uint *cols, uint *rows, uint max_cols, uint max_rows, uint upsample);
 140
 141 /* image-io.c */
 142
 143 enum image_format {
 144   IMAGE_FORMAT_UNDEFINED,
 145   IMAGE_FORMAT_JPEG,
 146   IMAGE_FORMAT_PNG,
 147   IMAGE_FORMAT_GIF,
 148   IMAGE_FORMAT_MAX
 149 };
 150
 151 struct image_io {
 152                                         /*  R - read_header input */
 153                                         /*   H - read_header output */
 154                                         /*    I - read_data input */
 155                                         /*     O - read_data output */
 156                                         /*      W - write input */
 157
 158   struct image *image;                  /* [   OW] - image data */
 159   enum image_format format;             /* [R   W] - file format (IMAGE_FORMAT_x) */
 160   struct fastbuf *fastbuf;              /* [R   W] - source/destination stream */
 161   struct mempool *pool;                 /* [  I  ] - parameter to image_new */
 162   uint cols;                            /* [ HI  ] - number of columns, parameter to image_new */
 163   uint rows;                            /* [ HI  ] - number of rows, parameter to image_new */
 164   uint flags;                           /* [ HI  ] - see enum image_io_flags */
 165   uint jpeg_quality;                    /* [    W] - JPEG compression quality (1..100) */
 166   uint number_of_colors;                /* [ H   ] - number of image colors */
 167   struct color background_color;        /* [ HI  ] - background color, zero if undefined */
 168   uint exif_size;                       /* [ H  W] - EXIF size in bytes (zero if not present) */
 169   byte *exif_data;                      /* [ H  W] - EXIF data */
 170
 171   /* internals */
 172   struct image_context *context;
 173   struct mempool *internal_pool;
 174   void *read_data;
 175   void (*read_cancel)(struct image_io *io);
 176 };
 177
 178 enum image_io_flags {
 179   IMAGE_IO_IMAGE_FLAGS = 0xffff,        /* [ HI  ] - mask of parameters to image new, read_header fills IMAGE_CHANNELS_FORMAT */
 180   IMAGE_IO_NEED_DESTROY = 0x10000,      /* [   O ] - enables automatic call of image_destroy */
 181   IMAGE_IO_HAS_PALETTE = 0x20000,       /* [ H   ] - true for image with indexed colors */
 182   IMAGE_IO_USE_BACKGROUND = 0x40000,    /* [  I  ] - merge transparent pixels with background_color */
 183   IMAGE_IO_WANT_EXIF = 0x80000,         /* [R    ] - read EXIF data if present */
 184 };
 185
 186 int image_io_init(struct image_context *ctx, struct image_io *io);
 187 void image_io_cleanup(struct image_io *io);
 188 void image_io_reset(struct image_io *io);
 189
 190 int image_io_read_header(struct image_io *io);
 191 struct image *image_io_read_data(struct image_io *io, int ref);
 192 struct image *image_io_read(struct image_io *io, int ref);
 193
 194 int image_io_write(struct image_io *io);
 195
 196 byte *image_format_to_extension(enum image_format format);
 197 enum image_format image_extension_to_format(byte *extension);
 198 enum image_format image_file_name_to_format(byte *file_name);
 199
 200 #endif