13 Imager's per-thread context.
18 typedef struct im_context_tag *im_context_t;
24 Represents a slot in the context object.
29 typedef ptrdiff_t im_slot_t;
30 typedef void (*im_slot_destroy_t)(void *);
32 /* just so we can use our own input typemap */
33 typedef double im_double;
34 typedef float im_float;
36 /* used for palette indices in some internal code (which might be
39 typedef unsigned char i_palidx;
41 /* We handle 2 types of sample, this is hopefully the most common, and the
42 smaller of the ones we support */
43 typedef unsigned char i_sample_t;
45 typedef struct { i_sample_t gray_color; } gray_color;
46 typedef struct { i_sample_t r,g,b; } rgb_color;
47 typedef struct { i_sample_t r,g,b,a; } rgba_color;
48 typedef struct { i_sample_t c,m,y,k; } cmyk_color;
50 typedef int undef_int; /* special value to put in typemaps to retun undef on 0 and 1 on 1 */
55 =synopsis i_img_dim x, y;
58 A signed integer type that represents an image dimension or ordinate.
60 May be larger than int on some platforms.
65 typedef ptrdiff_t i_img_dim;
70 =synopsis i_img_dim_u limit;
73 An unsigned variant of L</i_img_dim>.
78 typedef size_t i_img_dim_u;
80 #define i_img_dim_MAX ((i_img_dim)(~(i_img_dim_u)0 >> 1))
85 =synopsis i_color black;
86 =synopsis black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
88 Type for 8-bit/sample color.
94 i_color is a union of:
100 gray - contains a single element gray_color, eg. C<c.gray.gray_color>
104 C<rgb> - contains three elements C<r>, C<g>, C<b>, eg. C<c.rgb.r>
108 C<rgba> - contains four elements C<r>, C<g>, C<b>, C<a>, eg. C<c.rgba.a>
112 C<cmyk> - contains four elements C<c>, C<m>, C<y>, C<k>,
113 eg. C<c.cmyk.y>. Note that Imager never uses CMYK colors except when
114 reading/writing files.
118 channels - an array of four channels, eg C<c.channels[2]>.
130 i_sample_t channel[MAXCHANNELS];
134 /* this is the larger sample type, it should be able to accurately represent
135 any sample size we use */
136 typedef double i_fsample_t;
138 typedef struct { i_fsample_t gray_color; } i_fgray_color_t;
139 typedef struct { i_fsample_t r, g, b; } i_frgb_color_t;
140 typedef struct { i_fsample_t r, g, b, a; } i_frgba_color_t;
141 typedef struct { i_fsample_t c, m, y, k; } i_fcmyk_color_t;
147 This is the double/sample color type.
149 Its layout exactly corresponds to i_color.
155 i_fgray_color_t gray;
157 i_frgba_color_t rgba;
158 i_fcmyk_color_t cmyk;
159 i_fsample_t channel[MAXCHANNELS];
163 i_direct_type, /* direct colour, keeps RGB values per pixel */
164 i_palette_type /* keeps a palette index per pixel */
168 /* bits per sample, not per pixel */
169 /* a paletted image might have one bit per sample */
172 i_double_bits = sizeof(double) * 8
176 char *name; /* name of a given tag, might be NULL */
177 int code; /* number of a given tag, -1 if it has no meaning */
178 char *data; /* value of a given tag if it's not an int, may be NULL */
179 int size; /* size of the data */
180 int idata; /* value of a given tag if data is NULL */
184 int count; /* how many tags have been set */
185 int alloc; /* how many tags have been allocated for */
189 typedef struct i_img_ i_img;
190 typedef int (*i_f_ppix_t)(i_img *im, i_img_dim x, i_img_dim y, const i_color *pix);
191 typedef int (*i_f_ppixf_t)(i_img *im, i_img_dim x, i_img_dim y, const i_fcolor *pix);
192 typedef i_img_dim (*i_f_plin_t)(i_img *im, i_img_dim x, i_img_dim r, i_img_dim y, const i_color *vals);
193 typedef i_img_dim (*i_f_plinf_t)(i_img *im, i_img_dim x, i_img_dim r, i_img_dim y, const i_fcolor *vals);
194 typedef int (*i_f_gpix_t)(i_img *im, i_img_dim x, i_img_dim y, i_color *pix);
195 typedef int (*i_f_gpixf_t)(i_img *im, i_img_dim x, i_img_dim y, i_fcolor *pix);
196 typedef i_img_dim (*i_f_glin_t)(i_img *im, i_img_dim x, i_img_dim r, i_img_dim y, i_color *vals);
197 typedef i_img_dim (*i_f_glinf_t)(i_img *im, i_img_dim x, i_img_dim r, i_img_dim y, i_fcolor *vals);
199 typedef i_img_dim (*i_f_gsamp_t)(i_img *im, i_img_dim x, i_img_dim r, i_img_dim y, i_sample_t *samp,
200 const int *chans, int chan_count);
201 typedef i_img_dim (*i_f_gsampf_t)(i_img *im, i_img_dim x, i_img_dim r, i_img_dim y, i_fsample_t *samp,
202 const int *chan, int chan_count);
204 typedef i_img_dim (*i_f_gpal_t)(i_img *im, i_img_dim x, i_img_dim r, i_img_dim y, i_palidx *vals);
205 typedef i_img_dim (*i_f_ppal_t)(i_img *im, i_img_dim x, i_img_dim r, i_img_dim y, const i_palidx *vals);
206 typedef int (*i_f_addcolors_t)(i_img *im, const i_color *colors, int count);
207 typedef int (*i_f_getcolors_t)(i_img *im, int i, i_color *, int count);
208 typedef int (*i_f_colorcount_t)(i_img *im);
209 typedef int (*i_f_maxcolors_t)(i_img *im);
210 typedef int (*i_f_findcolor_t)(i_img *im, const i_color *color, i_palidx *entry);
211 typedef int (*i_f_setcolors_t)(i_img *im, int index, const i_color *colors,
214 typedef void (*i_f_destroy_t)(i_img *im);
216 typedef i_img_dim (*i_f_gsamp_bits_t)(i_img *im, i_img_dim x, i_img_dim r, i_img_dim y, unsigned *samp,
217 const int *chans, int chan_count, int bits);
218 typedef i_img_dim (*i_f_psamp_bits_t)(i_img *im, i_img_dim x, i_img_dim r, i_img_dim y, unsigned const *samp,
219 const int *chans, int chan_count, int bits);
221 (*i_f_psamp_t)(i_img *im, i_img_dim x, i_img_dim r, i_img_dim y,
222 const i_sample_t *samp, const int *chan, int chan_count);
224 (*i_f_psampf_t)(i_img *im, i_img_dim x, i_img_dim r, i_img_dim y,
225 const i_fsample_t *samp, const int *chan, int chan_count);
230 =synopsis i_img *img;
233 This is Imager's image type.
235 It contains the following members:
241 C<channels> - the number of channels in the image
245 C<xsize>, C<ysize> - the width and height of the image in pixels
249 C<bytes> - the number of bytes used to store the image data. Undefined
250 where virtual is non-zero.
254 C<ch_mask> - a mask of writable channels. eg. if this is 6 then only
255 channels 1 and 2 are writable. There may be bits set for which there
256 are no channels in the image.
260 C<bits> - the number of bits stored per sample. Should be one of
261 i_8_bits, i_16_bits, i_double_bits.
265 C<type> - either i_direct_type for direct color images, or i_palette_type
270 C<virtual> - if zero then this image is-self contained. If non-zero
271 then this image could be an interface to some other implementation.
275 C<idata> - the image data. This should not be directly accessed. A new
276 image implementation can use this to store its image data.
277 i_img_destroy() will myfree() this pointer if it's non-null.
281 C<tags> - a structure storing the image's tags. This should only be
282 accessed via the i_tags_*() functions.
286 C<ext_data> - a pointer for use internal to an image implementation.
287 This should be freed by the image's destroy handler.
291 C<im_data> - data internal to Imager. This is initialized by
296 i_f_ppix, i_f_ppixf, i_f_plin, i_f_plinf, i_f_gpix, i_f_gpixf,
297 i_f_glin, i_f_glinf, i_f_gsamp, i_f_gampf - implementations for each
298 of the required image functions. An image implementation should
299 initialize these between calling i_img_alloc() and i_img_init().
303 i_f_gpal, i_f_ppal, i_f_addcolors, i_f_getcolors, i_f_colorcount,
304 i_f_maxcolors, i_f_findcolor, i_f_setcolors - implementations for each
305 paletted image function.
309 i_f_destroy - custom image destruction function. This should be used
310 to release memory if necessary.
314 i_f_gsamp_bits - implements i_gsamp_bits() for this image.
318 i_f_psamp_bits - implements i_psamp_bits() for this image.
322 i_f_psamp - implements psamp() for this image.
326 i_f_psampf - implements psamp() for this image.
330 C<im_data> - image specific data internal to Imager.
334 C<context> - the Imager API context this image belongs to.
343 i_img_dim xsize,ysize;
345 unsigned int ch_mask;
348 int virtual; /* image might not keep any data, must use functions */
349 unsigned char *idata; /* renamed to force inspection of existing code */
350 /* can be NULL if virtual is non-zero */
355 /* interface functions */
357 i_f_ppixf_t i_f_ppixf;
359 i_f_plinf_t i_f_plinf;
361 i_f_gpixf_t i_f_gpixf;
363 i_f_glinf_t i_f_glinf;
364 i_f_gsamp_t i_f_gsamp;
365 i_f_gsampf_t i_f_gsampf;
367 /* only valid for type == i_palette_type */
370 i_f_addcolors_t i_f_addcolors;
371 i_f_getcolors_t i_f_getcolors;
372 i_f_colorcount_t i_f_colorcount;
373 i_f_maxcolors_t i_f_maxcolors;
374 i_f_findcolor_t i_f_findcolor;
375 i_f_setcolors_t i_f_setcolors;
377 i_f_destroy_t i_f_destroy;
380 i_f_gsamp_bits_t i_f_gsamp_bits;
381 i_f_psamp_bits_t i_f_psamp_bits;
384 i_f_psamp_t i_f_psamp;
385 i_f_psampf_t i_f_psampf;
390 im_context_t context;
393 /* ext_data for paletted images
396 int count; /* amount of space used in palette (in entries) */
397 int alloc; /* amount of space allocated for palette (in entries) */
403 The types in here so far are:
405 doubly linked bucket list - pretty efficient
406 octtree - no idea about goodness
415 i_img_dim xsize,ysize;
419 struct i_bitmap* btm_new(i_img_dim xsize,i_img_dim ysize);
420 void btm_destroy(struct i_bitmap *btm);
421 int btm_test(struct i_bitmap *btm,i_img_dim x,i_img_dim y);
422 void btm_set(struct i_bitmap *btm,i_img_dim x,i_img_dim y);
425 /* Stack/Linked list */
430 int fill; /* Number used in this link */
435 int multip; /* # of copies in a single chain */
436 size_t ssize; /* size of each small element */
437 int count; /* number of elements on the list */
443 struct llist *llist_new( int multip, size_t ssize );
444 void llist_destroy( struct llist *l );
445 void llist_push( struct llist *l, const void *data );
446 void llist_dump( struct llist *l );
447 int llist_pop( struct llist *l,void *data );
459 struct octt *octt_new(void);
460 int octt_add(struct octt *ct,unsigned char r,unsigned char g,unsigned char b);
461 void octt_dump(struct octt *ct);
462 void octt_count(struct octt *ct,int *tot,int max,int *overflow);
463 void octt_delete(struct octt *ct);
464 void octt_histo(struct octt *ct, unsigned int **col_usage_it_adr);
466 /* font bounding box results */
467 enum bounding_box_index_t {
483 Represents a polygon. Has the following members:
489 C<x>, C<y> - arrays of x and y locations of vertices.
493 C<count> - the number of entries in the C<x> and C<y> arrays.
500 typedef struct i_polygon_tag {
507 =item i_poly_fill_mode_t
510 Control how polygons are filled. Has the following values:
516 C<i_pfm_evenodd> - simple even-odd fills.
520 C<i_pfm_nonzero> - non-zero winding rule fills.
527 typedef enum i_poly_fill_mode_tag {
530 } i_poly_fill_mode_t;
535 typedef void (*i_fill_with_color_f)
536 (struct i_fill_tag *fill, i_img_dim x, i_img_dim y, i_img_dim width, int channels,
538 typedef void (*i_fill_with_fcolor_f)
539 (struct i_fill_tag *fill, i_img_dim x, i_img_dim y, i_img_dim width, int channels,
541 typedef void (*i_fill_destroy_f)(struct i_fill_tag *fill);
543 /* combine functions modify their target and are permitted to modify
544 the source to prevent having to perform extra copying/memory
546 The out array has I<channels> channels.
548 The in array has I<channels> channels + an alpha channel if one
549 isn't included in I<channels>.
552 typedef void (*i_fill_combine_f)(i_color *out, i_color *in, int channels,
554 typedef void (*i_fill_combinef_f)(i_fcolor *out, i_fcolor *in, int channels,
557 /* fountain fill types */
565 } i_fountain_seg_type;
573 double start, middle, end;
575 i_fountain_seg_type type;
576 i_fountain_color color;
604 =synopsis i_fill_t *fill;
606 This is the "abstract" base type for Imager's fill types.
608 Unless you're implementing a new fill type you'll typically treat this
614 typedef struct i_fill_tag
616 /* called for 8-bit/sample image (and maybe lower) */
617 /* this may be NULL, if so call fill_with_fcolor */
618 i_fill_with_color_f f_fill_with_color;
620 /* called for other sample sizes */
621 /* this must be non-NULL */
622 i_fill_with_fcolor_f f_fill_with_fcolor;
624 /* called if non-NULL to release any extra resources */
625 i_fill_destroy_f destroy;
627 /* if non-zero the caller will fill data with the original data
629 i_fill_combine_f combine;
630 i_fill_combinef_f combinef;
653 =synopsis i_mutex_t mutex;
655 Opaque type for Imager's mutex API.
659 typedef struct i_mutex_tag *i_mutex_t;
662 describes an axis of a MM font.
663 Modelled on FT2's FT_MM_Axis.
664 It would be nice to have a default entry too, but FT2
667 typedef struct i_font_mm_axis_tag {
673 #define IM_FONT_MM_MAX_AXES 4
676 multiple master information for a font, if any
677 modelled on FT2's FT_Multi_Master.
679 typedef struct i_font_mm_tag {
681 int num_designs; /* provided but not necessarily useful */
682 i_font_mm_axis axis[IM_FONT_MM_MAX_AXES];
687 struct TT_Fonthandle_;
689 typedef struct TT_Fonthandle_ TT_Fonthandle;
697 An enumerated type for controlling how transparency is handled during
700 This has the following possible values:
706 C<tr_none> - ignore the alpha channel
710 C<tr_threshold> - simple transparency thresholding.
714 C<tr_errdiff> - use error diffusion to control which pixels are
719 C<tr_ordered> - use ordered dithering to control which pixels are
727 /* transparency handling for quantized output */
728 typedef enum i_transp_tag {
729 tr_none, /* ignore any alpha channel */
730 tr_threshold, /* threshold the transparency - uses tr_threshold */
731 tr_errdiff, /* error diffusion */
732 tr_ordered /* an ordered dither */
739 An enumerated type used to control the method used for produce the
746 C<mc_none> - the user supplied map is used.
750 C<mc_web_map> - use the classic web map. Any existing fixed colors
755 C<mc_median_cut> - use median cut
759 C<mono> - use a fixed black and white map.
763 C<gray> - 256 step gray map.
767 C<gray4> - 4 step gray map.
771 C<gray16> - 16 step gray map.
778 typedef enum i_make_colors_tag {
779 mc_none, /* user supplied colour map only */
780 mc_web_map, /* Use the 216 colour web colour map */
781 mc_addi, /* Addi's algorithm */
782 mc_median_cut, /* median cut - similar to giflib, hopefully */
783 mc_mono, /* fixed mono color map */
784 mc_gray, /* 256 gray map */
785 mc_gray4, /* four step gray map */
786 mc_gray16, /* sixteen step gray map */
787 mc_mask = 0xFF /* (mask for generator) */
794 An enumerated type that controls how colors are translated:
800 C<pt_giflib> - obsolete, forces C<make_colors> to use median cut and
801 acts like C<pt_closest>.
805 C<pt_closest> - always use the closest color.
809 C<pt_perturb> - add random values to each sample and find the closest
814 C<pt_errdiff> - error diffusion dither.
821 /* controls how we translate the colours */
822 typedef enum i_translate_tag {
823 pt_giflib, /* get gif lib to do it (ignores make_colours) */
824 pt_closest, /* just use the closest match within the hashbox */
825 pt_perturb, /* randomly perturb the data - uses perturb_size*/
826 pt_errdiff /* error diffusion dither - uses errdiff */
833 Controls the type of error diffusion to use:
839 C<ed_floyd> - floyd-steinberg
843 C<ed_jarvis> - Jarvis, Judice and Ninke
847 C<ed_stucki> - Stucki
851 C<ed_custom> - not usable for transparency dithering, allows a custom
852 error diffusion map to be used.
856 C<ed_bidir> - or with the error diffusion type to use alternate
857 directions on each line of the dither.
864 /* Which error diffusion map to use */
865 typedef enum i_errdiff_tag {
866 ed_floyd, /* floyd-steinberg */
867 ed_jarvis, /* Jarvis, Judice and Ninke */
868 ed_stucki, /* Stucki */
869 ed_custom, /* the map found in ed_map|width|height|orig */
870 ed_mask = 0xFF, /* mask to get the map */
871 ed_bidir = 0x100 /* change direction for each row */
878 Which ordered dither map to use, currently only available for
879 transparency. Values are:
885 C<od_random> - a pre-generated random map.
889 C<od_dot8> - large dot dither.
893 C<od_dot4> - smaller dot dither
897 C<od_hline> - horizontal line dither.
901 C<od_vline> - vertical line dither.
905 C<od_slashline> - C</> line dither.
909 C<od_backline> - C<\> line dither.
913 C<od_tiny> - small checkbox dither
917 C<od_custom> - custom dither map.
923 I don't know of a way to do ordered dither of an image against some
926 typedef enum i_ord_dith_tag
928 od_random, /* sort of random */
929 od_dot8, /* large dot */
933 od_slashline, /* / line dither */
934 od_backline, /* \ line dither */
935 od_tiny, /* small checkerbox */
936 od_custom /* custom 8x8 map */
943 A structure type used to supply image quantization, ie. when
944 converting a direct color image to a paletted image.
946 This has the following members:
952 C<transp> - how to handle transparency, see L</i_transp>.
956 C<threshold> - when C<transp> is C<tr_threshold>, this is the alpha
957 level at which pixels become transparent.
961 C<tr_errdiff> - when C<transp> is C<tr_errdiff> this controls the type
962 of error diffusion to be done. This may not be C<ed_custom> for this
967 C<tr_orddith> - when C<transp> is C<tr_ordered> this controls the
968 patten used for dithering transparency.
972 C<tr_custom> - when C<tr_orddith> is C<tr_custom> this is the ordered
977 C<make_colors> - the method used to generate the color palette, see
982 C<mc_colors> - an array of C<mc_size> L</i_color> entries used to
983 define the fixed colors (controlled by C<mc_count> and to return the
984 generated color list.
988 C<mc_size> - the size of the buffer allocated to C<mc_colors> in
989 C<sizeof(i_color)> units.
993 C<mc_count> - the number of initialized colors in C<mc_colors>.
997 C<translate> - how RGB colors are translated to palette indexes, see
1002 C<errdiff> - when C<translate> is C<pt_errdiff> this controls the type
1003 of error diffusion to be done.
1007 C<ed_map>, C<ed_width>, C<ed_height>, C<ed_orig> - when C<errdiff> is
1008 C<ed_custom> this controls the error diffusion map. C<ed_map> is an
1009 array of C<ed_width * ed_height> integers. C<ed_orig> is the position
1010 of the current pixel in the error diffusion map, always on the top
1015 C<perturb> - the amount to perturb pixels when C<translate> is
1022 typedef struct i_quantize_tag {
1025 /* how to handle transparency */
1027 /* the threshold at which to make pixels opaque */
1029 i_errdiff tr_errdiff;
1030 i_ord_dith tr_orddith;
1031 unsigned char tr_custom[64];
1033 /* how to make the colour map */
1034 i_make_colors make_colors;
1036 /* any existing colours
1037 mc_existing is an existing colour table
1038 mc_count is the number of existing colours
1039 mc_size is the total size of the array that mc_existing points
1040 at - this must be at least 256
1046 /* how we translate the colours */
1047 i_translate translate;
1049 /* the error diffusion map to use if translate is mc_errdiff */
1051 /* the following define the error diffusion values to use if
1052 errdiff is ed_custom. ed_orig is the column on the top row that
1053 represents the current
1056 int ed_width, ed_height, ed_orig;
1058 /* the amount of perturbation to use for translate is mc_perturb */
1060 /* version 2 members after here */
1063 /* distance measures used by some filters */
1065 i_dmeasure_euclidean = 0,
1066 i_dmeasure_euclidean_squared = 1,
1067 i_dmeasure_manhatten = 2,
1068 i_dmeasure_limit = 2,
1071 #include "iolayert.h"
1073 /* error message information returned by im_errors() */
1080 typedef struct i_render_tag i_render;
1083 =item i_color_model_t
1084 =category Data Types
1087 Returned by L</i_img_color_model(im)> to indicate the color model of
1090 An enumerated type with the following possible values:
1096 C<icm_unknown> - the image has no usable color data. In future
1097 versions of Imager this will be returned in a few limited cases,
1098 eg. when the source image is CMYK and the user has requested no color
1099 translation is done.
1103 C<icm_gray> - gray scale with no alpha channel.
1107 C<icm_gray_alpha> - gray scale with an alpha channel.
1115 C<icm_rgb_alpha> - RGB with an alpha channel.
1130 #ifdef IMAGER_FORMAT_ATTR
1131 #define I_FORMAT_ATTR(format_index, va_index) \
1132 __attribute ((format (printf, format_index, va_index)))
1134 #define I_FORMAT_ATTR(format_index, va_index)
1139 # define vsnprintf _vsnprintf
1142 # define snprintf _snprintf
1148 =category Data Types
1149 =synopsis printf("left %" i_DF "\n", i_DFc(x));
1152 This is a constant string that can be used with functions like
1153 printf() to format i_img_dim values after they're been cast with i_DFc().
1155 Does not include the leading C<%>.
1160 =category Data Types
1163 Cast an C<i_img_dim> value to a type for use with the i_DF format
1169 =category Data Types
1170 =synopsis printf("point (" i_DFp ")\n", i_DFcp(x, y));
1173 Format a pair of C<i_img_dim> values. This format string I<does>
1174 include the leading C<%>.
1179 =category Data Types
1182 Casts two C<i_img_dim> values for use with the i_DF (or i_DFp) format.
1187 #define i_DFc(x) ((i_dim_format_t)(x))
1188 #define i_DFcp(x, y) i_DFc(x), i_DFc(y)
1189 #define i_DFp "%" i_DF ", %" i_DF