mlib_ImageColorDitherInit(3mlib)

1mlib_ImageColorDitherInit(3mMeLdIiBa)Lib Library Funcmtliiobn_sImageColorDitherInit(3MLIB)
2
3
4

NAME

6       mlib_ImageColorDitherInit - initialization for image dithering
7

SYNOPSIS

9       cc [ flag... ] file... -lmlib [ library... ]
10       #include <mlib.h>
11
12       mlib_status mlib_ImageColorDitherInit(void **colormap, const mlib_s32 *dimensions,
13            mlib_type intype, mlib_type outtype, mlib_s32 channels, mlib_s32 entries,
14            mlib_s32 offset, void **lut);
15
16

DESCRIPTION

18       The  mlib_ImageColorDitherInit()  function  creates  an  internal  data
19       structure, colormap, which can be used by one of  the  following  func‐
20       tions for image dithering:
21
22         mlib_ImageColorErrorDiffusion3x3
23         mlib_ImageColorErrorDiffusionMxN
24         mlib_ImageColorOrderedDither8x8
25         mlib_ImageColorOrderedDitherMxN
26
27
28
29       The  lut  might have either 1 or 3 channels. The type of the lut can be
30       one of the following:
31
32         MLIB_BYTE in, MLIB_BYTE out (i.e., BYTE-to-BYTE)
33         MLIB_BIT in, MLIB_BYTE out (i.e., BIT-to-BYTE)
34
35
36
37       If dimensions == NULL, then no colorcube will be created. In this case,
38       the user-provided lookup table, lut, will be used for dithering.
39
40
41       If  dimensions  !=  NULL, then a colorcube is created from scratch in a
42       way shown in the following example.
43
44
45       To dither an RGB image of type MLIB_BYTE to a  color-indexed  image  of
46       type MLIB_BYTE, we can use the following parameters:
47
48         mlib_s32  dimensions[] = {2, 3, 4};
49         mlib_type intype = MLIB_BYTE;
50         mlib_type outtype = MLIB_BYTE;
51         mlib_s32  channels = 3;
52         mlib_s32  offset = 6;
53
54
55
56       These  values  would  lead  to  the  creation of a colorcube that would
57       dither red values in the source image to one of  2  red  levels,  green
58       values  to one of 3 green levels, and blue values to one of 4 blue lev‐
59       els.  You could picture this colorcube as a cube with dimensions of  2,
60       3,  and  4.  The index values assigned to the elements in that cube can
61       be described by the following lookup table:
62
63
64
65
66
67          Indexes     │   Red Values   │ Green Values   │ Blue Values
68       ───────────────┼────────────────┼────────────────┼───────────────
69       0              │                │                │
70       ───────────────┼────────────────┼────────────────┼───────────────
71       ...            │                │                │
72       ───────────────┼────────────────┼────────────────┼───────────────
73       5              │                │                │
74       ───────────────┼────────────────┼────────────────┼───────────────
75       6              │ 0              │ 0              │0
76       ───────────────┼────────────────┼────────────────┼───────────────
77       7              │ 255            │ 0              │0
78       ───────────────┼────────────────┼────────────────┼───────────────
79       8              │ 0              │ 128            │0
80       ───────────────┼────────────────┼────────────────┼───────────────
81       9              │ 255            │ 128            │0
82       ───────────────┼────────────────┼────────────────┼───────────────
83       10             │ 0              │ 255            │0
84       ───────────────┼────────────────┼────────────────┼───────────────
85       11             │ 255            │ 255            │0
86       ───────────────┼────────────────┼────────────────┼───────────────
87       12             │ 0              │ 0              │85
88       ───────────────┼────────────────┼────────────────┼───────────────
89       13             │ 255            │ 0              │85
90       ───────────────┼────────────────┼────────────────┼───────────────
91       14             │ 0              │ 128            │85
92       ───────────────┼────────────────┼────────────────┼───────────────
93       15             │ 255            │ 128            │85
94       ───────────────┼────────────────┼────────────────┼───────────────
95       16             │ 0              │ 255            │85
96       ───────────────┼────────────────┼────────────────┼───────────────
97       17             │ 255            │ 255            │85
98       ───────────────┼────────────────┼────────────────┼───────────────
99       18             │ 0              │ 0              │170
100       ───────────────┼────────────────┼────────────────┼───────────────
101       19             │ 255            │ 0              │170
102       ───────────────┼────────────────┼────────────────┼───────────────
103       20             │ 0              │ 128            │170
104       ───────────────┼────────────────┼────────────────┼───────────────
105       21             │ 255            │ 128            │170
106       ───────────────┼────────────────┼────────────────┼───────────────
107       22             │ 0              │ 255            │170
108       ───────────────┼────────────────┼────────────────┼───────────────
109       23             │ 255            │ 255            │170
110       ───────────────┼────────────────┼────────────────┼───────────────
111       24             │ 0              │ 0              │255
112       ───────────────┼────────────────┼────────────────┼───────────────
113       25             │ 255            │ 0              │255
114       ───────────────┼────────────────┼────────────────┼───────────────
115       26             │ 0              │ 128            │255
116       ───────────────┼────────────────┼────────────────┼───────────────
117       27             │ 255            │ 128            │255
118       ───────────────┼────────────────┼────────────────┼───────────────
119       28             │ 0              │ 255            │255
120       ───────────────┼────────────────┼────────────────┼───────────────
121       29             │ 255            │ 255            │255
122       ───────────────┼────────────────┼────────────────┼───────────────
123       ...            │                │                │
124
125
126
127       The distance between level changes in each channel of the lookup  table
128       is determined by the following formulas:
129
130         multipliers[0] = signof(dimensions[0])*1;
131         multipliers[i] = signof(dimensions[i])*
132                          abs(multipliers[i-1]*dimension[i-1]);
133
134
135
136       A negative dimensions[i], so as to a negative multipliers[i], indicates
137       that the values in a color ramp for channel i should appear in decreas‐
138       ing as opposed to increasing order.
139
140
141       For each channel i, the values of the levels are determined by the fol‐
142       lowing formulas:
143
144         double delta = (dataMax - dataMin)/(abs(dimensions[i]) - 1);
145         int levels[j] = (int)(j*delta + 0.5);
146
147
148
149       where dataMax and dataMin are the maximum and minimum  values,  respec‐
150       tively, for data type intype.
151
152
153       Whenever  a colorcube is created, if lut != NULL, the lookup table will
154       be filled according to the colorcube and supplied parameters like  off‐
155       set.   For  the  example  shown above, the lookup table will start from
156       line 6.  In this case, it is the user's responsibility to allocate mem‐
157       ory for the lookup table.
158

PARAMETERS

160       The function takes the following arguments:
161
162       colormap      Internal data structure for image dithering.
163
164
165       dimensions     Dimensions of the colorcube in the colormap structure.
166
167
168       intype        Data type of the source image and the lookup table.
169
170
171       outtype       Data type of the destination indexed image.
172
173
174       channels      Number of channels of the lookup table and source image.
175
176
177       entries       Number of entries of the lookup table.
178
179
180       offset        Index offset of the lookup table.
181
182
183       lut           Lookup table.
184
185

RETURN VALUES

187       The  function  returns MLIB_SUCCESS if successful. Otherwise it returns
188       MLIB_FAILURE.
189

ATTRIBUTES

191       See attributes(5) for descriptions of the following attributes:
192
193
194
195
196       ┌─────────────────────────────┬─────────────────────────────┐
197       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
198       ├─────────────────────────────┼─────────────────────────────┤
199       │Interface Stability          │Committed                    │
200       ├─────────────────────────────┼─────────────────────────────┤
201       │MT-Level                     │MT-Safe                      │
202       └─────────────────────────────┴─────────────────────────────┘
203

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUES

ATTRIBUTES

SEE ALSO