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