1/*
2 * Copyright (c) 2007, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26This directory contains source code to perform a wide variety of image
27conversions for the Java AWT.
28
29The image conversion process is controlled by a function skeleton
30defined in the include file <img_scaleloop.h> which invokes a number
31of macros in different categories to perform the work of reading and
32decoding the input pixels and then scaling, dithering, and storing the
33pixels in the destination image structure. Each part of that process
34can be implemented in one of several different ways depending on the
35type of input data and output representation needed and depending on
36the speed and quality desired.
37
38The conversion process as defined by <img_scaleloop.h> can be broken
39down into the following categories:
40
41 Fetching retrieving pixels from the source pixel data
42 Decoding decoding source pixels into color/alpha information
43 Scaling resampling source data for a different resolution
44 Encoding converting source colors into a destination pixel
45 Alpha converting alpha values into masks or alpha channels
46 Storing storing the final pixels in the destination image
47
48Each category defines a number of different macros that are used by the
49code skeleton in <img_scaleloop.h> to perform the work of converting
50the images. The macros for each category are all implemented by a
51number of other header files with multiple implementations provided
52for each category depending on the particular type of input or output
53data desired. The files which implement the various categories are as
54follows:
55
56 Fetching
57 <img_input8.h> Fetch 8 bit pixels from a byte array
58 <img_input32.h> Fetch 32 bit pixels from a int array
59 <img_input8_32.h> Fetch 8 or 32 bit pixels
60
61 Decoding
62 <img_icm.h> Decode IndexColorModel pixels
63 <img_dcm.h> Decode DirectColorModel pixels
64 <img_dcm8.h> Decode DirectColorModel pixels with at
65 least 8 bits per component
66 <img_anycm.h> Decode any type of ColorModel's pixels (with
67 native handling of Index and Direct)
68
69 Scaling
70 <img_noscale.h> Don't scale input data at all
71 <img_replscale.h> Nearest Neighbor scaling - replicate or
72 omit pixels as necessary
73
74 Encoding
75 <img_nodither.h> No encoding at all (only for 24-bit images)
76 <img_dir8dither.h> Compose DirectColor pixels, 8-bits/component
77 <img_dirdither.h> Compose DirectColor pixels up to 8-bits/comp
78 <img_fsgray.h> Floyd-Steinberg error diffusion, gray ramp
79 (requires TopDownLeftRight source data)
80 <img_fscolor.h> Floyd-Steinberg error diffusion, RGB color map
81 (requires TopDownLeftRight source data)
82 <img_fsdither.h> Floyd-Steinberg error diffusion, RGB or gray
83 (requires TopDownLeftRight source data)
84 <img_ordgray.h> unsigned ordered dither error, gray ramp
85 <img_ordclruns.h> unsigned ordered dither error, RGB color map
86 <img_ordclrsgn.h> signed ordered dither error, RGB color map
87 <img_orddither.h> unsigned ordered dither error, RGB or gray
88 (must also include ordclrsgn or ordclruns)
89
90 Alpha
91 <img_opaque.h> No alpha processing (must be opaque input)
92 <img_alpha.h> Produce 1-bit transparency masks from alpha
93 data using an ordered dithering technique
94
95 Storing
96 <img_output8.h> Store 8-bit pixels in a byte array
97 <img_output16.h> Store 16-bit pixels in a short array
98 <img_output24.h> Store 24-bit pixels in a byte triplet array
99 <img_output32.h> Store 32-bit pixels in an int array
100 <img_output8_16_24.h> Store 8, 16 or 24 bit pixels
101 <img_output8_16_32.h> Store 8, 16 or 32 bit pixels
102 <img_output8_32.h> Store 8 or 32 bit pixels
103
104Some of these header files also require a number of definitions to be
105provided by the platform implementor. These definitions are usually
106placed in a file called "img_util_md.h" and included when defining an
107actual image scaling function (see below). Most of the definitions
108can be implemented using either macros or functions unless indicated
109below. Here is a list of the various required definitions and the
110files or categories which rely on them:
111
112used by <img_alpha.h>
113
114 typedef [integer base type] MaskBits;
115 Specifies the base type for transparency mask manipulation.
116 Some platforms may manipulate masks 8-bits at a time and others
117 may manipulate them 32-bits at a time.
118
119 MaskBits *ImgInitMask(cvdata);
120 Create a transparency mask buffer and return a handle to it.
121 The buffer will be created on the fly whenever the first
122 transparent pixel is encountered. If no transparent pixels
123 are ever encountered, there will be no reason to create a
124 mask. The buffer should be initialized to opacity values
125 where any existing opaque converted data resides and to
126 transparency values where there is no data yet.
127
128 int MaskScan(cvdata);
129 Return the size of a single scan line in the output mask buffer
130 in MaskBits sized units. If the mask data is being buffered a
131 scan line at a time, then return 0 to indicate that successive
132 scan lines should overwrite each other in the single row-sized
133 buffer.
134
135 int MaskOffset(x);
136 Return the index into an array of MaskBits elements where the
137 data for the indicated x coordinate resides. This is typically
138 (x >> (sizeof(MaskBits) * 8)).
139
140 int MaskInit(x);
141 Return a number with the appropriate single bit set for modifying
142 the mask location for the indicated x coordinate. This is
143 typically (1 << (x & ((sizeof(MaskBits) * 8) - 1))).
144
145 void SetOpaqueBit(mask, bit);
146 Perform the necessary logical operation on the accumulator "mask"
147 with the indicated "bit" to indicate an opaque pixel. If bits set
148 to 1 represent opacity, then this operation is typically defined
149 as (mask |= bit). Note that SetOpaqueBit must be implemented as
150 a macro since the first argument, the mask accumulator, must be
151 modified.
152
153 void SetTransparentBit(mask, bit);
154 Perform the necessary logical operation on the accumulator "mask"
155 with the indicated "bit" to indicate a transparent pixel. If bits
156 set to 0 represent transparency, then this operation is typically
157 defined as (mask &= (~bit)). Note that SetTransparentBit must
158 be implemented as a macro since the first argument, the mask
159 accumulator, must be modified.
160
161used directly by <img_scaleloop.h>
162
163 void BufComplete(cvdata, dstX1, dstY1, dstX2, dstY2);
164 Called at the end of the image conversion function to perform any
165 final processing on the buffer, the x1,y1,x2,y2 coordinates specify
166 the rectangular region of the output buffer that was modified.
167
168used by all <img_output*.h> variants
169
170 void SendRow(ird, dstY, dstX1, dstX2);
171 Called at the end of the processing for a given row to allow
172 the platform to buffer converted data by row and then move the
173 data into place a row at a time (for instance under X11, you
174 might want to convert a row of pixels in a row-sized local
175 buffer and then execute XPutImage to send that one row to the
176 server to save on the client side memory requirements)
177
178 int ScanBytes(cvdata);
179 Return the size in bytes of a single scan line in the output
180 buffer. If the data is being buffered a scan line at a time,
181 then return 0 to indicate that successive scan lines should
182 overwrite each other in the single row-sized buffer.
183
184used by <img_fscolor.h> and <img_sgnordcolor.h>
185
186 int ColorCubeFSMap(red, green, blue);
187 Return the pixel value of the closest color to the requested
188 red, green, and blue components. The components are already
189 bound to the range 0 <= component <= 255.
190
191used by all <img_fs*.h> variants
192
193 void GetPixelRGB(pixel, red, green, blue);
194 Store the appropriate color components for the indicated output
195 "pixel" into the red, green, and blue arguments. Note that
196 GetPixelRGB must be implemented as a macro since the last three
197 arguments must be modified, but the macro could be implemented
198 to call a function. You can expect that the red, green, and
199 blue arguments are simple variables if you need to reference
200 them.
201
202used by <img_ordclruns.h> (used to be known as img_ordcolor.h)
203
204 extern uns_ordered_dither_array img_oda_red;
205 extern uns_ordered_dither_array img_oda_green;
206 extern uns_ordered_dither_array img_oda_blue;
207 These names can be #defined to refer to some other global
208 variables.
209
210 int ColorCubeOrdMapUns(red, green, blue);
211 Return the pixel value of the next color darker than the
212 requested red, green, and blue components. The components
213 are already bound to the range 0 <= component <= 256, where
214 256 represents maximum intensity, but 255 represents the
215 next to highest intensity.
216
217used by <img_ordclrsgn.h>
218
219 extern sgn_ordered_dither_array img_oda_red;
220 extern sgn_ordered_dither_array img_oda_green;
221 extern sgn_ordered_dither_array img_oda_blue;
222 These names can be #defined to refer to some other global
223 variables.
224
225 int ColorCubeOrdMapSgn(red, green, blue);
226 Return the pixel value of the closest color to the requested
227 red, green, and blue components. The components are already
228 bound to the range 0 <= component <= 255.
229 (Typically equivalent to ColorCubeFSMap(r, g, b))
230
231used by all <img_*gray.h> variants
232
233 extern unsigned char img_grays[256];
234 extern unsigned char img_bwgamma[256];
235 The img_bwgamma table allows a gamma curve to be placed on the
236 grayscale dithering to improve the output match when the gray
237 ramp has very few gray values in it. The img_grays table is
238 a simple best match lookup for an 8-bit gray value to the best
239 pixel value in the available gray ramp.
240 These names can be #defined to refer to some other global
241 variables.
242
243used by <img_ordgray.h>
244
245 extern sgn_ordered_dither_array img_oda_gray;
246 This name can be #defined to refer to some other global
247 variable.
248
249To implement a given conversion function, simply create a file which
250includes the necessary header files from the above list which match
251the properties that you are trying to handle. In some cases, you can
252choose a very general header file to handle more cases as a default
253implementation, or a very specific header file to handle common cases
254more efficiently. Then simply define the macro "NAME" to represent
255the name of the function you wish to create and then include the skeleton
256file <img_scaleloop.h> to do the actual work. When you compile this file
257it will generate an object file which defines a function with the given
258name that performs the indicated image conversion. An example of a file
259which defines a very generalized function to convert any input data into
260an 8-bit output image with an associated transparency mask (if needed)
261would be:
262
263--------genimgcv8.c----------
264#include "img_util.h" /* always needed */
265#include "img_util_md.h" /* supplies platform definitions */
266
267#include "img_input8_32.h" /* any type of input pixels */
268#include "img_anycm.h" /* any type of input ColorModel */
269#include "img_replscale.h" /* scale if necessary */
270#include "img_orddither.h" /* color or grayscale dithering */
271#include "img_alpha.h" /* generate 1-bit mask if necessary */
272#include "img_output8.h" /* store byte pixels */
273
274#define NAME ImgConvert8 /* Name our function */
275
276#include "img_scaleloop.h" /* include the skeleton */
277-----end of genimgcv8.c------
278