/*

 * 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.

 */

/* ****************************************************************

 ******************************************************************

 ******************************************************************

 *** COPYRIGHT (c) Eastman Kodak Company, 1997

 *** As  an unpublished  work pursuant to Title 17 of the United

 *** States Code.  All rights reserved.

 ******************************************************************

 ******************************************************************

 ******************************************************************/

package java.awt.image;

import java.awt.Rectangle;

import java.awt.Point;

import sun.awt.image.ByteInterleavedRaster;

import sun.awt.image.ShortInterleavedRaster;

import sun.awt.image.IntegerInterleavedRaster;

import sun.awt.image.ByteBandedRaster;

import sun.awt.image.ShortBandedRaster;

import sun.awt.image.BytePackedRaster;

import sun.awt.image.SunWritableRaster;

/**

 * A class representing a rectangular array of pixels.  A Raster

 * encapsulates a DataBuffer that stores the sample values and a

 * SampleModel that describes how to locate a given sample value in a

 * DataBuffer.

 * <p>

 * A Raster defines values for pixels occupying a particular

 * rectangular area of the plane, not necessarily including (0, 0).

 * The rectangle, known as the Raster's bounding rectangle and

 * available by means of the getBounds method, is defined by minX,

 * minY, width, and height values.  The minX and minY values define

 * the coordinate of the upper left corner of the Raster.  References

 * to pixels outside of the bounding rectangle may result in an

 * exception being thrown, or may result in references to unintended

 * elements of the Raster's associated DataBuffer.  It is the user's

 * responsibility to avoid accessing such pixels.

 * <p>

 * A SampleModel describes how samples of a Raster

 * are stored in the primitive array elements of a DataBuffer.

 * Samples may be stored one per data element, as in a

 * PixelInterleavedSampleModel or BandedSampleModel, or packed several to

 * an element, as in a SinglePixelPackedSampleModel or

 * MultiPixelPackedSampleModel.  The SampleModel is also

 * controls whether samples are sign extended, allowing unsigned

 * data to be stored in signed Java data types such as byte, short, and

 * int.

 * <p>

 * Although a Raster may live anywhere in the plane, a SampleModel

 * makes use of a simple coordinate system that starts at (0, 0).  A

 * Raster therefore contains a translation factor that allows pixel

 * locations to be mapped between the Raster's coordinate system and

 * that of the SampleModel.  The translation from the SampleModel

 * coordinate system to that of the Raster may be obtained by the

 * getSampleModelTranslateX and getSampleModelTranslateY methods.

 * <p>

 * A Raster may share a DataBuffer with another Raster either by

 * explicit construction or by the use of the createChild and

 * createTranslatedChild methods.  Rasters created by these methods

 * can return a reference to the Raster they were created from by

 * means of the getParent method.  For a Raster that was not

 * constructed by means of a call to createTranslatedChild or

 * createChild, getParent will return null.

 * <p>

 * The createTranslatedChild method returns a new Raster that

 * shares all of the data of the current Raster, but occupies a

 * bounding rectangle of the same width and height but with a

 * different starting point.  For example, if the parent Raster

 * occupied the region (10, 10) to (100, 100), and the translated

 * Raster was defined to start at (50, 50), then pixel (20, 20) of the

 * parent and pixel (60, 60) of the child occupy the same location in

 * the DataBuffer shared by the two Rasters.  In the first case, (-10,

 * -10) should be added to a pixel coordinate to obtain the

 * corresponding SampleModel coordinate, and in the second case (-50,

 * -50) should be added.

 * <p>

 * The translation between a parent and child Raster may be

 * determined by subtracting the child's sampleModelTranslateX and

 * sampleModelTranslateY values from those of the parent.

 * <p>

 * The createChild method may be used to create a new Raster

 * occupying only a subset of its parent's bounding rectangle

 * (with the same or a translated coordinate system) or

 * with a subset of the bands of its parent.

 * <p>

 * All constructors are protected.  The correct way to create a

 * Raster is to use one of the static create methods defined in this

 * class.  These methods create instances of Raster that use the

 * standard Interleaved, Banded, and Packed SampleModels and that may

 * be processed more efficiently than a Raster created by combining

 * an externally generated SampleModel and DataBuffer.

 * @see java.awt.image.DataBuffer

 * @see java.awt.image.SampleModel

 * @see java.awt.image.PixelInterleavedSampleModel

 * @see java.awt.image.BandedSampleModel

 * @see java.awt.image.SinglePixelPackedSampleModel

 * @see java.awt.image.MultiPixelPackedSampleModel

 */

public class Raster {

