avoid ignoring the result of i_io_getc()
[imager.git] / imdatatypes.h
1 #ifndef _DATATYPES_H_
2 #define _DATATYPES_H_
3
4 #include <stddef.h>
5 #include "imconfig.h"
6
7 #define MAXCHANNELS 4
8
9 /*
10 =item im_context_t
11 =category Data Types
12
13 Imager's per-thread context.
14
15 =cut
16 */
17
18 typedef struct im_context_tag *im_context_t;
19
20 /*
21 =item im_slot_t
22 =category Data Types
23
24 Represents a slot in the context object.
25
26 =cut
27 */
28
29 typedef ptrdiff_t im_slot_t;
30 typedef void (*im_slot_destroy_t)(void *);
31
32 /* used for palette indices in some internal code (which might be 
33    exposed at some point
34 */
35 typedef unsigned char i_palidx;
36
37 /* We handle 2 types of sample, this is hopefully the most common, and the
38    smaller of the ones we support */
39 typedef unsigned char i_sample_t;
40
41 typedef struct { i_sample_t gray_color; } gray_color;
42 typedef struct { i_sample_t r,g,b; } rgb_color;
43 typedef struct { i_sample_t r,g,b,a; } rgba_color;
44 typedef struct { i_sample_t c,m,y,k; } cmyk_color;
45
46 typedef int undef_int; /* special value to put in typemaps to retun undef on 0 and 1 on 1 */
47
48 /*
49 =item i_img_dim
50 =category Data Types
51 =synopsis i_img_dim x, y;
52 =order 90
53
54 A signed integer type that represents an image dimension or ordinate.
55
56 May be larger than int on some platforms.
57
58 =cut
59 */
60
61 typedef ptrdiff_t i_img_dim;
62
63 /*
64 =item i_img_dim_u
65 =category Data Types
66 =synopsis i_img_dim_u limit;
67 =order 90
68
69 An unsigned variant of L</i_img_dim>.
70
71 =cut
72 */
73
74 typedef size_t i_img_dim_u;
75
76 #define i_img_dim_MAX ((i_img_dim)(~(i_img_dim_u)0 >> 1))
77
78 /*
79 =item i_color
80 =category Data Types
81 =synopsis i_color black;
82 =synopsis black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0;
83
84 Type for 8-bit/sample color.
85
86 Samples as per;
87
88   i_color c;
89
90 i_color is a union of:
91
92 =over
93
94 =item *
95
96 gray - contains a single element gray_color, eg. C<c.gray.gray_color>
97
98 =item *
99
100 C<rgb> - contains three elements C<r>, C<g>, C<b>, eg. C<c.rgb.r>
101
102 =item *
103
104 C<rgba> - contains four elements C<r>, C<g>, C<b>, C<a>, eg. C<c.rgba.a>
105
106 =item *
107
108 C<cmyk> - contains four elements C<c>, C<m>, C<y>, C<k>,
109 eg. C<c.cmyk.y>.  Note that Imager never uses CMYK colors except when
110 reading/writing files.
111
112 =item *
113
114 channels - an array of four channels, eg C<c.channels[2]>.
115
116 =back
117
118 =cut
119 */
120
121 typedef union {
122   gray_color gray;
123   rgb_color rgb;
124   rgba_color rgba;
125   cmyk_color cmyk;
126   i_sample_t channel[MAXCHANNELS];
127   unsigned int ui;
128 } i_color;
129
130 /* this is the larger sample type, it should be able to accurately represent
131    any sample size we use */
132 typedef double i_fsample_t;
133
134 typedef struct { i_fsample_t gray_color; } i_fgray_color_t;
135 typedef struct { i_fsample_t r, g, b; } i_frgb_color_t;
136 typedef struct { i_fsample_t r, g, b, a; } i_frgba_color_t;
137 typedef struct { i_fsample_t c, m, y, k; } i_fcmyk_color_t;
138
139 /*
140 =item i_fcolor
141 =category Data Types
142
143 This is the double/sample color type.
144
145 Its layout exactly corresponds to i_color.
146
147 =cut
148 */
149
150 typedef union {
151   i_fgray_color_t gray;
152   i_frgb_color_t rgb;
153   i_frgba_color_t rgba;
154   i_fcmyk_color_t cmyk;
155   i_fsample_t channel[MAXCHANNELS];
156 } i_fcolor;
157
158 typedef enum {
159   i_direct_type, /* direct colour, keeps RGB values per pixel */
160   i_palette_type /* keeps a palette index per pixel */
161 } i_img_type_t;
162
163 typedef enum { 
164   /* bits per sample, not per pixel */
165   /* a paletted image might have one bit per sample */
166   i_8_bits = 8,
167   i_16_bits = 16,
168   i_double_bits = sizeof(double) * 8
169 } i_img_bits_t;
170
171 typedef struct {
172   char *name; /* name of a given tag, might be NULL */
173   int code; /* number of a given tag, -1 if it has no meaning */
174   char *data; /* value of a given tag if it's not an int, may be NULL */
175   int size; /* size of the data */
176   int idata; /* value of a given tag if data is NULL */
177 } i_img_tag;
178
179 typedef struct {
180   int count; /* how many tags have been set */
181   int alloc; /* how many tags have been allocated for */
182   i_img_tag *tags;
183 } i_img_tags;
184
185 typedef struct i_img_ i_img;
186 typedef int (*i_f_ppix_t)(i_img *im, i_img_dim x, i_img_dim y, const i_color *pix);
187 typedef int (*i_f_ppixf_t)(i_img *im, i_img_dim x, i_img_dim y, const i_fcolor *pix);
188 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);
189 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);
190 typedef int (*i_f_gpix_t)(i_img *im, i_img_dim x, i_img_dim y, i_color *pix);
191 typedef int (*i_f_gpixf_t)(i_img *im, i_img_dim x, i_img_dim y, i_fcolor *pix);
192 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);
193 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);
194
195 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,
196                            const int *chans, int chan_count);
197 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,
198                             const int *chan, int chan_count);
199
200 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);
201 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);
202 typedef int (*i_f_addcolors_t)(i_img *im, const i_color *colors, int count);
203 typedef int (*i_f_getcolors_t)(i_img *im, int i, i_color *, int count);
204 typedef int (*i_f_colorcount_t)(i_img *im);
205 typedef int (*i_f_maxcolors_t)(i_img *im);
206 typedef int (*i_f_findcolor_t)(i_img *im, const i_color *color, i_palidx *entry);
207 typedef int (*i_f_setcolors_t)(i_img *im, int index, const i_color *colors, 
208                               int count);
209
210 typedef void (*i_f_destroy_t)(i_img *im);
211
212 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,
213                            const int *chans, int chan_count, int bits);
214 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,
215                                  const int *chans, int chan_count, int bits);
216 typedef i_img_dim
217 (*i_f_psamp_t)(i_img *im, i_img_dim x, i_img_dim r, i_img_dim y, 
218                 const i_sample_t *samp, const int *chan, int chan_count);
219 typedef i_img_dim
220 (*i_f_psampf_t)(i_img *im, i_img_dim x, i_img_dim r, i_img_dim y,
221                 const i_fsample_t *samp, const int *chan, int chan_count);
222
223 /*
224 =item i_img
225 =category Data Types
226 =synopsis i_img *img;
227 =order 10
228
229 This is Imager's image type.
230
231 It contains the following members:
232
233 =over
234
235 =item *
236
237 C<channels> - the number of channels in the image
238
239 =item *
240
241 C<xsize>, C<ysize> - the width and height of the image in pixels
242
243 =item *
244
245 C<bytes> - the number of bytes used to store the image data.  Undefined
246 where virtual is non-zero.
247
248 =item *
249
250 C<ch_mask> - a mask of writable channels.  eg. if this is 6 then only
251 channels 1 and 2 are writable.  There may be bits set for which there
252 are no channels in the image.
253
254 =item *
255
256 C<bits> - the number of bits stored per sample.  Should be one of
257 i_8_bits, i_16_bits, i_double_bits.
258
259 =item *
260
261 C<type> - either i_direct_type for direct color images, or i_palette_type
262 for paletted images.
263
264 =item *
265
266 C<virtual> - if zero then this image is-self contained.  If non-zero
267 then this image could be an interface to some other implementation.
268
269 =item *
270
271 C<idata> - the image data.  This should not be directly accessed.  A new
272 image implementation can use this to store its image data.
273 i_img_destroy() will myfree() this pointer if it's non-null.
274
275 =item *
276
277 C<tags> - a structure storing the image's tags.  This should only be
278 accessed via the i_tags_*() functions.
279
280 =item *
281
282 C<ext_data> - a pointer for use internal to an image implementation.
283 This should be freed by the image's destroy handler.
284
285 =item *
286
287 C<im_data> - data internal to Imager.  This is initialized by
288 i_img_init().
289
290 =item *
291
292 i_f_ppix, i_f_ppixf, i_f_plin, i_f_plinf, i_f_gpix, i_f_gpixf,
293 i_f_glin, i_f_glinf, i_f_gsamp, i_f_gampf - implementations for each
294 of the required image functions.  An image implementation should
295 initialize these between calling i_img_alloc() and i_img_init().
296
297 =item *
298
299 i_f_gpal, i_f_ppal, i_f_addcolors, i_f_getcolors, i_f_colorcount,
300 i_f_maxcolors, i_f_findcolor, i_f_setcolors - implementations for each
301 paletted image function.
302
303 =item *
304
305 i_f_destroy - custom image destruction function.  This should be used
306 to release memory if necessary.
307
308 =item *
309
310 i_f_gsamp_bits - implements i_gsamp_bits() for this image.
311
312 =item *
313
314 i_f_psamp_bits - implements i_psamp_bits() for this image.
315
316 =item *
317
318 i_f_psamp - implements psamp() for this image.
319
320 =item *
321
322 i_f_psampf - implements psamp() for this image.
323
324 =item *
325
326 C<im_data> - image specific data internal to Imager.
327
328 =item *
329
330 C<context> - the Imager API context this image belongs to.
331
332 =back
333
334 =cut
335 */
336
337 struct i_img_ {
338   int channels;
339   i_img_dim xsize,ysize;
340   size_t bytes;
341   unsigned int ch_mask;
342   i_img_bits_t bits;
343   i_img_type_t type;
344   int virtual; /* image might not keep any data, must use functions */
345   unsigned char *idata; /* renamed to force inspection of existing code */
346                         /* can be NULL if virtual is non-zero */
347   i_img_tags tags;
348
349   void *ext_data;
350
351   /* interface functions */
352   i_f_ppix_t i_f_ppix;
353   i_f_ppixf_t i_f_ppixf;
354   i_f_plin_t i_f_plin;
355   i_f_plinf_t i_f_plinf;
356   i_f_gpix_t i_f_gpix;
357   i_f_gpixf_t i_f_gpixf;
358   i_f_glin_t i_f_glin;
359   i_f_glinf_t i_f_glinf;
360   i_f_gsamp_t i_f_gsamp;
361   i_f_gsampf_t i_f_gsampf;
362   
363   /* only valid for type == i_palette_type */
364   i_f_gpal_t i_f_gpal;
365   i_f_ppal_t i_f_ppal;
366   i_f_addcolors_t i_f_addcolors;
367   i_f_getcolors_t i_f_getcolors;
368   i_f_colorcount_t i_f_colorcount;
369   i_f_maxcolors_t i_f_maxcolors;
370   i_f_findcolor_t i_f_findcolor;
371   i_f_setcolors_t i_f_setcolors;
372
373   i_f_destroy_t i_f_destroy;
374
375   /* as of 0.61 */
376   i_f_gsamp_bits_t i_f_gsamp_bits;
377   i_f_psamp_bits_t i_f_psamp_bits;
378
379   /* as of 0.88 */
380   i_f_psamp_t i_f_psamp;
381   i_f_psampf_t i_f_psampf;
382
383   void *im_data;
384
385   /* 0.91 */
386   im_context_t context;
387 };
388
389 /* ext_data for paletted images
390  */
391 typedef struct {
392   int count; /* amount of space used in palette (in entries) */
393   int alloc; /* amount of space allocated for palette (in entries) */
394   i_color *pal;
395   int last_found;
396 } i_img_pal_ext;
397
398 /* Helper datatypes
399   The types in here so far are:
400
401   doubly linked bucket list - pretty efficient
402   octtree - no idea about goodness
403   
404   needed: hashes.
405
406 */
407
408 /* bitmap mask */
409
410 struct i_bitmap {
411   i_img_dim xsize,ysize;
412   char *data;
413 };
414
415 struct i_bitmap* btm_new(i_img_dim xsize,i_img_dim ysize);
416 void btm_destroy(struct i_bitmap *btm);
417 int btm_test(struct i_bitmap *btm,i_img_dim x,i_img_dim y);
418 void btm_set(struct i_bitmap *btm,i_img_dim x,i_img_dim y);
419
420
421 /* Stack/Linked list */
422
423 struct llink {
424   struct llink *p,*n;
425   void *data;
426   int fill;             /* Number used in this link */
427 };
428
429 struct llist {
430   struct llink *h,*t;
431   int multip;           /* # of copies in a single chain  */
432   size_t ssize;         /* size of each small element     */
433   int count;           /* number of elements on the list */
434 };
435
436
437 /* Lists */
438
439 struct llist *llist_new( int multip, size_t ssize );
440 void llist_destroy( struct llist *l );
441 void llist_push( struct llist *l, const void *data );
442 void llist_dump( struct llist *l );
443 int llist_pop( struct llist *l,void *data );
444
445
446
447
448 /* Octtree */
449
450 struct octt {
451   struct octt *t[8]; 
452   int cnt;
453 };
454
455 struct octt *octt_new(void);
456 int octt_add(struct octt *ct,unsigned char r,unsigned char g,unsigned char b);
457 void octt_dump(struct octt *ct);
458 void octt_count(struct octt *ct,int *tot,int max,int *overflow);
459 void octt_delete(struct octt *ct);
460 void octt_histo(struct octt *ct, unsigned int **col_usage_it_adr);
461
462 /* font bounding box results */
463 enum bounding_box_index_t {
464   BBOX_NEG_WIDTH,
465   BBOX_GLOBAL_DESCENT,
466   BBOX_POS_WIDTH,
467   BBOX_GLOBAL_ASCENT,
468   BBOX_DESCENT,
469   BBOX_ASCENT,
470   BBOX_ADVANCE_WIDTH,
471   BBOX_RIGHT_BEARING,
472   BOUNDING_BOX_COUNT
473 };
474
475 /*
476 =item i_polygon_t
477 =category Data Types
478
479 Represents a polygon.  Has the following members:
480
481 =over
482
483 =item *
484
485 C<x>, C<y> - arrays of x and y locations of vertices.
486
487 =item *
488
489 C<count> - the number of entries in the C<x> and C<y> arrays.
490
491 =back
492
493 =cut
494 */
495
496 typedef struct i_polygon_tag {
497   const double *x;
498   const double *y;
499   size_t count;
500 } i_polygon_t;
501
502 /*
503 =item i_poly_fill_mode_t
504 =category Data Types
505
506 Control how polygons are filled.  Has the following values:
507
508 =over
509
510 =item *
511
512 C<i_pfm_evenodd> - simple even-odd fills.
513
514 =item *
515
516 C<i_pfm_nonzero> - non-zero winding rule fills.
517
518 =back
519
520 =cut
521 */
522
523 typedef enum i_poly_fill_mode_tag {
524   i_pfm_evenodd,
525   i_pfm_nonzero
526 } i_poly_fill_mode_t;
527
528 /* Generic fills */
529 struct i_fill_tag;
530
531 typedef void (*i_fill_with_color_f)
532 (struct i_fill_tag *fill, i_img_dim x, i_img_dim y, i_img_dim width, int channels, 
533       i_color *data);
534 typedef void (*i_fill_with_fcolor_f)
535      (struct i_fill_tag *fill, i_img_dim x, i_img_dim y, i_img_dim width, int channels,
536       i_fcolor *data);
537 typedef void (*i_fill_destroy_f)(struct i_fill_tag *fill);
538
539 /* combine functions modify their target and are permitted to modify
540    the source to prevent having to perform extra copying/memory
541    allocations, etc
542    The out array has I<channels> channels.
543
544    The in array has I<channels> channels + an alpha channel if one
545    isn't included in I<channels>.
546 */
547
548 typedef void (*i_fill_combine_f)(i_color *out, i_color *in, int channels, 
549                                  i_img_dim count);
550 typedef void (*i_fill_combinef_f)(i_fcolor *out, i_fcolor *in, int channels,
551                                   i_img_dim count);
552
553 /* fountain fill types */
554 typedef enum {
555   i_fst_linear,
556   i_fst_curved,
557   i_fst_sine,
558   i_fst_sphere_up,
559   i_fst_sphere_down,
560   i_fst_end
561 } i_fountain_seg_type;
562 typedef enum {
563   i_fc_direct,
564   i_fc_hue_up,
565   i_fc_hue_down,
566   i_fc_end
567 } i_fountain_color;
568 typedef struct {
569   double start, middle, end;
570   i_fcolor c[2];
571   i_fountain_seg_type type;
572   i_fountain_color color;
573 } i_fountain_seg;
574 typedef enum {
575   i_fr_none,
576   i_fr_sawtooth,
577   i_fr_triangle,
578   i_fr_saw_both,
579   i_fr_tri_both
580 } i_fountain_repeat;
581 typedef enum {
582   i_ft_linear,
583   i_ft_bilinear,
584   i_ft_radial,
585   i_ft_radial_square,
586   i_ft_revolution,
587   i_ft_conical,
588   i_ft_end
589 } i_fountain_type;
590 typedef enum {
591   i_fts_none,
592   i_fts_grid,
593   i_fts_random,
594   i_fts_circle
595 } i_ft_supersample;
596
597 /*
598 =item i_fill_t
599 =category Data Types
600 =synopsis i_fill_t *fill;
601
602 This is the "abstract" base type for Imager's fill types.
603
604 Unless you're implementing a new fill type you'll typically treat this
605 as an opaque type.
606
607 =cut
608 */
609
610 typedef struct i_fill_tag
611 {
612   /* called for 8-bit/sample image (and maybe lower) */
613   /* this may be NULL, if so call fill_with_fcolor */
614   i_fill_with_color_f f_fill_with_color;
615
616   /* called for other sample sizes */
617   /* this must be non-NULL */
618   i_fill_with_fcolor_f f_fill_with_fcolor;
619
620   /* called if non-NULL to release any extra resources */
621   i_fill_destroy_f destroy;
622
623   /* if non-zero the caller will fill data with the original data
624      from the image */
625   i_fill_combine_f combine;
626   i_fill_combinef_f combinef;
627 } i_fill_t;
628
629 typedef enum {
630   ic_none,
631   ic_normal,
632   ic_multiply,
633   ic_dissolve,
634   ic_add,
635   ic_subtract,
636   ic_diff,
637   ic_lighten,
638   ic_darken,
639   ic_hue,
640   ic_sat,
641   ic_value,
642   ic_color
643 } i_combine_t;
644
645 /*
646 =item i_mutex_t
647 X<i_mutex>
648 =category mutex
649 =synopsis i_mutex_t mutex;
650
651 Opaque type for Imager's mutex API.
652
653 =cut
654  */
655 typedef struct i_mutex_tag *i_mutex_t;
656
657 /*
658    describes an axis of a MM font.
659    Modelled on FT2's FT_MM_Axis.
660    It would be nice to have a default entry too, but FT2 
661    doesn't support it.
662 */
663 typedef struct i_font_mm_axis_tag {
664   char const *name;
665   int minimum;
666   int maximum;
667 } i_font_mm_axis;
668
669 #define IM_FONT_MM_MAX_AXES 4
670
671 /* 
672    multiple master information for a font, if any 
673    modelled on FT2's FT_Multi_Master.
674 */
675 typedef struct i_font_mm_tag {
676   int num_axis;
677   int num_designs; /* provided but not necessarily useful */
678   i_font_mm_axis axis[IM_FONT_MM_MAX_AXES];
679 } i_font_mm;
680
681 #ifdef HAVE_LIBTT
682
683 struct TT_Fonthandle_;
684
685 typedef struct TT_Fonthandle_ TT_Fonthandle;
686
687 #endif
688
689 /*
690 =item i_transp
691 =category Data Types
692
693 An enumerated type for controlling how transparency is handled during
694 quantization.
695
696 This has the following possible values:
697
698 =over
699
700 =item *
701
702 C<tr_none> - ignore the alpha channel
703
704 =item *
705
706 C<tr_threshold> - simple transparency thresholding.
707
708 =item *
709
710 C<tr_errdiff> - use error diffusion to control which pixels are
711 transparent.
712
713 =item *
714
715 C<tr_ordered> - use ordered dithering to control which pixels are
716 transparent.
717
718 =back
719
720 =cut
721 */
722
723 /* transparency handling for quantized output */
724 typedef enum i_transp_tag {
725   tr_none, /* ignore any alpha channel */
726   tr_threshold, /* threshold the transparency - uses tr_threshold */
727   tr_errdiff, /* error diffusion */
728   tr_ordered /* an ordered dither */
729 } i_transp;
730
731 /*
732 =item i_make_colors
733 =category Data Types
734
735 An enumerated type used to control the method used for produce the
736 color map:
737
738 =over
739
740 =item *
741
742 C<mc_none> - the user supplied map is used.
743
744 =item *
745
746 C<mc_web_map> - use the classic web map.  Any existing fixed colors
747 are ignored.
748
749 =item *
750
751 C<mc_median_cut> - use median cut
752
753 =item *
754
755 C<mono> - use a fixed black and white map.
756
757 =item *
758
759 C<gray> - 256 step gray map.
760
761 =item *
762
763 C<gray4> - 4 step gray map.
764
765 =item *
766
767 C<gray16> - 16 step gray map.
768
769 =back
770
771 =cut
772 */
773
774 typedef enum i_make_colors_tag {
775   mc_none, /* user supplied colour map only */
776   mc_web_map, /* Use the 216 colour web colour map */
777   mc_addi, /* Addi's algorithm */
778   mc_median_cut, /* median cut - similar to giflib, hopefully */
779   mc_mono, /* fixed mono color map */
780   mc_gray, /* 256 gray map */
781   mc_gray4, /* four step gray map */
782   mc_gray16, /* sixteen step gray map */
783   mc_mask = 0xFF /* (mask for generator) */
784 } i_make_colors;
785
786 /*
787 =item i_translate
788 =category Data Types
789
790 An enumerated type that controls how colors are translated:
791
792 =over
793
794 =item *
795
796 C<pt_giflib> - obsolete, forces C<make_colors> to use median cut and
797 acts like C<pt_closest>.
798
799 =item *
800
801 C<pt_closest> - always use the closest color.
802
803 =item *
804
805 C<pt_perturb> - add random values to each sample and find the closest
806 color.
807
808 =item *
809
810 C<pt_errdiff> - error diffusion dither.
811
812 =back
813
814 =cut
815 */
816
817 /* controls how we translate the colours */
818 typedef enum i_translate_tag {
819   pt_giflib, /* get gif lib to do it (ignores make_colours) */
820   pt_closest, /* just use the closest match within the hashbox */
821   pt_perturb, /* randomly perturb the data - uses perturb_size*/
822   pt_errdiff /* error diffusion dither - uses errdiff */
823 } i_translate;
824
825 /*
826 =item i_errdiff
827 =category Data Types
828
829 Controls the type of error diffusion to use:
830
831 =over
832
833 =item *
834
835 C<ed_floyd> - floyd-steinberg
836
837 =item *
838
839 C<ed_jarvis> - Jarvis, Judice and Ninke 
840
841 =item *
842
843 C<ed_stucki> - Stucki
844
845 =item *
846
847 C<ed_custom> - not usable for transparency dithering, allows a custom
848 error diffusion map to be used.
849
850 =item *
851
852 C<ed_bidir> - or with the error diffusion type to use alternate
853 directions on each line of the dither.
854
855 =back
856
857 =cut
858 */
859
860 /* Which error diffusion map to use */
861 typedef enum i_errdiff_tag {
862   ed_floyd, /* floyd-steinberg */
863   ed_jarvis, /* Jarvis, Judice and Ninke */
864   ed_stucki, /* Stucki */
865   ed_custom, /* the map found in ed_map|width|height|orig */
866   ed_mask = 0xFF, /* mask to get the map */
867   ed_bidir = 0x100 /* change direction for each row */
868 } i_errdiff;
869
870 /*
871 =item i_ord_dith
872 =category Data Types
873
874 Which ordered dither map to use, currently only available for
875 transparency.  Values are:
876
877 =over
878
879 =item *
880
881 C<od_random> - a pre-generated random map.
882
883 =item *
884
885 C<od_dot8> - large dot dither.
886
887 =item *
888
889 C<od_dot4> - smaller dot dither
890
891 =item *
892
893 C<od_hline> - horizontal line dither.
894
895 =item *
896
897 C<od_vline> - vertical line dither.
898
899 =item *
900
901 C<od_slashline> - C</> line dither.
902
903 =item *
904
905 C<od_backline> - C<\> line dither.
906
907 =item *
908
909 C<od_tiny> - small checkbox dither
910
911 =item *
912
913 C<od_custom> - custom dither map.
914
915 =back
916
917 =cut
918
919    I don't know of a way to do ordered dither of an image against some 
920    general palette
921  */
922 typedef enum i_ord_dith_tag
923 {
924   od_random, /* sort of random */
925   od_dot8, /* large dot */
926   od_dot4,
927   od_hline,
928   od_vline,
929   od_slashline, /* / line dither */
930   od_backline, /* \ line dither */
931   od_tiny, /* small checkerbox */
932   od_custom /* custom 8x8 map */
933 } i_ord_dith;
934
935 /*
936 =item i_quantize
937 =category Data Types
938
939 A structure type used to supply image quantization, ie. when
940 converting a direct color image to a paletted image.
941
942 This has the following members:
943
944 =over
945
946 =item *
947
948 C<transp> - how to handle transparency, see L</i_transp>.
949
950 =item *
951
952 C<threshold> - when C<transp> is C<tr_threshold>, this is the alpha
953 level at which pixels become transparent.
954
955 =item *
956
957 C<tr_errdiff> - when C<transp> is C<tr_errdiff> this controls the type
958 of error diffusion to be done.  This may not be C<ed_custom> for this
959 member.
960
961 =item *
962
963 C<tr_orddith> - when C<transp> is C<tr_ordered> this controls the
964 patten used for dithering transparency.
965
966 =item *
967
968 C<tr_custom> - when C<tr_orddith> is C<tr_custom> this is the ordered
969 dither mask.
970
971 =item *
972
973 C<make_colors> - the method used to generate the color palette, see
974 L</i_make_colors>.
975
976 =item *
977
978 C<mc_colors> - an array of C<mc_size> L</i_color> entries used to
979 define the fixed colors (controlled by C<mc_count> and to return the
980 generated color list.
981
982 =item *
983
984 C<mc_size> - the size of the buffer allocated to C<mc_colors> in
985 C<sizeof(i_color)> units.
986
987 =item *
988
989 C<mc_count> - the number of initialized colors in C<mc_colors>.
990
991 =item *
992
993 C<translate> - how RGB colors are translated to palette indexes, see
994 L</i_translate>.
995
996 =item *
997
998 C<errdiff> - when C<translate> is C<pt_errdiff> this controls the type
999 of error diffusion to be done.
1000
1001 =item *
1002
1003 C<ed_map>, C<ed_width>, C<ed_height>, C<ed_orig> - when C<errdiff> is
1004 C<ed_custom> this controls the error diffusion map.  C<ed_map> is an
1005 array of C<ed_width * ed_height> integers.  C<ed_orig> is the position
1006 of the current pixel in the error diffusion map, always on the top
1007 row.
1008
1009 =item *
1010
1011 C<perturb> - the amount to perturb pixels when C<translate> is
1012 C<mc_perturb>.
1013
1014 =back
1015
1016 =cut
1017 */
1018 typedef struct i_quantize_tag {
1019   int version;
1020
1021   /* how to handle transparency */
1022   i_transp transp;
1023   /* the threshold at which to make pixels opaque */
1024   int tr_threshold;
1025   i_errdiff tr_errdiff;
1026   i_ord_dith tr_orddith;
1027   unsigned char tr_custom[64];
1028   
1029   /* how to make the colour map */
1030   i_make_colors make_colors;
1031
1032   /* any existing colours 
1033      mc_existing is an existing colour table
1034      mc_count is the number of existing colours
1035      mc_size is the total size of the array that mc_existing points
1036      at - this must be at least 256
1037   */
1038   i_color *mc_colors;
1039   int mc_size;
1040   int mc_count;
1041
1042   /* how we translate the colours */
1043   i_translate translate;
1044
1045   /* the error diffusion map to use if translate is mc_errdiff */
1046   i_errdiff errdiff;
1047   /* the following define the error diffusion values to use if 
1048      errdiff is ed_custom.  ed_orig is the column on the top row that
1049      represents the current 
1050   */
1051   int *ed_map;
1052   int ed_width, ed_height, ed_orig;
1053
1054   /* the amount of perturbation to use for translate is mc_perturb */
1055   int perturb;
1056   /* version 2 members after here */
1057 } i_quantize;
1058
1059 /* distance measures used by some filters */
1060 enum {
1061   i_dmeasure_euclidean = 0,
1062   i_dmeasure_euclidean_squared = 1,
1063   i_dmeasure_manhatten = 2,
1064   i_dmeasure_limit = 2,
1065 };
1066
1067 #include "iolayert.h"
1068
1069 /* error message information returned by im_errors() */
1070
1071 typedef struct {
1072   char *msg;
1073   int code;
1074 } i_errmsg;
1075
1076 typedef struct i_render_tag i_render;
1077
1078 /*
1079 =item i_color_model_t
1080 =category Data Types
1081 =order 95
1082
1083 Returned by L</i_img_color_model(im)> to indicate the color model of
1084 the image.
1085
1086 An enumerated type with the following possible values:
1087
1088 =over
1089
1090 =item *
1091
1092 C<icm_unknown> - the image has no usable color data.  In future
1093 versions of Imager this will be returned in a few limited cases,
1094 eg. when the source image is CMYK and the user has requested no color
1095 translation is done.
1096
1097 =item *
1098
1099 C<icm_gray> - gray scale with no alpha channel.
1100
1101 =item *
1102
1103 C<icm_gray_alpha> - gray scale with an alpha channel.
1104
1105 =item *
1106
1107 C<icm_rgb> - RGB
1108
1109 =item *
1110
1111 C<icm_rgb_alpha> - RGB with an alpha channel.
1112
1113 =back
1114
1115 =cut
1116 */
1117
1118 typedef enum {
1119   icm_unknown,
1120   icm_gray,
1121   icm_gray_alpha,
1122   icm_rgb,
1123   icm_rgb_alpha
1124 } i_color_model_t;
1125
1126 #ifdef IMAGER_FORMAT_ATTR
1127 #define I_FORMAT_ATTR(format_index, va_index) \
1128   __attribute ((format (printf, format_index, va_index)))
1129 #else
1130 #define I_FORMAT_ATTR(format_index, va_index)
1131 #endif
1132
1133 #ifdef _MSC_VER
1134 #  ifndef vsnprintf
1135 #  define vsnprintf _vsnprintf
1136 #  endif
1137 #  ifndef snprintf
1138 #  define snprintf _snprintf
1139 #  endif
1140 #endif
1141
1142 /*
1143 =item i_DF
1144 =category Data Types
1145 =synopsis printf("left %" i_DF "\n", i_DFc(x));
1146 =order 95
1147
1148 This is a constant string that can be used with functions like
1149 printf() to format i_img_dim values after they're been cast with i_DFc().
1150
1151 Does not include the leading C<%>.
1152
1153 =cut
1154
1155 =item i_DFc
1156 =category Data Types
1157 =order 95
1158
1159 Cast an C<i_img_dim> value to a type for use with the i_DF format
1160 string.
1161
1162 =cut
1163
1164 =item i_DFp
1165 =category Data Types
1166 =synopsis printf("point (" i_DFp ")\n", i_DFcp(x, y));
1167 =order 95
1168
1169 Format a pair of C<i_img_dim> values.  This format string I<does>
1170 include the leading C<%>.
1171
1172 =cut
1173
1174 =item i_DFcp
1175 =category Data Types
1176 =order 95
1177
1178 Casts two C<i_img_dim> values for use with the i_DF (or i_DFp) format.
1179
1180 =cut
1181  */
1182
1183 #define i_DFc(x) ((i_dim_format_t)(x))
1184 #define i_DFcp(x, y) i_DFc(x), i_DFc(y)
1185 #define i_DFp "%" i_DF ", %" i_DF
1186
1187 #endif
1188