2 * Image Library -- Main hearer file
4 * (c) 2006 Pavel Charvat <pchar@ucw.cz>
6 * This software may be freely distributed and used according to the terms
7 * of the GNU Lesser General Public License.
10 #ifndef _IMAGES_IMAGES_H
11 #define _IMAGES_IMAGES_H
20 * - contexts with error/message handling
21 * - imagelib is thread-safe until each context is bounded to a single thread */
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) */
31 /* initialization/cleanup */
32 void image_context_init(struct image_context *ctx);
33 void image_context_cleanup(struct image_context *ctx);
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);
39 /* default callback, displays messages with standard libucw's log() routine */
40 void image_context_msg_default(struct image_context *ctx);
43 void image_context_msg_silent(struct image_context *ctx);
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)! */
51 extern uns image_max_dim; /* ImageLib.ImageMaxDim */
52 extern uns image_max_bytes; /* ImageLib.ImageMaxBytes */
54 /* SSE aligning size, see IMAGE_SSE_ALIGNED */
55 #define IMAGE_SSE_ALIGN_SIZE (MAX(16, sizeof(uns)))
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,
72 byte *pixels; /* aligned top left pixel, there are at least sizeof(uns)
73 unsed bytes after the buffer (possible optimizations) */
74 u32 cols; /* number of columns */
75 u32 rows; /* number of rows */
76 u32 pixel_size; /* size of pixel (1, 2, 3 or 4) */
77 u32 row_size; /* scanline size in bytes */
78 u32 image_size; /* rows * row_size */
79 u32 flags; /* enum image_flag */
82 struct image *image_new(struct image_context *ctx, uns cols, uns rows, uns flags, struct mempool *pool);
83 struct image *image_clone(struct image_context *ctx, struct image *src, uns flags, struct mempool *pool);
84 void image_destroy(struct image *img);
85 void image_clear(struct image_context *ctx, struct image *img);
86 struct image *image_init_matrix(struct image_context *ctx, struct image *img, byte *pixels, uns cols, uns rows, uns row_size, uns flags);
87 struct image *image_init_subimage(struct image_context *ctx, struct image *img, struct image *src, uns left, uns top, uns cols, uns rows);
90 image_dimensions_valid(uns cols, uns rows)
92 return cols && rows && cols <= image_max_dim && rows <= image_max_dim;
95 byte *color_space_to_name(uns cs);
96 byte *image_channels_format_to_name(uns format);
97 uns image_name_to_channels_format(byte *name);
106 int image_scale(struct image_context *ctx, struct image *dest, struct image *src);
107 void image_dimensions_fit_to_box(u32 *cols, u32 *rows, u32 max_cols, u32 max_rows, uns upsample);
111 int image_apply_background(struct image_context *ctx, struct image *dest, struct image *src, struct color *background);
116 IMAGE_FORMAT_UNDEFINED,
124 /* R - read_header input */
125 /* H - read_header output */
126 /* I - read_data input */
127 /* O - read_data output */
128 /* W - write input */
130 struct image *image; /* [ OW] - image data */
131 enum image_format format; /* [R W] - file format (IMAGE_FORMAT_x) */
132 struct fastbuf *fastbuf; /* [R W] - source/destination stream */
133 struct mempool *pool; /* [ I ] - parameter to image_new */
134 u32 cols; /* [ HI ] - number of columns, parameter to image_new */
135 u32 rows; /* [ HI ] - number of rows, parameter to image_new */
136 u32 flags; /* [ HI ] - see enum image_io_flags */
137 u32 jpeg_quality; /* [ W] - JPEG compression quality (1..100) */
138 u32 number_of_colors; /* [ H ] - number of image colors */
139 struct color background_color; /* [ HI ] - background color, zero if undefined */
140 #ifdef CONFIG_IMAGES_EXIF
141 u32 exif_size; /* [ H W] - EXIF size in bytes (zero if not present) */
142 byte *exif_data; /* [ H W] - EXIF data */
146 struct image_context *context;
147 struct mempool *internal_pool;
149 void (*read_cancel)(struct image_io *io);
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 #ifdef CONFIG_IMAGES_EXIF
158 IMAGE_IO_WANT_EXIF = 0x80000, /* [R ] - read EXIF data if present */
162 int image_io_init(struct image_context *ctx, struct image_io *io);
163 void image_io_cleanup(struct image_io *io);
164 void image_io_reset(struct image_io *io);
166 int image_io_read_header(struct image_io *io);
167 struct image *image_io_read_data(struct image_io *io, int ref);
168 struct image *image_io_read(struct image_io *io, int ref);
170 int image_io_write(struct image_io *io);
172 byte *image_format_to_extension(enum image_format format);
173 enum image_format image_extension_to_format(byte *extension);
174 enum image_format image_file_name_to_format(byte *file_name);