    /**

     * The SampleModel that describes how pixels from this Raster

     * are stored in the DataBuffer.

     */

    protected SampleModel sampleModel;

    /** The DataBuffer that stores the image data. */

    protected DataBuffer dataBuffer;

    /** The X coordinate of the upper-left pixel of this Raster. */

    protected int minX;

    /** The Y coordinate of the upper-left pixel of this Raster. */

    protected int minY;

    /** The width of this Raster. */

    protected int width;

    /** The height of this Raster. */

    protected int height;

    /**

     * The X translation from the coordinate space of the

     * Raster's SampleModel to that of the Raster.

     */

    protected int sampleModelTranslateX;

    /**

     * The Y translation from the coordinate space of the

     * Raster's SampleModel to that of the Raster.

     */

    protected int sampleModelTranslateY;

    /** The number of bands in the Raster. */

    protected int numBands;

    /** The number of DataBuffer data elements per pixel. */

    protected int numDataElements;

    /** The parent of this Raster, or null. */

    protected Raster parent;

    private static native void initIDs();

    static {

        ColorModel.loadLibraries();

        initIDs();

    }

    /**

     * Creates a Raster based on a PixelInterleavedSampleModel with the

     * specified data type, width, height, and number of bands.

     *

     * <p> The upper left corner of the Raster is given by the

     * location argument.  If location is null, (0, 0) will be used.

     * The dataType parameter should be one of the enumerated values

     * defined in the DataBuffer class.

     *

     * <p> Note that interleaved {@code DataBuffer.TYPE_INT}

     * Rasters are not supported.  To create a 1-band Raster of type

     * {@code DataBuffer.TYPE_INT}, use

     * Raster.createPackedRaster().

     * <p> The only dataTypes supported currently are TYPE_BYTE

     * and TYPE_USHORT.

     * @param dataType  the data type for storing samples

     * @param w         the width in pixels of the image data

     * @param h         the height in pixels of the image data

     * @param bands     the number of bands

     * @param location  the upper-left corner of the {@code Raster}

     * @return a WritableRaster object with the specified data type,

     *         width, height and number of bands.

     * @throws RasterFormatException if {@code w} or {@code h}

     *         is less than or equal to zero, or computing either

     *         {@code location.x + w} or

     *         {@code location.y + h} results in integer

     *         overflow

     */

    public static WritableRaster createInterleavedRaster(int dataType,

                                                         int w, int h,

                                                         int bands,

                                                         Point location) {

        int[] bandOffsets = new int[bands];

        for (int i = 0; i < bands; i++) {

            bandOffsets[i] = i;

        }

        return createInterleavedRaster(dataType, w, h, w*bands, bands,

                                       bandOffsets, location);

    }

    /**

     * Creates a Raster based on a PixelInterleavedSampleModel with the

     * specified data type, width, height, scanline stride, pixel

     * stride, and band offsets.  The number of bands is inferred from

     * bandOffsets.length.

     *

     * <p> The upper left corner of the Raster is given by the

     * location argument.  If location is null, (0, 0) will be used.

     * The dataType parameter should be one of the enumerated values

     * defined in the DataBuffer class.

     *

     * <p> Note that interleaved {@code DataBuffer.TYPE_INT}

     * Rasters are not supported.  To create a 1-band Raster of type

     * {@code DataBuffer.TYPE_INT}, use

     * Raster.createPackedRaster().

     * <p> The only dataTypes supported currently are TYPE_BYTE

     * and TYPE_USHORT.

     * @param dataType  the data type for storing samples

     * @param w         the width in pixels of the image data

     * @param h         the height in pixels of the image data

     * @param scanlineStride the line stride of the image data

     * @param pixelStride the pixel stride of the image data

     * @param bandOffsets the offsets of all bands

     * @param location  the upper-left corner of the {@code Raster}

     * @return a WritableRaster object with the specified data type,

     *         width, height, scanline stride, pixel stride and band

     *         offsets.

     * @throws RasterFormatException if {@code w} or {@code h}

     *         is less than or equal to zero, or computing either

     *         {@code location.x + w} or

     *         {@code location.y + h} results in integer

     *         overflow

     * @throws IllegalArgumentException if {@code dataType} is not

     *         one of the supported data types, which are

     *         {@code DataBuffer.TYPE_BYTE}, or

     *         {@code DataBuffer.TYPE_USHORT}.

     */

