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