src/share/native/sun/awt/image/cvutils/README

/* 
 * 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 <img_scaleloop.h> 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 <img_scaleloop.h> 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 <img_scaleloop.h> 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
	<img_input8.h>		Fetch 8 bit pixels from a byte array
	<img_input32.h>		Fetch 32 bit pixels from a int array
	<img_input8_32.h>	Fetch 8 or 32 bit pixels

    Decoding
    	<img_icm.h>		Decode IndexColorModel pixels
    	<img_dcm.h>		Decode DirectColorModel pixels
    	<img_dcm8.h>		Decode DirectColorModel pixels with at
				    least 8 bits per component
    	<img_anycm.h>		Decode any type of ColorModel's pixels (with
				    native handling of Index and Direct)

    Scaling
    	<img_noscale.h>		Don't scale input data at all
	<img_replscale.h>	Nearest Neighbor scaling - replicate or
				    omit pixels as necessary

    Encoding
	<img_nodither.h>	No encoding at all (only for 24-bit images)
	<img_dir8dither.h>	Compose DirectColor pixels, 8-bits/component 
	<img_dirdither.h>	Compose DirectColor pixels up to 8-bits/comp
	<img_fsgray.h>		Floyd-Steinberg error diffusion, gray ramp
				    (requires TopDownLeftRight source data)
	<img_fscolor.h>		Floyd-Steinberg error diffusion, RGB color map
				    (requires TopDownLeftRight source data)
	<img_fsdither.h>	Floyd-Steinberg error diffusion, RGB or gray
				    (requires TopDownLeftRight source data)
	<img_ordgray.h>		unsigned ordered dither error, gray ramp
	<img_ordclruns.h>	unsigned ordered dither error, RGB color map
	<img_ordclrsgn.h>	signed ordered dither error, RGB color map
	<img_orddither.h>	unsigned ordered dither error, RGB or gray
				    (must also include ordclrsgn or ordclruns)

    Alpha
    	<img_opaque.h>		No alpha processing (must be opaque input)
    	<img_alpha.h>		Produce 1-bit transparency masks from alpha
				    data using an ordered dithering technique

    Storing
    	<img_output8.h>		Store 8-bit pixels in a byte array
    	<img_output16.h>	Store 16-bit pixels in a short array
    	<img_output24.h>	Store 24-bit pixels in a byte triplet array
    	<img_output32.h>	Store 32-bit pixels in an int array
    	<img_output8_16_24.h>	Store 8, 16 or 24 bit pixels
    	<img_output8_16_32.h>	Store 8, 16 or 32 bit pixels
    	<img_output8_32.h>	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 <img_alpha.h>

    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 <img_scaleloop.h>

    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 <img_output*.h> 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 <img_fscolor.h> and <img_sgnordcolor.h>

    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 <img_fs*.h> 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 <img_ordclruns.h> (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 <img_ordclrsgn.h>

    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 <img_*gray.h> 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 <img_ordgray.h>

    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 <img_scaleloop.h> 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------