    public static WritableRaster createInterleavedRaster(int dataType,

                                                         int w, int h,

                                                         int scanlineStride,

                                                         int pixelStride,

                                                         Point location) {

        DataBuffer d;

        int size = scanlineStride * (h - 1) + // fisrt (h - 1) scans

            pixelStride * w; // last scan

        switch(dataType) {

        case DataBuffer.TYPE_BYTE:

            d = new DataBufferByte(size);

            break;

        case DataBuffer.TYPE_USHORT:

            d = new DataBufferUShort(size);

            break;

        default:

            throw new IllegalArgumentException("Unsupported data type " +

                                                dataType);

        }

        return createInterleavedRaster(d, w, h, scanlineStride,

                                       pixelStride, bandOffsets, location);

    }

    /**

     * Creates a Raster based on a BandedSampleModel with the

     * specified data type, width, height, and number of bands.

     *

     * <p> The upper left corner of the Raster is given by the

     * location argument.  If location is null, (0, 0) will be used.

     * The dataType parameter should be one of the enumerated values

     * defined in the DataBuffer class.

     *

     * <p> The only dataTypes supported currently are TYPE_BYTE, TYPE_USHORT,

     * and TYPE_INT.

     * @param dataType  the data type for storing samples

     * @param w         the width in pixels of the image data

     * @param h         the height in pixels of the image data

     * @param bands     the number of bands

     * @param location  the upper-left corner of the {@code Raster}

     * @return a WritableRaster object with the specified data type,

     *         width, height and number of bands.

     * @throws RasterFormatException if {@code w} or {@code h}

     *         is less than or equal to zero, or computing either

     *         {@code location.x + w} or

     *         {@code location.y + h} results in integer

     *         overflow

     * @throws ArrayIndexOutOfBoundsException if {@code bands}

     *         is less than 1

     */

    public static WritableRaster createBandedRaster(int dataType,

                                                    int w, int h,

                                                    int bands,

                                                    Point location) {

        if (bands < 1) {

            throw new ArrayIndexOutOfBoundsException("Number of bands ("+

                                                     bands+") must"+

                                                     " be greater than 0");

        }

        int[] bankIndices = new int[bands];

        int[] bandOffsets = new int[bands];

        for (int i = 0; i < bands; i++) {

            bankIndices[i] = i;

            bandOffsets[i] = 0;

        }

        return createBandedRaster(dataType, w, h, w,

                                  bankIndices, bandOffsets,

                                  location);

    }

    /**

     * Creates a Raster based on a BandedSampleModel with the

     * specified data type, width, height, scanline stride, bank

     * indices and band offsets.  The number of bands is inferred from

     * bankIndices.length and bandOffsets.length, which must be the

     * same.

     *

     * <p> The upper left corner of the Raster is given by the

     * location argument.  The dataType parameter should be one of the

     * enumerated values defined in the DataBuffer class.

     *

     * <p> The only dataTypes supported currently are TYPE_BYTE, TYPE_USHORT,

     * and TYPE_INT.

     * @param dataType  the data type for storing samples

     * @param w         the width in pixels of the image data

     * @param h         the height in pixels of the image data

     * @param scanlineStride the line stride of the image data

     * @param bankIndices the bank indices for each band

     * @param bandOffsets the offsets of all bands

     * @param location  the upper-left corner of the {@code Raster}

     * @return a WritableRaster object with the specified data type,

     *         width, height, scanline stride, bank indices and band

     *         offsets.

     * @throws RasterFormatException if {@code w} or {@code h}

     *         is less than or equal to zero, or computing either

     *         {@code location.x + w} or

     *         {@code location.y + h} results in integer

     *         overflow

     * @throws IllegalArgumentException if {@code dataType} is not

     *         one of the supported data types, which are

     *         {@code DataBuffer.TYPE_BYTE},

     *         {@code DataBuffer.TYPE_USHORT}

     *         or {@code DataBuffer.TYPE_INT}

     * @throws ArrayIndexOutOfBoundsException if {@code bankIndices}

     *         or {@code bandOffsets} is {@code null}

     */

    public static WritableRaster createBandedRaster(int dataType,

                                                    int w, int h,

                                                    int scanlineStride,

                                                    Point location) {

        DataBuffer d;

        int bands = bandOffsets.length;

        if (bankIndices == null) {

            throw new

                ArrayIndexOutOfBoundsException("Bank indices array is null");

        }

        if (bandOffsets == null) {

            throw new

                ArrayIndexOutOfBoundsException("Band offsets array is null");

        }

        // Figure out the #banks and the largest band offset

        int maxBank = bankIndices[0];

        int maxBandOff = bandOffsets[0];

        for (int i = 1; i < bands; i++) {

            if (bankIndices[i] > maxBank) {

                maxBank = bankIndices[i];

            }

            if (bandOffsets[i] > maxBandOff) {

                maxBandOff = bandOffsets[i];

            }

        }

        int banks = maxBank + 1;

        int size = maxBandOff +

            scanlineStride * (h - 1) + // first (h - 1) scans

            w; // last scan

        switch(dataType) {

        case DataBuffer.TYPE_BYTE:

            d = new DataBufferByte(size, banks);

            break;

        case DataBuffer.TYPE_USHORT:

            d = new DataBufferUShort(size, banks);

            break;

        case DataBuffer.TYPE_INT:

            d = new DataBufferInt(size, banks);

            break;

        default:

            throw new IllegalArgumentException("Unsupported data type " +

                                                dataType);

        }

        return createBandedRaster(d, w, h, scanlineStride,

                                  bankIndices, bandOffsets, location);

    }

