/* * Copyright (c) 2007, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ This directory contains source code to perform a wide variety of image conversions for the Java AWT. The image conversion process is controlled by a function skeleton defined in the include file which invokes a number of macros in different categories to perform the work of reading and decoding the input pixels and then scaling, dithering, and storing the pixels in the destination image structure. Each part of that process can be implemented in one of several different ways depending on the type of input data and output representation needed and depending on the speed and quality desired. The conversion process as defined by can be broken down into the following categories: Fetching retrieving pixels from the source pixel data Decoding decoding source pixels into color/alpha information Scaling resampling source data for a different resolution Encoding converting source colors into a destination pixel Alpha converting alpha values into masks or alpha channels Storing storing the final pixels in the destination image Each category defines a number of different macros that are used by the code skeleton in to perform the work of converting the images. The macros for each category are all implemented by a number of other header files with multiple implementations provided for each category depending on the particular type of input or output data desired. The files which implement the various categories are as follows: Fetching Fetch 8 bit pixels from a byte array Fetch 32 bit pixels from a int array Fetch 8 or 32 bit pixels Decoding Decode IndexColorModel pixels Decode DirectColorModel pixels Decode DirectColorModel pixels with at least 8 bits per component Decode any type of ColorModel's pixels (with native handling of Index and Direct) Scaling Don't scale input data at all Nearest Neighbor scaling - replicate or omit pixels as necessary Encoding No encoding at all (only for 24-bit images) Compose DirectColor pixels, 8-bits/component Compose DirectColor pixels up to 8-bits/comp Floyd-Steinberg error diffusion, gray ramp (requires TopDownLeftRight source data) Floyd-Steinberg error diffusion, RGB color map (requires TopDownLeftRight source data) Floyd-Steinberg error diffusion, RGB or gray (requires TopDownLeftRight source data) unsigned ordered dither error, gray ramp unsigned ordered dither error, RGB color map signed ordered dither error, RGB color map unsigned ordered dither error, RGB or gray (must also include ordclrsgn or ordclruns) Alpha No alpha processing (must be opaque input) Produce 1-bit transparency masks from alpha data using an ordered dithering technique Storing Store 8-bit pixels in a byte array Store 16-bit pixels in a short array Store 24-bit pixels in a byte triplet array Store 32-bit pixels in an int array Store 8, 16 or 24 bit pixels Store 8, 16 or 32 bit pixels Store 8 or 32 bit pixels Some of these header files also require a number of definitions to be provided by the platform implementor. These definitions are usually placed in a file called "img_util_md.h" and included when defining an actual image scaling function (see below). Most of the definitions can be implemented using either macros or functions unless indicated below. Here is a list of the various required definitions and the files or categories which rely on them: used by typedef [integer base type] MaskBits; Specifies the base type for transparency mask manipulation. Some platforms may manipulate masks 8-bits at a time and others may manipulate them 32-bits at a time. MaskBits *ImgInitMask(cvdata); Create a transparency mask buffer and return a handle to it. The buffer will be created on the fly whenever the first transparent pixel is encountered. If no transparent pixels are ever encountered, there will be no reason to create a mask. The buffer should be initialized to opacity values where any existing opaque converted data resides and to transparency values where there is no data yet. int MaskScan(cvdata); Return the size of a single scan line in the output mask buffer in MaskBits sized units. If the mask data is being buffered a scan line at a time, then return 0 to indicate that successive scan lines should overwrite each other in the single row-sized buffer. int MaskOffset(x); Return the index into an array of MaskBits elements where the data for the indicated x coordinate resides. This is typically (x >> (sizeof(MaskBits) * 8)). int MaskInit(x); Return a number with the appropriate single bit set for modifying the mask location for the indicated x coordinate. This is typically (1 << (x & ((sizeof(MaskBits) * 8) - 1))). void SetOpaqueBit(mask, bit); Perform the necessary logical operation on the accumulator "mask" with the indicated "bit" to indicate an opaque pixel. If bits set to 1 represent opacity, then this operation is typically defined as (mask |= bit). Note that SetOpaqueBit must be implemented as a macro since the first argument, the mask accumulator, must be modified. void SetTransparentBit(mask, bit); Perform the necessary logical operation on the accumulator "mask" with the indicated "bit" to indicate a transparent pixel. If bits set to 0 represent transparency, then this operation is typically defined as (mask &= (~bit)). Note that SetTransparentBit must be implemented as a macro since the first argument, the mask accumulator, must be modified. used directly by void BufComplete(cvdata, dstX1, dstY1, dstX2, dstY2); Called at the end of the image conversion function to perform any final processing on the buffer, the x1,y1,x2,y2 coordinates specify the rectangular region of the output buffer that was modified. used by all variants void SendRow(ird, dstY, dstX1, dstX2); Called at the end of the processing for a given row to allow the platform to buffer converted data by row and then move the data into place a row at a time (for instance under X11, you might want to convert a row of pixels in a row-sized local buffer and then execute XPutImage to send that one row to the server to save on the client side memory requirements) int ScanBytes(cvdata); Return the size in bytes of a single scan line in the output buffer. If the data is being buffered a scan line at a time, then return 0 to indicate that successive scan lines should overwrite each other in the single row-sized buffer. used by and int ColorCubeFSMap(red, green, blue); Return the pixel value of the closest color to the requested red, green, and blue components. The components are already bound to the range 0 <= component <= 255. used by all variants void GetPixelRGB(pixel, red, green, blue); Store the appropriate color components for the indicated output "pixel" into the red, green, and blue arguments. Note that GetPixelRGB must be implemented as a macro since the last three arguments must be modified, but the macro could be implemented to call a function. You can expect that the red, green, and blue arguments are simple variables if you need to reference them. used by (used to be known as img_ordcolor.h) extern uns_ordered_dither_array img_oda_red; extern uns_ordered_dither_array img_oda_green; extern uns_ordered_dither_array img_oda_blue; These names can be #defined to refer to some other global variables. int ColorCubeOrdMapUns(red, green, blue); Return the pixel value of the next color darker than the requested red, green, and blue components. The components are already bound to the range 0 <= component <= 256, where 256 represents maximum intensity, but 255 represents the next to highest intensity. used by extern sgn_ordered_dither_array img_oda_red; extern sgn_ordered_dither_array img_oda_green; extern sgn_ordered_dither_array img_oda_blue; These names can be #defined to refer to some other global variables. int ColorCubeOrdMapSgn(red, green, blue); Return the pixel value of the closest color to the requested red, green, and blue components. The components are already bound to the range 0 <= component <= 255. (Typically equivalent to ColorCubeFSMap(r, g, b)) used by all variants extern unsigned char img_grays[256]; extern unsigned char img_bwgamma[256]; The img_bwgamma table allows a gamma curve to be placed on the grayscale dithering to improve the output match when the gray ramp has very few gray values in it. The img_grays table is a simple best match lookup for an 8-bit gray value to the best pixel value in the available gray ramp. These names can be #defined to refer to some other global variables. used by extern sgn_ordered_dither_array img_oda_gray; This name can be #defined to refer to some other global variable. To implement a given conversion function, simply create a file which includes the necessary header files from the above list which match the properties that you are trying to handle. In some cases, you can choose a very general header file to handle more cases as a default implementation, or a very specific header file to handle common cases more efficiently. Then simply define the macro "NAME" to represent the name of the function you wish to create and then include the skeleton file to do the actual work. When you compile this file it will generate an object file which defines a function with the given name that performs the indicated image conversion. An example of a file which defines a very generalized function to convert any input data into an 8-bit output image with an associated transparency mask (if needed) would be: --------genimgcv8.c---------- #include "img_util.h" /* always needed */ #include "img_util_md.h" /* supplies platform definitions */ #include "img_input8_32.h" /* any type of input pixels */ #include "img_anycm.h" /* any type of input ColorModel */ #include "img_replscale.h" /* scale if necessary */ #include "img_orddither.h" /* color or grayscale dithering */ #include "img_alpha.h" /* generate 1-bit mask if necessary */ #include "img_output8.h" /* store byte pixels */ #define NAME ImgConvert8 /* Name our function */ #include "img_scaleloop.h" /* include the skeleton */ -----end of genimgcv8.c------