    /**

     * Creates a Raster based on a SinglePixelPackedSampleModel with

     * the specified data type, width, height, and band masks.

     * The number of bands is inferred from bandMasks.length.

     *

     * <p> The upper left corner of the Raster is given by the

     * location argument.  If location is null, (0, 0) will be used.

     * The dataType parameter should be one of the enumerated values

     * defined in the DataBuffer class.

     *

     * <p> The only dataTypes supported currently are TYPE_BYTE, TYPE_USHORT,

     * and TYPE_INT.

     * @param dataType  the data type for storing samples

     * @param w         the width in pixels of the image data

     * @param h         the height in pixels of the image data

     * @param bandMasks an array containing an entry for each band

     * @param location  the upper-left corner of the {@code Raster}

     * @return a WritableRaster object with the specified data type,

     *         width, height, and band masks.

     * @throws RasterFormatException if {@code w} or {@code h}

     *         is less than or equal to zero, or computing either

     *         {@code location.x + w} or

     *         {@code location.y + h} results in integer

     *         overflow

     * @throws IllegalArgumentException if {@code dataType} is not

     *         one of the supported data types, which are

     *         {@code DataBuffer.TYPE_BYTE},

     *         {@code DataBuffer.TYPE_USHORT}

     *         or {@code DataBuffer.TYPE_INT}

     */

    public static WritableRaster createPackedRaster(int dataType,

                                                    int w, int h,

                                                    Point location) {

        DataBuffer d;

        switch(dataType) {

        case DataBuffer.TYPE_BYTE:

            d = new DataBufferByte(w*h);

            break;

        case DataBuffer.TYPE_USHORT:

            d = new DataBufferUShort(w*h);

            break;

        case DataBuffer.TYPE_INT:

            d = new DataBufferInt(w*h);

            break;

        default:

            throw new IllegalArgumentException("Unsupported data type " +

                                                dataType);

        }

        return createPackedRaster(d, w, h, w, bandMasks, location);

    }

    /**

     * Creates a Raster based on a packed SampleModel with the

     * specified data type, width, height, number of bands, and bits

     * per band.  If the number of bands is one, the SampleModel will

     * be a MultiPixelPackedSampleModel.

     *

     * <p> If the number of bands is more than one, the SampleModel

     * will be a SinglePixelPackedSampleModel, with each band having

     * bitsPerBand bits.  In either case, the requirements on dataType

     * and bitsPerBand imposed by the corresponding SampleModel must

     * be met.

     *

     * <p> The upper left corner of the Raster is given by the

     * location argument.  If location is null, (0, 0) will be used.

     * The dataType parameter should be one of the enumerated values

     * defined in the DataBuffer class.

     *

     * <p> The only dataTypes supported currently are TYPE_BYTE, TYPE_USHORT,

     * and TYPE_INT.

     * @param dataType  the data type for storing samples

     * @param w         the width in pixels of the image data

     * @param h         the height in pixels of the image data

     * @param bands     the number of bands

     * @param bitsPerBand the number of bits per band

     * @param location  the upper-left corner of the {@code Raster}

     * @return a WritableRaster object with the specified data type,

     *         width, height, number of bands, and bits per band.

     * @throws RasterFormatException if {@code w} or {@code h}

     *         is less than or equal to zero, or computing either

     *         {@code location.x + w} or

     *         {@code location.y + h} results in integer

     *         overflow

     * @throws IllegalArgumentException if the product of

     *         {@code bitsPerBand} and {@code bands} is

     *         greater than the number of bits held by

     *         {@code dataType}

     * @throws IllegalArgumentException if {@code bitsPerBand} or

     *         {@code bands} is not greater than zero

     * @throws IllegalArgumentException if {@code dataType} is not

     *         one of the supported data types, which are

     *         {@code DataBuffer.TYPE_BYTE},

     *         {@code DataBuffer.TYPE_USHORT}