View Javadoc
1   /*
2    * Copyright (c) 1997, 2013, 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  
26  /* ****************************************************************
27   ******************************************************************
28   ******************************************************************
29   *** COPYRIGHT (c) Eastman Kodak Company, 1997
30   *** As  an unpublished  work pursuant to Title 17 of the United
31   *** States Code.  All rights reserved.
32   ******************************************************************
33   ******************************************************************
34   ******************************************************************/
35  
36  
37  package java.awt.image;
38  import java.awt.Rectangle;
39  import java.awt.Point;
40  
41  import sun.awt.image.ByteInterleavedRaster;
42  import sun.awt.image.ShortInterleavedRaster;
43  import sun.awt.image.IntegerInterleavedRaster;
44  import sun.awt.image.ByteBandedRaster;
45  import sun.awt.image.ShortBandedRaster;
46  import sun.awt.image.BytePackedRaster;
47  import sun.awt.image.SunWritableRaster;
48  
49  /**
50   * A class representing a rectangular array of pixels.  A Raster
51   * encapsulates a DataBuffer that stores the sample values and a
52   * SampleModel that describes how to locate a given sample value in a
53   * DataBuffer.
54   * <p>
55   * A Raster defines values for pixels occupying a particular
56   * rectangular area of the plane, not necessarily including (0, 0).
57   * The rectangle, known as the Raster's bounding rectangle and
58   * available by means of the getBounds method, is defined by minX,
59   * minY, width, and height values.  The minX and minY values define
60   * the coordinate of the upper left corner of the Raster.  References
61   * to pixels outside of the bounding rectangle may result in an
62   * exception being thrown, or may result in references to unintended
63   * elements of the Raster's associated DataBuffer.  It is the user's
64   * responsibility to avoid accessing such pixels.
65   * <p>
66   * A SampleModel describes how samples of a Raster
67   * are stored in the primitive array elements of a DataBuffer.
68   * Samples may be stored one per data element, as in a
69   * PixelInterleavedSampleModel or BandedSampleModel, or packed several to
70   * an element, as in a SinglePixelPackedSampleModel or
71   * MultiPixelPackedSampleModel.  The SampleModel is also
72   * controls whether samples are sign extended, allowing unsigned
73   * data to be stored in signed Java data types such as byte, short, and
74   * int.
75   * <p>
76   * Although a Raster may live anywhere in the plane, a SampleModel
77   * makes use of a simple coordinate system that starts at (0, 0).  A
78   * Raster therefore contains a translation factor that allows pixel
79   * locations to be mapped between the Raster's coordinate system and
80   * that of the SampleModel.  The translation from the SampleModel
81   * coordinate system to that of the Raster may be obtained by the
82   * getSampleModelTranslateX and getSampleModelTranslateY methods.
83   * <p>
84   * A Raster may share a DataBuffer with another Raster either by
85   * explicit construction or by the use of the createChild and
86   * createTranslatedChild methods.  Rasters created by these methods
87   * can return a reference to the Raster they were created from by
88   * means of the getParent method.  For a Raster that was not
89   * constructed by means of a call to createTranslatedChild or
90   * createChild, getParent will return null.
91   * <p>
92   * The createTranslatedChild method returns a new Raster that
93   * shares all of the data of the current Raster, but occupies a
94   * bounding rectangle of the same width and height but with a
95   * different starting point.  For example, if the parent Raster
96   * occupied the region (10, 10) to (100, 100), and the translated
97   * Raster was defined to start at (50, 50), then pixel (20, 20) of the
98   * parent and pixel (60, 60) of the child occupy the same location in
99   * the DataBuffer shared by the two Rasters.  In the first case, (-10,
100  * -10) should be added to a pixel coordinate to obtain the
101  * corresponding SampleModel coordinate, and in the second case (-50,
102  * -50) should be added.
103  * <p>
104  * The translation between a parent and child Raster may be
105  * determined by subtracting the child's sampleModelTranslateX and
106  * sampleModelTranslateY values from those of the parent.
107  * <p>
108  * The createChild method may be used to create a new Raster
109  * occupying only a subset of its parent's bounding rectangle
110  * (with the same or a translated coordinate system) or
111  * with a subset of the bands of its parent.
112  * <p>
113  * All constructors are protected.  The correct way to create a
114  * Raster is to use one of the static create methods defined in this
115  * class.  These methods create instances of Raster that use the
116  * standard Interleaved, Banded, and Packed SampleModels and that may
117  * be processed more efficiently than a Raster created by combining
118  * an externally generated SampleModel and DataBuffer.
119  * @see java.awt.image.DataBuffer
120  * @see java.awt.image.SampleModel
121  * @see java.awt.image.PixelInterleavedSampleModel
122  * @see java.awt.image.BandedSampleModel
123  * @see java.awt.image.SinglePixelPackedSampleModel
124  * @see java.awt.image.MultiPixelPackedSampleModel
125  */
126 public class Raster {
127 
128     /**
129      * The SampleModel that describes how pixels from this Raster
130      * are stored in the DataBuffer.
131      */
132     protected SampleModel sampleModel;
133 
134     /** The DataBuffer that stores the image data. */
135     protected DataBuffer dataBuffer;
136 
137     /** The X coordinate of the upper-left pixel of this Raster. */
138     protected int minX;
139 
140     /** The Y coordinate of the upper-left pixel of this Raster. */
141     protected int minY;
142 
143     /** The width of this Raster. */
144     protected int width;
145 
146     /** The height of this Raster. */
147     protected int height;
148 
149     /**
150      * The X translation from the coordinate space of the
151      * Raster's SampleModel to that of the Raster.
152      */
153     protected int sampleModelTranslateX;
154 
155     /**
156      * The Y translation from the coordinate space of the
157      * Raster's SampleModel to that of the Raster.
158      */
159     protected int sampleModelTranslateY;
160 
161     /** The number of bands in the Raster. */
162     protected int numBands;
163 
164     /** The number of DataBuffer data elements per pixel. */
165     protected int numDataElements;
166 
167     /** The parent of this Raster, or null. */
168     protected Raster parent;
169 
170     static private native void initIDs();
171     static {
172         ColorModel.loadLibraries();
173         initIDs();
174     }
175 
176     /**
177      * Creates a Raster based on a PixelInterleavedSampleModel with the
178      * specified data type, width, height, and number of bands.
179      *
180      * <p> The upper left corner of the Raster is given by the
181      * location argument.  If location is null, (0, 0) will be used.
182      * The dataType parameter should be one of the enumerated values
183      * defined in the DataBuffer class.
184      *
185      * <p> Note that interleaved <code>DataBuffer.TYPE_INT</code>
186      * Rasters are not supported.  To create a 1-band Raster of type
187      * <code>DataBuffer.TYPE_INT</code>, use
188      * Raster.createPackedRaster().
189      * <p> The only dataTypes supported currently are TYPE_BYTE
190      * and TYPE_USHORT.
191      * @param dataType  the data type for storing samples
192      * @param w         the width in pixels of the image data
193      * @param h         the height in pixels of the image data
194      * @param bands     the number of bands
195      * @param location  the upper-left corner of the <code>Raster</code>
196      * @return a WritableRaster object with the specified data type,
197      *         width, height and number of bands.
198      * @throws RasterFormatException if <code>w</code> or <code>h</code>
199      *         is less than or equal to zero, or computing either
200      *         <code>location.x + w</code> or
201      *         <code>location.y + h</code> results in integer
202      *         overflow
203      */
204     public static WritableRaster createInterleavedRaster(int dataType,
205                                                          int w, int h,
206                                                          int bands,
207                                                          Point location) {
208         int[] bandOffsets = new int[bands];
209         for (int i = 0; i < bands; i++) {
210             bandOffsets[i] = i;
211         }
212         return createInterleavedRaster(dataType, w, h, w*bands, bands,
213                                        bandOffsets, location);
214     }
215 
216     /**
217      * Creates a Raster based on a PixelInterleavedSampleModel with the
218      * specified data type, width, height, scanline stride, pixel
219      * stride, and band offsets.  The number of bands is inferred from
220      * bandOffsets.length.
221      *
222      * <p> The upper left corner of the Raster is given by the
223      * location argument.  If location is null, (0, 0) will be used.
224      * The dataType parameter should be one of the enumerated values
225      * defined in the DataBuffer class.
226      *
227      * <p> Note that interleaved <code>DataBuffer.TYPE_INT</code>
228      * Rasters are not supported.  To create a 1-band Raster of type
229      * <code>DataBuffer.TYPE_INT</code>, use
230      * Raster.createPackedRaster().
231      * <p> The only dataTypes supported currently are TYPE_BYTE
232      * and TYPE_USHORT.
233      * @param dataType  the data type for storing samples
234      * @param w         the width in pixels of the image data
235      * @param h         the height in pixels of the image data
236      * @param scanlineStride the line stride of the image data
237      * @param pixelStride the pixel stride of the image data
238      * @param bandOffsets the offsets of all bands
239      * @param location  the upper-left corner of the <code>Raster</code>
240      * @return a WritableRaster object with the specified data type,
241      *         width, height, scanline stride, pixel stride and band
242      *         offsets.
243      * @throws RasterFormatException if <code>w</code> or <code>h</code>
244      *         is less than or equal to zero, or computing either
245      *         <code>location.x + w</code> or
246      *         <code>location.y + h</code> results in integer
247      *         overflow
248      * @throws IllegalArgumentException if <code>dataType</code> is not
249      *         one of the supported data types, which are
250      *         <code>DataBuffer.TYPE_BYTE</code>, or
251      *         <code>DataBuffer.TYPE_USHORT</code>.
252      */
253     public static WritableRaster createInterleavedRaster(int dataType,
254                                                          int w, int h,
255                                                          int scanlineStride,
256                                                          int pixelStride,
257                                                          int bandOffsets[],
258                                                          Point location) {
259         DataBuffer d;
260 
261         int size = scanlineStride * (h - 1) + // fisrt (h - 1) scans
262             pixelStride * w; // last scan
263 
264         switch(dataType) {
265         case DataBuffer.TYPE_BYTE:
266             d = new DataBufferByte(size);
267             break;
268 
269         case DataBuffer.TYPE_USHORT:
270             d = new DataBufferUShort(size);
271             break;
272 
273         default:
274             throw new IllegalArgumentException("Unsupported data type " +
275                                                 dataType);
276         }
277 
278         return createInterleavedRaster(d, w, h, scanlineStride,
279                                        pixelStride, bandOffsets, location);
280     }
281 
282     /**
283      * Creates a Raster based on a BandedSampleModel with the
284      * specified data type, width, height, and number of bands.
285      *
286      * <p> The upper left corner of the Raster is given by the
287      * location argument.  If location is null, (0, 0) will be used.
288      * The dataType parameter should be one of the enumerated values
289      * defined in the DataBuffer class.
290      *
291      * <p> The only dataTypes supported currently are TYPE_BYTE, TYPE_USHORT,
292      * and TYPE_INT.
293      * @param dataType  the data type for storing samples
294      * @param w         the width in pixels of the image data
295      * @param h         the height in pixels of the image data
296      * @param bands     the number of bands
297      * @param location  the upper-left corner of the <code>Raster</code>
298      * @return a WritableRaster object with the specified data type,
299      *         width, height and number of bands.
300      * @throws RasterFormatException if <code>w</code> or <code>h</code>
301      *         is less than or equal to zero, or computing either
302      *         <code>location.x + w</code> or
303      *         <code>location.y + h</code> results in integer
304      *         overflow
305      * @throws ArrayIndexOutOfBoundsException if <code>bands</code>
306      *         is less than 1
307      */
308     public static WritableRaster createBandedRaster(int dataType,
309                                                     int w, int h,
310                                                     int bands,
311                                                     Point location) {
312         if (bands < 1) {
313             throw new ArrayIndexOutOfBoundsException("Number of bands ("+
314                                                      bands+") must"+
315                                                      " be greater than 0");
316         }
317         int[] bankIndices = new int[bands];
318         int[] bandOffsets = new int[bands];
319         for (int i = 0; i < bands; i++) {
320             bankIndices[i] = i;
321             bandOffsets[i] = 0;
322         }
323 
324         return createBandedRaster(dataType, w, h, w,
325                                   bankIndices, bandOffsets,
326                                   location);
327     }
328 
329     /**
330      * Creates a Raster based on a BandedSampleModel with the
331      * specified data type, width, height, scanline stride, bank
332      * indices and band offsets.  The number of bands is inferred from
333      * bankIndices.length and bandOffsets.length, which must be the
334      * same.
335      *
336      * <p> The upper left corner of the Raster is given by the
337      * location argument.  The dataType parameter should be one of the
338      * enumerated values defined in the DataBuffer class.
339      *
340      * <p> The only dataTypes supported currently are TYPE_BYTE, TYPE_USHORT,
341      * and TYPE_INT.
342      * @param dataType  the data type for storing samples
343      * @param w         the width in pixels of the image data
344      * @param h         the height in pixels of the image data
345      * @param scanlineStride the line stride of the image data
346      * @param bankIndices the bank indices for each band
347      * @param bandOffsets the offsets of all bands
348      * @param location  the upper-left corner of the <code>Raster</code>
349      * @return a WritableRaster object with the specified data type,
350      *         width, height, scanline stride, bank indices and band
351      *         offsets.
352      * @throws RasterFormatException if <code>w</code> or <code>h</code>
353      *         is less than or equal to zero, or computing either
354      *         <code>location.x + w</code> or
355      *         <code>location.y + h</code> results in integer
356      *         overflow
357      * @throws IllegalArgumentException if <code>dataType</code> is not
358      *         one of the supported data types, which are
359      *         <code>DataBuffer.TYPE_BYTE</code>,
360      *         <code>DataBuffer.TYPE_USHORT</code>
361      *         or <code>DataBuffer.TYPE_INT</code>
362      * @throws ArrayIndexOutOfBoundsException if <code>bankIndices</code>
363      *         or <code>bandOffsets</code> is <code>null</code>
364      */
365     public static WritableRaster createBandedRaster(int dataType,
366                                                     int w, int h,
367                                                     int scanlineStride,
368                                                     int bankIndices[],
369                                                     int bandOffsets[],
370                                                     Point location) {
371         DataBuffer d;
372         int bands = bandOffsets.length;
373 
374         if (bankIndices == null) {
375             throw new
376                 ArrayIndexOutOfBoundsException("Bank indices array is null");
377         }
378         if (bandOffsets == null) {
379             throw new
380                 ArrayIndexOutOfBoundsException("Band offsets array is null");
381         }
382 
383         // Figure out the #banks and the largest band offset
384         int maxBank = bankIndices[0];
385         int maxBandOff = bandOffsets[0];
386         for (int i = 1; i < bands; i++) {
387             if (bankIndices[i] > maxBank) {
388                 maxBank = bankIndices[i];
389             }
390             if (bandOffsets[i] > maxBandOff) {
391                 maxBandOff = bandOffsets[i];
392             }
393         }
394         int banks = maxBank + 1;
395         int size = maxBandOff +
396             scanlineStride * (h - 1) + // fisrt (h - 1) scans
397             w; // last scan
398 
399         switch(dataType) {
400         case DataBuffer.TYPE_BYTE:
401             d = new DataBufferByte(size, banks);
402             break;
403 
404         case DataBuffer.TYPE_USHORT:
405             d = new DataBufferUShort(size, banks);
406             break;
407 
408         case DataBuffer.TYPE_INT:
409             d = new DataBufferInt(size, banks);
410             break;
411 
412         default:
413             throw new IllegalArgumentException("Unsupported data type " +
414                                                 dataType);
415         }
416 
417         return createBandedRaster(d, w, h, scanlineStride,
418                                   bankIndices, bandOffsets, location);
419     }
420 
421     /**
422      * Creates a Raster based on a SinglePixelPackedSampleModel with
423      * the specified data type, width, height, and band masks.
424      * The number of bands is inferred from bandMasks.length.
425      *
426      * <p> The upper left corner of the Raster is given by the
427      * location argument.  If location is null, (0, 0) will be used.
428      * The dataType parameter should be one of the enumerated values
429      * defined in the DataBuffer class.
430      *
431      * <p> The only dataTypes supported currently are TYPE_BYTE, TYPE_USHORT,
432      * and TYPE_INT.
433      * @param dataType  the data type for storing samples
434      * @param w         the width in pixels of the image data
435      * @param h         the height in pixels of the image data
436      * @param bandMasks an array containing an entry for each band
437      * @param location  the upper-left corner of the <code>Raster</code>
438      * @return a WritableRaster object with the specified data type,
439      *         width, height, and band masks.
440      * @throws RasterFormatException if <code>w</code> or <code>h</code>
441      *         is less than or equal to zero, or computing either
442      *         <code>location.x + w</code> or
443      *         <code>location.y + h</code> results in integer
444      *         overflow
445      * @throws IllegalArgumentException if <code>dataType</code> is not
446      *         one of the supported data types, which are
447      *         <code>DataBuffer.TYPE_BYTE</code>,
448      *         <code>DataBuffer.TYPE_USHORT</code>
449      *         or <code>DataBuffer.TYPE_INT</code>
450      */
451     public static WritableRaster createPackedRaster(int dataType,
452                                                     int w, int h,
453                                                     int bandMasks[],
454                                                     Point location) {
455         DataBuffer d;
456 
457         switch(dataType) {
458         case DataBuffer.TYPE_BYTE:
459             d = new DataBufferByte(w*h);
460             break;
461 
462         case DataBuffer.TYPE_USHORT:
463             d = new DataBufferUShort(w*h);
464             break;
465 
466         case DataBuffer.TYPE_INT:
467             d = new DataBufferInt(w*h);
468             break;
469 
470         default:
471             throw new IllegalArgumentException("Unsupported data type " +
472                                                 dataType);
473         }
474 
475         return createPackedRaster(d, w, h, w, bandMasks, location);
476     }
477 
478     /**
479      * Creates a Raster based on a packed SampleModel with the
480      * specified data type, width, height, number of bands, and bits
481      * per band.  If the number of bands is one, the SampleModel will
482      * be a MultiPixelPackedSampleModel.
483      *
484      * <p> If the number of bands is more than one, the SampleModel
485      * will be a SinglePixelPackedSampleModel, with each band having
486      * bitsPerBand bits.  In either case, the requirements on dataType
487      * and bitsPerBand imposed by the corresponding SampleModel must
488      * be met.
489      *
490      * <p> The upper left corner of the Raster is given by the
491      * location argument.  If location is null, (0, 0) will be used.
492      * The dataType parameter should be one of the enumerated values
493      * defined in the DataBuffer class.
494      *
495      * <p> The only dataTypes supported currently are TYPE_BYTE, TYPE_USHORT,
496      * and TYPE_INT.
497      * @param dataType  the data type for storing samples
498      * @param w         the width in pixels of the image data
499      * @param h         the height in pixels of the image data
500      * @param bands     the number of bands
501      * @param bitsPerBand the number of bits per band
502      * @param location  the upper-left corner of the <code>Raster</code>
503      * @return a WritableRaster object with the specified data type,
504      *         width, height, number of bands, and bits per band.
505      * @throws RasterFormatException if <code>w</code> or <code>h</code>
506      *         is less than or equal to zero, or computing either
507      *         <code>location.x + w</code> or
508      *         <code>location.y + h</code> results in integer
509      *         overflow
510      * @throws IllegalArgumentException if the product of
511      *         <code>bitsPerBand</code> and <code>bands</code> is
512      *         greater than the number of bits held by
513      *         <code>dataType</code>
514      * @throws IllegalArgumentException if <code>bitsPerBand</code> or
515      *         <code>bands</code> is not greater than zero
516      * @throws IllegalArgumentException if <code>dataType</code> is not
517      *         one of the supported data types, which are
518      *         <code>DataBuffer.TYPE_BYTE</code>,
519      *         <code>DataBuffer.TYPE_USHORT</code>
520      *         or <code>DataBuffer.TYPE_INT</code>
521      */
522     public static WritableRaster createPackedRaster(int dataType,
523                                                     int w, int h,
524                                                     int bands,
525                                                     int bitsPerBand,
526                                                     Point location) {
527         DataBuffer d;
528 
529         if (bands <= 0) {
530             throw new IllegalArgumentException("Number of bands ("+bands+
531                                                ") must be greater than 0");
532         }
533 
534         if (bitsPerBand <= 0) {
535             throw new IllegalArgumentException("Bits per band ("+bitsPerBand+
536                                                ") must be greater than 0");
537         }
538 
539         if (bands != 1) {
540             int[] masks = new int[bands];
541             int mask = (1 << bitsPerBand) - 1;
542             int shift = (bands-1)*bitsPerBand;
543 
544             /* Make sure the total mask size will fit in the data type */
545             if (shift+bitsPerBand > DataBuffer.getDataTypeSize(dataType)) {
546                 throw new IllegalArgumentException("bitsPerBand("+
547                                                    bitsPerBand+") * bands is "+
548                                                    " greater than data type "+
549                                                    "size.");
550             }
551             switch(dataType) {
552             case DataBuffer.TYPE_BYTE:
553             case DataBuffer.TYPE_USHORT:
554             case DataBuffer.TYPE_INT:
555                 break;
556             default:
557                 throw new IllegalArgumentException("Unsupported data type " +
558                                                     dataType);
559             }
560 
561             for (int i = 0; i < bands; i++) {
562                 masks[i] = mask << shift;
563                 shift = shift - bitsPerBand;
564             }
565 
566             return createPackedRaster(dataType, w, h, masks, location);
567         }
568         else {
569             double fw = w;
570             switch(dataType) {
571             case DataBuffer.TYPE_BYTE:
572                 d = new DataBufferByte((int)(Math.ceil(fw/(8/bitsPerBand)))*h);
573                 break;
574 
575             case DataBuffer.TYPE_USHORT:
576                 d = new DataBufferUShort((int)(Math.ceil(fw/(16/bitsPerBand)))*h);
577                 break;
578 
579             case DataBuffer.TYPE_INT:
580                 d = new DataBufferInt((int)(Math.ceil(fw/(32/bitsPerBand)))*h);
581                 break;
582 
583             default:
584                 throw new IllegalArgumentException("Unsupported data type " +
585                                                    dataType);
586             }
587 
588             return createPackedRaster(d, w, h, bitsPerBand, location);
589         }
590     }
591 
592     /**
593      * Creates a Raster based on a PixelInterleavedSampleModel with the
594      * specified DataBuffer, width, height, scanline stride, pixel
595      * stride, and band offsets.  The number of bands is inferred from
596      * bandOffsets.length.  The upper left corner of the Raster
597      * is given by the location argument.  If location is null, (0, 0)
598      * will be used.
599      * <p> Note that interleaved <code>DataBuffer.TYPE_INT</code>
600      * Rasters are not supported.  To create a 1-band Raster of type
601      * <code>DataBuffer.TYPE_INT</code>, use
602      * Raster.createPackedRaster().
603      * @param dataBuffer the <code>DataBuffer</code> that contains the
604      *        image data
605      * @param w         the width in pixels of the image data
606      * @param h         the height in pixels of the image data
607      * @param scanlineStride the line stride of the image data
608      * @param pixelStride the pixel stride of the image data
609      * @param bandOffsets the offsets of all bands
610      * @param location  the upper-left corner of the <code>Raster</code>
611      * @return a WritableRaster object with the specified
612      *         <code>DataBuffer</code>, width, height, scanline stride,
613      *         pixel stride and band offsets.
614      * @throws RasterFormatException if <code>w</code> or <code>h</code>
615      *         is less than or equal to zero, or computing either
616      *         <code>location.x + w</code> or
617      *         <code>location.y + h</code> results in integer
618      *         overflow
619      * @throws IllegalArgumentException if <code>dataType</code> is not
620      *         one of the supported data types, which are
621      *         <code>DataBuffer.TYPE_BYTE</code>,
622      *         <code>DataBuffer.TYPE_USHORT</code>
623      * @throws RasterFormatException if <code>dataBuffer</code> has more
624      *         than one bank.
625      * @throws NullPointerException if <code>dataBuffer</code> is null
626      */
627     public static WritableRaster createInterleavedRaster(DataBuffer dataBuffer,
628                                                          int w, int h,
629                                                          int scanlineStride,
630                                                          int pixelStride,
631                                                          int bandOffsets[],
632                                                          Point location) {
633         if (dataBuffer == null) {
634             throw new NullPointerException("DataBuffer cannot be null");
635         }
636         if (location == null) {
637             location = new Point(0, 0);
638         }
639         int dataType = dataBuffer.getDataType();
640 
641         PixelInterleavedSampleModel csm =
642             new PixelInterleavedSampleModel(dataType, w, h,
643                                             pixelStride,
644                                             scanlineStride,
645                                             bandOffsets);
646         switch(dataType) {
647         case DataBuffer.TYPE_BYTE:
648             return new ByteInterleavedRaster(csm, dataBuffer, location);
649 
650         case DataBuffer.TYPE_USHORT:
651             return new ShortInterleavedRaster(csm, dataBuffer, location);
652 
653         default:
654             throw new IllegalArgumentException("Unsupported data type " +
655                                                 dataType);
656         }
657     }
658 
659     /**
660      * Creates a Raster based on a BandedSampleModel with the
661      * specified DataBuffer, width, height, scanline stride, bank
662      * indices, and band offsets.  The number of bands is inferred
663      * from bankIndices.length and bandOffsets.length, which must be
664      * the same.  The upper left corner of the Raster is given by the
665      * location argument.  If location is null, (0, 0) will be used.
666      * @param dataBuffer the <code>DataBuffer</code> that contains the
667      *        image data
668      * @param w         the width in pixels of the image data
669      * @param h         the height in pixels of the image data
670      * @param scanlineStride the line stride of the image data
671      * @param bankIndices the bank indices for each band
672      * @param bandOffsets the offsets of all bands
673      * @param location  the upper-left corner of the <code>Raster</code>
674      * @return a WritableRaster object with the specified
675      *         <code>DataBuffer</code>, width, height, scanline stride,
676      *         bank indices and band offsets.
677      * @throws RasterFormatException if <code>w</code> or <code>h</code>
678      *         is less than or equal to zero, or computing either
679      *         <code>location.x + w</code> or
680      *         <code>location.y + h</code> results in integer
681      *         overflow
682      * @throws IllegalArgumentException if <code>dataType</code> is not
683      *         one of the supported data types, which are
684      *         <code>DataBuffer.TYPE_BYTE</code>,
685      *         <code>DataBuffer.TYPE_USHORT</code>
686      *         or <code>DataBuffer.TYPE_INT</code>
687      * @throws NullPointerException if <code>dataBuffer</code> is null
688      */
689     public static WritableRaster createBandedRaster(DataBuffer dataBuffer,
690                                                     int w, int h,
691                                                     int scanlineStride,
692                                                     int bankIndices[],
693                                                     int bandOffsets[],
694                                                     Point location) {
695         if (dataBuffer == null) {
696             throw new NullPointerException("DataBuffer cannot be null");
697         }
698         if (location == null) {
699            location = new Point(0,0);
700         }
701         int dataType = dataBuffer.getDataType();
702 
703         int bands = bankIndices.length;
704         if (bandOffsets.length != bands) {
705             throw new IllegalArgumentException(
706                                    "bankIndices.length != bandOffsets.length");
707         }
708 
709         BandedSampleModel bsm =
710             new BandedSampleModel(dataType, w, h,
711                                   scanlineStride,
712                                   bankIndices, bandOffsets);
713 
714         switch(dataType) {
715         case DataBuffer.TYPE_BYTE:
716             return new ByteBandedRaster(bsm, dataBuffer, location);
717 
718         case DataBuffer.TYPE_USHORT:
719             return new ShortBandedRaster(bsm, dataBuffer, location);
720 
721         case DataBuffer.TYPE_INT:
722             return new SunWritableRaster(bsm, dataBuffer, location);
723 
724         default:
725             throw new IllegalArgumentException("Unsupported data type " +
726                                                 dataType);
727         }
728     }
729 
730     /**
731      * Creates a Raster based on a SinglePixelPackedSampleModel with
732      * the specified DataBuffer, width, height, scanline stride, and
733      * band masks.  The number of bands is inferred from bandMasks.length.
734      * The upper left corner of the Raster is given by
735      * the location argument.  If location is null, (0, 0) will be used.
736      * @param dataBuffer the <code>DataBuffer</code> that contains the
737      *        image data
738      * @param w         the width in pixels of the image data
739      * @param h         the height in pixels of the image data
740      * @param scanlineStride the line stride of the image data
741      * @param bandMasks an array containing an entry for each band
742      * @param location  the upper-left corner of the <code>Raster</code>
743      * @return a WritableRaster object with the specified
744      *         <code>DataBuffer</code>, width, height, scanline stride,
745      *         and band masks.
746      * @throws RasterFormatException if <code>w</code> or <code>h</code>
747      *         is less than or equal to zero, or computing either
748      *         <code>location.x + w</code> or
749      *         <code>location.y + h</code> results in integer
750      *         overflow
751      * @throws IllegalArgumentException if <code>dataType</code> is not
752      *         one of the supported data types, which are
753      *         <code>DataBuffer.TYPE_BYTE</code>,
754      *         <code>DataBuffer.TYPE_USHORT</code>
755      *         or <code>DataBuffer.TYPE_INT</code>
756      * @throws RasterFormatException if <code>dataBuffer</code> has more
757      *         than one bank.
758      * @throws NullPointerException if <code>dataBuffer</code> is null
759      */
760     public static WritableRaster createPackedRaster(DataBuffer dataBuffer,
761                                                     int w, int h,
762                                                     int scanlineStride,
763                                                     int bandMasks[],
764                                                     Point location) {
765         if (dataBuffer == null) {
766             throw new NullPointerException("DataBuffer cannot be null");
767         }
768         if (location == null) {
769            location = new Point(0,0);
770         }
771         int dataType = dataBuffer.getDataType();
772 
773         SinglePixelPackedSampleModel sppsm =
774             new SinglePixelPackedSampleModel(dataType, w, h, scanlineStride,
775                                              bandMasks);
776 
777         switch(dataType) {
778         case DataBuffer.TYPE_BYTE:
779             return new ByteInterleavedRaster(sppsm, dataBuffer, location);
780 
781         case DataBuffer.TYPE_USHORT:
782             return new ShortInterleavedRaster(sppsm, dataBuffer, location);
783 
784         case DataBuffer.TYPE_INT:
785             return new IntegerInterleavedRaster(sppsm, dataBuffer, location);
786 
787         default:
788             throw new IllegalArgumentException("Unsupported data type " +
789                                                 dataType);
790         }
791     }
792 
793     /**
794      * Creates a Raster based on a MultiPixelPackedSampleModel with the
795      * specified DataBuffer, width, height, and bits per pixel.  The upper
796      * left corner of the Raster is given by the location argument.  If
797      * location is null, (0, 0) will be used.
798      * @param dataBuffer the <code>DataBuffer</code> that contains the
799      *        image data
800      * @param w         the width in pixels of the image data
801      * @param h         the height in pixels of the image data
802      * @param bitsPerPixel the number of bits for each pixel
803      * @param location  the upper-left corner of the <code>Raster</code>
804      * @return a WritableRaster object with the specified
805      *         <code>DataBuffer</code>, width, height, and
806      *         bits per pixel.
807      * @throws RasterFormatException if <code>w</code> or <code>h</code>
808      *         is less than or equal to zero, or computing either
809      *         <code>location.x + w</code> or
810      *         <code>location.y + h</code> results in integer
811      *         overflow
812      * @throws IllegalArgumentException if <code>dataType</code> is not
813      *         one of the supported data types, which are
814      *         <code>DataBuffer.TYPE_BYTE</code>,
815      *         <code>DataBuffer.TYPE_USHORT</code>
816      *         or <code>DataBuffer.TYPE_INT</code>
817      * @throws RasterFormatException if <code>dataBuffer</code> has more
818      *         than one bank.
819      * @throws NullPointerException if <code>dataBuffer</code> is null
820      */
821     public static WritableRaster createPackedRaster(DataBuffer dataBuffer,
822                                                     int w, int h,
823                                                     int bitsPerPixel,
824                                                     Point location) {
825         if (dataBuffer == null) {
826             throw new NullPointerException("DataBuffer cannot be null");
827         }
828         if (location == null) {
829            location = new Point(0,0);
830         }
831         int dataType = dataBuffer.getDataType();
832 
833         if (dataType != DataBuffer.TYPE_BYTE &&
834             dataType != DataBuffer.TYPE_USHORT &&
835             dataType != DataBuffer.TYPE_INT) {
836             throw new IllegalArgumentException("Unsupported data type " +
837                                                dataType);
838         }
839 
840         if (dataBuffer.getNumBanks() != 1) {
841             throw new
842                 RasterFormatException("DataBuffer for packed Rasters"+
843                                       " must only have 1 bank.");
844         }
845 
846         MultiPixelPackedSampleModel mppsm =
847                 new MultiPixelPackedSampleModel(dataType, w, h, bitsPerPixel);
848 
849         if (dataType == DataBuffer.TYPE_BYTE &&
850             (bitsPerPixel == 1 || bitsPerPixel == 2 || bitsPerPixel == 4)) {
851             return new BytePackedRaster(mppsm, dataBuffer, location);
852         } else {
853             return new SunWritableRaster(mppsm, dataBuffer, location);
854         }
855     }
856 
857 
858     /**
859      *  Creates a Raster with the specified SampleModel and DataBuffer.
860      *  The upper left corner of the Raster is given by the location argument.
861      *  If location is null, (0, 0) will be used.
862      *  @param sm the specified <code>SampleModel</code>
863      *  @param db the specified <code>DataBuffer</code>
864      *  @param location the upper-left corner of the <code>Raster</code>
865      *  @return a <code>Raster</code> with the specified
866      *          <code>SampleModel</code>, <code>DataBuffer</code>, and
867      *          location.
868      * @throws RasterFormatException if computing either
869      *         <code>location.x + sm.getWidth()</code> or
870      *         <code>location.y + sm.getHeight()</code> results in integer
871      *         overflow
872      * @throws RasterFormatException if <code>db</code> has more
873      *         than one bank and <code>sm</code> is a
874      *         PixelInterleavedSampleModel, SinglePixelPackedSampleModel,
875      *         or MultiPixelPackedSampleModel.
876      *  @throws NullPointerException if either SampleModel or DataBuffer is
877      *          null
878      */
879     public static Raster createRaster(SampleModel sm,
880                                       DataBuffer db,
881                                       Point location) {
882         if ((sm == null) || (db == null)) {
883             throw new NullPointerException("SampleModel and DataBuffer cannot be null");
884         }
885 
886         if (location == null) {
887            location = new Point(0,0);
888         }
889         int dataType = sm.getDataType();
890 
891         if (sm instanceof PixelInterleavedSampleModel) {
892             switch(dataType) {
893                 case DataBuffer.TYPE_BYTE:
894                     return new ByteInterleavedRaster(sm, db, location);
895 
896                 case DataBuffer.TYPE_USHORT:
897                     return new ShortInterleavedRaster(sm, db, location);
898             }
899         } else if (sm instanceof SinglePixelPackedSampleModel) {
900             switch(dataType) {
901                 case DataBuffer.TYPE_BYTE:
902                     return new ByteInterleavedRaster(sm, db, location);
903 
904                 case DataBuffer.TYPE_USHORT:
905                     return new ShortInterleavedRaster(sm, db, location);
906 
907                 case DataBuffer.TYPE_INT:
908                     return new IntegerInterleavedRaster(sm, db, location);
909             }
910         } else if (sm instanceof MultiPixelPackedSampleModel &&
911                    dataType == DataBuffer.TYPE_BYTE &&
912                    sm.getSampleSize(0) < 8) {
913             return new BytePackedRaster(sm, db, location);
914         }
915 
916         // we couldn't do anything special - do the generic thing
917 
918         return new Raster(sm,db,location);
919     }
920 
921     /**
922      *  Creates a WritableRaster with the specified SampleModel.
923      *  The upper left corner of the Raster is given by the location argument.
924      *  If location is null, (0, 0) will be used.
925      *  @param sm the specified <code>SampleModel</code>
926      *  @param location the upper-left corner of the
927      *         <code>WritableRaster</code>
928      *  @return a <code>WritableRaster</code> with the specified
929      *          <code>SampleModel</code> and location.
930      *  @throws RasterFormatException if computing either
931      *          <code>location.x + sm.getWidth()</code> or
932      *          <code>location.y + sm.getHeight()</code> results in integer
933      *          overflow
934      */
935     public static WritableRaster createWritableRaster(SampleModel sm,
936                                                       Point location) {
937         if (location == null) {
938            location = new Point(0,0);
939         }
940 
941         return createWritableRaster(sm, sm.createDataBuffer(), location);
942     }
943 
944     /**
945      *  Creates a WritableRaster with the specified SampleModel and DataBuffer.
946      *  The upper left corner of the Raster is given by the location argument.
947      *  If location is null, (0, 0) will be used.
948      *  @param sm the specified <code>SampleModel</code>
949      *  @param db the specified <code>DataBuffer</code>
950      *  @param location the upper-left corner of the
951      *         <code>WritableRaster</code>
952      *  @return a <code>WritableRaster</code> with the specified
953      *          <code>SampleModel</code>, <code>DataBuffer</code>, and
954      *          location.
955      * @throws RasterFormatException if computing either
956      *         <code>location.x + sm.getWidth()</code> or
957      *         <code>location.y + sm.getHeight()</code> results in integer
958      *         overflow
959      * @throws RasterFormatException if <code>db</code> has more
960      *         than one bank and <code>sm</code> is a
961      *         PixelInterleavedSampleModel, SinglePixelPackedSampleModel,
962      *         or MultiPixelPackedSampleModel.
963      * @throws NullPointerException if either SampleModel or DataBuffer is null
964      */
965     public static WritableRaster createWritableRaster(SampleModel sm,
966                                                       DataBuffer db,
967                                                       Point location) {
968         if ((sm == null) || (db == null)) {
969             throw new NullPointerException("SampleModel and DataBuffer cannot be null");
970         }
971         if (location == null) {
972            location = new Point(0,0);
973         }
974 
975         int dataType = sm.getDataType();
976 
977         if (sm instanceof PixelInterleavedSampleModel) {
978             switch(dataType) {
979                 case DataBuffer.TYPE_BYTE:
980                     return new ByteInterleavedRaster(sm, db, location);
981 
982                 case DataBuffer.TYPE_USHORT:
983                     return new ShortInterleavedRaster(sm, db, location);
984             }
985         } else if (sm instanceof SinglePixelPackedSampleModel) {
986             switch(dataType) {
987                 case DataBuffer.TYPE_BYTE:
988                     return new ByteInterleavedRaster(sm, db, location);
989 
990                 case DataBuffer.TYPE_USHORT:
991                     return new ShortInterleavedRaster(sm, db, location);
992 
993                 case DataBuffer.TYPE_INT:
994                     return new IntegerInterleavedRaster(sm, db, location);
995             }
996         } else if (sm instanceof MultiPixelPackedSampleModel &&
997                    dataType == DataBuffer.TYPE_BYTE &&
998                    sm.getSampleSize(0) < 8) {
999             return new BytePackedRaster(sm, db, location);
1000         }
1001 
1002         // we couldn't do anything special - do the generic thing
1003 
1004         return new SunWritableRaster(sm,db,location);
1005     }
1006 
1007     /**
1008      *  Constructs a Raster with the given SampleModel.  The Raster's
1009      *  upper left corner is origin and it is the same size as the
1010      *  SampleModel.  A DataBuffer large enough to describe the
1011      *  Raster is automatically created.
1012      *  @param sampleModel     The SampleModel that specifies the layout
1013      *  @param origin          The Point that specified the origin
1014      *  @throws RasterFormatException if computing either
1015      *          <code>origin.x + sampleModel.getWidth()</code> or
1016      *          <code>origin.y + sampleModel.getHeight()</code> results in
1017      *          integer overflow
1018      *  @throws NullPointerException either <code>sampleModel</code> or
1019      *          <code>origin</code> is null
1020      */
1021     protected Raster(SampleModel sampleModel,
1022                      Point origin) {
1023         this(sampleModel,
1024              sampleModel.createDataBuffer(),
1025              new Rectangle(origin.x,
1026                            origin.y,
1027                            sampleModel.getWidth(),
1028                            sampleModel.getHeight()),
1029              origin,
1030              null);
1031     }
1032 
1033     /**
1034      *  Constructs a Raster with the given SampleModel and DataBuffer.
1035      *  The Raster's upper left corner is origin and it is the same size
1036      *  as the SampleModel.  The DataBuffer is not initialized and must
1037      *  be compatible with SampleModel.
1038      *  @param sampleModel     The SampleModel that specifies the layout
1039      *  @param dataBuffer      The DataBuffer that contains the image data
1040      *  @param origin          The Point that specifies the origin
1041      *  @throws RasterFormatException if computing either
1042      *          <code>origin.x + sampleModel.getWidth()</code> or
1043      *          <code>origin.y + sampleModel.getHeight()</code> results in
1044      *          integer overflow
1045      *  @throws NullPointerException either <code>sampleModel</code> or
1046      *          <code>origin</code> is null
1047      */
1048     protected Raster(SampleModel sampleModel,
1049                      DataBuffer dataBuffer,
1050                      Point origin) {
1051         this(sampleModel,
1052              dataBuffer,
1053              new Rectangle(origin.x,
1054                            origin.y,
1055                            sampleModel.getWidth(),
1056                            sampleModel.getHeight()),
1057              origin,
1058              null);
1059     }
1060 
1061     /**
1062      * Constructs a Raster with the given SampleModel, DataBuffer, and
1063      * parent.  aRegion specifies the bounding rectangle of the new
1064      * Raster.  When translated into the base Raster's coordinate
1065      * system, aRegion must be contained by the base Raster.
1066      * (The base Raster is the Raster's ancestor which has no parent.)
1067      * sampleModelTranslate specifies the sampleModelTranslateX and
1068      * sampleModelTranslateY values of the new Raster.
1069      *
1070      * Note that this constructor should generally be called by other
1071      * constructors or create methods, it should not be used directly.
1072      * @param sampleModel     The SampleModel that specifies the layout
1073      * @param dataBuffer      The DataBuffer that contains the image data
1074      * @param aRegion         The Rectangle that specifies the image area
1075      * @param sampleModelTranslate  The Point that specifies the translation
1076      *                        from SampleModel to Raster coordinates
1077      * @param parent          The parent (if any) of this raster
1078      * @throws NullPointerException if any of <code>sampleModel</code>,
1079      *         <code>dataBuffer</code>, <code>aRegion</code> or
1080      *         <code>sampleModelTranslate</code> is null
1081      * @throws RasterFormatException if <code>aRegion</code> has width
1082      *         or height less than or equal to zero, or computing either
1083      *         <code>aRegion.x + aRegion.width</code> or
1084      *         <code>aRegion.y + aRegion.height</code> results in integer
1085      *         overflow
1086      */
1087     protected Raster(SampleModel sampleModel,
1088                      DataBuffer dataBuffer,
1089                      Rectangle aRegion,
1090                      Point sampleModelTranslate,
1091                      Raster parent) {
1092 
1093         if ((sampleModel == null) || (dataBuffer == null) ||
1094             (aRegion == null) || (sampleModelTranslate == null)) {
1095             throw new NullPointerException("SampleModel, dataBuffer, aRegion and " +
1096                                            "sampleModelTranslate cannot be null");
1097         }
1098        this.sampleModel = sampleModel;
1099        this.dataBuffer = dataBuffer;
1100        minX = aRegion.x;
1101        minY = aRegion.y;
1102        width = aRegion.width;
1103        height = aRegion.height;
1104        if (width <= 0 || height <= 0) {
1105            throw new RasterFormatException("negative or zero " +
1106                ((width <= 0) ? "width" : "height"));
1107        }
1108        if ((minX + width) < minX) {
1109            throw new RasterFormatException(
1110                "overflow condition for X coordinates of Raster");
1111        }
1112        if ((minY + height) < minY) {
1113            throw new RasterFormatException(
1114                "overflow condition for Y coordinates of Raster");
1115        }
1116 
1117        sampleModelTranslateX = sampleModelTranslate.x;
1118        sampleModelTranslateY = sampleModelTranslate.y;
1119 
1120        numBands = sampleModel.getNumBands();
1121        numDataElements = sampleModel.getNumDataElements();
1122        this.parent = parent;
1123     }
1124 
1125 
1126     /**
1127      * Returns the parent Raster (if any) of this Raster or null.
1128      * @return the parent Raster or <code>null</code>.
1129      */
1130     public Raster getParent() {
1131         return parent;
1132     }
1133 
1134     /**
1135      * Returns the X translation from the coordinate system of the
1136      * SampleModel to that of the Raster.  To convert a pixel's X
1137      * coordinate from the Raster coordinate system to the SampleModel
1138      * coordinate system, this value must be subtracted.
1139      * @return the X translation from the coordinate space of the
1140      *         Raster's SampleModel to that of the Raster.
1141      */
1142     final public int getSampleModelTranslateX() {
1143         return sampleModelTranslateX;
1144     }
1145 
1146     /**
1147      * Returns the Y translation from the coordinate system of the
1148      * SampleModel to that of the Raster.  To convert a pixel's Y
1149      * coordinate from the Raster coordinate system to the SampleModel
1150      * coordinate system, this value must be subtracted.
1151      * @return the Y translation from the coordinate space of the
1152      *         Raster's SampleModel to that of the Raster.
1153      */
1154     final public int getSampleModelTranslateY() {
1155         return sampleModelTranslateY;
1156     }
1157 
1158     /**
1159      * Create a compatible WritableRaster the same size as this Raster with
1160      * the same SampleModel and a new initialized DataBuffer.
1161      * @return a compatible <code>WritableRaster</code> with the same sample
1162      *         model and a new data buffer.
1163      */
1164     public WritableRaster createCompatibleWritableRaster() {
1165         return new SunWritableRaster(sampleModel, new Point(0,0));
1166     }
1167 
1168     /**
1169      * Create a compatible WritableRaster with the specified size, a new
1170      * SampleModel, and a new initialized DataBuffer.
1171      * @param w the specified width of the new <code>WritableRaster</code>
1172      * @param h the specified height of the new <code>WritableRaster</code>
1173      * @return a compatible <code>WritableRaster</code> with the specified
1174      *         size and a new sample model and data buffer.
1175      * @exception RasterFormatException if the width or height is less than
1176      *                               or equal to zero.
1177      */
1178     public WritableRaster createCompatibleWritableRaster(int w, int h) {
1179         if (w <= 0 || h <=0) {
1180             throw new RasterFormatException("negative " +
1181                                           ((w <= 0) ? "width" : "height"));
1182         }
1183 
1184         SampleModel sm = sampleModel.createCompatibleSampleModel(w,h);
1185 
1186         return new SunWritableRaster(sm, new Point(0,0));
1187     }
1188 
1189     /**
1190      * Create a compatible WritableRaster with location (minX, minY)
1191      * and size (width, height) specified by rect, a
1192      * new SampleModel, and a new initialized DataBuffer.
1193      * @param rect a <code>Rectangle</code> that specifies the size and
1194      *        location of the <code>WritableRaster</code>
1195      * @return a compatible <code>WritableRaster</code> with the specified
1196      *         size and location and a new sample model and data buffer.
1197      * @throws RasterFormatException if <code>rect</code> has width
1198      *         or height less than or equal to zero, or computing either
1199      *         <code>rect.x + rect.width</code> or
1200      *         <code>rect.y + rect.height</code> results in integer
1201      *         overflow
1202      * @throws NullPointerException if <code>rect</code> is null
1203      */
1204     public WritableRaster createCompatibleWritableRaster(Rectangle rect) {
1205         if (rect == null) {
1206             throw new NullPointerException("Rect cannot be null");
1207         }
1208         return createCompatibleWritableRaster(rect.x, rect.y,
1209                                               rect.width, rect.height);
1210     }
1211 
1212     /**
1213      * Create a compatible WritableRaster with the specified
1214      * location (minX, minY) and size (width, height), a
1215      * new SampleModel, and a new initialized DataBuffer.
1216      * @param x the X coordinate of the upper-left corner of
1217      *        the <code>WritableRaster</code>
1218      * @param y the Y coordinate of the upper-left corner of
1219      *        the <code>WritableRaster</code>
1220      * @param w the specified width of the <code>WritableRaster</code>
1221      * @param h the specified height of the <code>WritableRaster</code>
1222      * @return a compatible <code>WritableRaster</code> with the specified
1223      *         size and location and a new sample model and data buffer.
1224      * @throws RasterFormatException if <code>w</code> or <code>h</code>
1225      *         is less than or equal to zero, or computing either
1226      *         <code>x + w</code> or
1227      *         <code>y + h</code> results in integer
1228      *         overflow
1229      */
1230     public WritableRaster createCompatibleWritableRaster(int x, int y,
1231                                                          int w, int h) {
1232         WritableRaster ret = createCompatibleWritableRaster(w, h);
1233         return ret.createWritableChild(0,0,w,h,x,y,null);
1234     }
1235 
1236     /**
1237      * Create a Raster with the same size, SampleModel and DataBuffer
1238      * as this one, but with a different location.  The new Raster
1239      * will possess a reference to the current Raster, accessible
1240      * through its getParent() method.
1241      *
1242      * @param childMinX the X coordinate of the upper-left
1243      *        corner of the new <code>Raster</code>
1244      * @param childMinY the Y coordinate of the upper-left
1245      *        corner of the new <code>Raster</code>
1246      * @return a new <code>Raster</code> with the same size, SampleModel,
1247      *         and DataBuffer as this <code>Raster</code>, but with the
1248      *         specified location.
1249      * @throws RasterFormatException if  computing either
1250      *         <code>childMinX + this.getWidth()</code> or
1251      *         <code>childMinY + this.getHeight()</code> results in integer
1252      *         overflow
1253      */
1254     public Raster createTranslatedChild(int childMinX, int childMinY) {
1255         return createChild(minX,minY,width,height,
1256                            childMinX,childMinY,null);
1257     }
1258 
1259     /**
1260      * Returns a new Raster which shares all or part of this Raster's
1261      * DataBuffer.  The new Raster will possess a reference to the
1262      * current Raster, accessible through its getParent() method.
1263      *
1264      * <p> The parentX, parentY, width and height parameters
1265      * form a Rectangle in this Raster's coordinate space,
1266      * indicating the area of pixels to be shared.  An error will
1267      * be thrown if this Rectangle is not contained with the bounds
1268      * of the current Raster.
1269      *
1270      * <p> The new Raster may additionally be translated to a
1271      * different coordinate system for the plane than that used by the current
1272      * Raster.  The childMinX and childMinY parameters give the new
1273      * (x, y) coordinate of the upper-left pixel of the returned
1274      * Raster; the coordinate (childMinX, childMinY) in the new Raster
1275      * will map to the same pixel as the coordinate (parentX, parentY)
1276      * in the current Raster.
1277      *
1278      * <p> The new Raster may be defined to contain only a subset of
1279      * the bands of the current Raster, possibly reordered, by means
1280      * of the bandList parameter.  If bandList is null, it is taken to
1281      * include all of the bands of the current Raster in their current
1282      * order.
1283      *
1284      * <p> To create a new Raster that contains a subregion of the current
1285      * Raster, but shares its coordinate system and bands,
1286      * this method should be called with childMinX equal to parentX,
1287      * childMinY equal to parentY, and bandList equal to null.
1288      *
1289      * @param parentX The X coordinate of the upper-left corner
1290      *        in this Raster's coordinates
1291      * @param parentY The Y coordinate of the upper-left corner
1292      *        in this Raster's coordinates
1293      * @param width      Width of the region starting at (parentX, parentY)
1294      * @param height     Height of the region starting at (parentX, parentY).
1295      * @param childMinX The X coordinate of the upper-left corner
1296      *                   of the returned Raster
1297      * @param childMinY The Y coordinate of the upper-left corner
1298      *                   of the returned Raster
1299      * @param bandList   Array of band indices, or null to use all bands
1300      * @return a new <code>Raster</code>.
1301      * @exception RasterFormatException if the specified subregion is outside
1302      *                               of the raster bounds.
1303      * @throws RasterFormatException if <code>width</code> or
1304      *         <code>height</code>
1305      *         is less than or equal to zero, or computing any of
1306      *         <code>parentX + width</code>, <code>parentY + height</code>,
1307      *         <code>childMinX + width</code>, or
1308      *         <code>childMinY + height</code> results in integer
1309      *         overflow
1310      */
1311     public Raster createChild(int parentX, int parentY,
1312                               int width, int height,
1313                               int childMinX, int childMinY,
1314                               int bandList[]) {
1315         if (parentX < this.minX) {
1316             throw new RasterFormatException("parentX lies outside raster");
1317         }
1318         if (parentY < this.minY) {
1319             throw new RasterFormatException("parentY lies outside raster");
1320         }
1321         if ((parentX + width < parentX) ||
1322             (parentX + width > this.width + this.minX)) {
1323             throw new RasterFormatException("(parentX + width) is outside raster");
1324         }
1325         if ((parentY + height < parentY) ||
1326             (parentY + height > this.height + this.minY)) {
1327             throw new RasterFormatException("(parentY + height) is outside raster");
1328         }
1329 
1330         SampleModel subSampleModel;
1331         // Note: the SampleModel for the child Raster should have the same
1332         // width and height as that for the parent, since it represents
1333         // the physical layout of the pixel data.  The child Raster's width
1334         // and height represent a "virtual" view of the pixel data, so
1335         // they may be different than those of the SampleModel.
1336         if (bandList == null) {
1337             subSampleModel = sampleModel;
1338         } else {
1339             subSampleModel = sampleModel.createSubsetSampleModel(bandList);
1340         }
1341 
1342         int deltaX = childMinX - parentX;
1343         int deltaY = childMinY - parentY;
1344 
1345         return new Raster(subSampleModel, getDataBuffer(),
1346                           new Rectangle(childMinX, childMinY, width, height),
1347                           new Point(sampleModelTranslateX + deltaX,
1348                                     sampleModelTranslateY + deltaY), this);
1349     }
1350 
1351     /**
1352      * Returns the bounding Rectangle of this Raster. This function returns
1353      * the same information as getMinX/MinY/Width/Height.
1354      * @return the bounding box of this <code>Raster</code>.
1355      */
1356     public Rectangle getBounds() {
1357         return new Rectangle(minX, minY, width, height);
1358     }
1359 
1360     /** Returns the minimum valid X coordinate of the Raster.
1361      *  @return the minimum x coordinate of this <code>Raster</code>.
1362      */
1363     final public int getMinX() {
1364         return minX;
1365     }
1366 
1367     /** Returns the minimum valid Y coordinate of the Raster.
1368      *  @return the minimum y coordinate of this <code>Raster</code>.
1369      */
1370     final public int getMinY() {
1371         return minY;
1372     }
1373 
1374     /** Returns the width in pixels of the Raster.
1375      *  @return the width of this <code>Raster</code>.
1376      */
1377     final public int getWidth() {
1378         return width;
1379     }
1380 
1381     /** Returns the height in pixels of the Raster.
1382      *  @return the height of this <code>Raster</code>.
1383      */
1384     final public int getHeight() {
1385         return height;
1386     }
1387 
1388     /** Returns the number of bands (samples per pixel) in this Raster.
1389      *  @return the number of bands of this <code>Raster</code>.
1390      */
1391     final public int getNumBands() {
1392         return numBands;
1393     }
1394 
1395     /**
1396      *  Returns the number of data elements needed to transfer one pixel
1397      *  via the getDataElements and setDataElements methods.  When pixels
1398      *  are transferred via these methods, they may be transferred in a
1399      *  packed or unpacked format, depending on the implementation of the
1400      *  underlying SampleModel.  Using these methods, pixels are transferred
1401      *  as an array of getNumDataElements() elements of a primitive type given
1402      *  by getTransferType().  The TransferType may or may not be the same
1403      *  as the storage data type of the DataBuffer.
1404      *  @return the number of data elements.
1405      */
1406     final public int getNumDataElements() {
1407         return sampleModel.getNumDataElements();
1408     }
1409 
1410     /**
1411      *  Returns the TransferType used to transfer pixels via the
1412      *  getDataElements and setDataElements methods.  When pixels
1413      *  are transferred via these methods, they may be transferred in a
1414      *  packed or unpacked format, depending on the implementation of the
1415      *  underlying SampleModel.  Using these methods, pixels are transferred
1416      *  as an array of getNumDataElements() elements of a primitive type given
1417      *  by getTransferType().  The TransferType may or may not be the same
1418      *  as the storage data type of the DataBuffer.  The TransferType will
1419      *  be one of the types defined in DataBuffer.
1420      *  @return this transfer type.
1421      */
1422     final public int getTransferType() {
1423         return sampleModel.getTransferType();
1424     }
1425 
1426     /** Returns the DataBuffer associated with this Raster.
1427      *  @return the <code>DataBuffer</code> of this <code>Raster</code>.
1428      */
1429     public DataBuffer getDataBuffer() {
1430         return dataBuffer;
1431     }
1432 
1433     /** Returns the SampleModel that describes the layout of the image data.
1434      *  @return the <code>SampleModel</code> of this <code>Raster</code>.
1435      */
1436     public SampleModel getSampleModel() {
1437         return sampleModel;
1438     }
1439 
1440     /**
1441      * Returns data for a single pixel in a primitive array of type
1442      * TransferType.  For image data supported by the Java 2D(tm) API,
1443      * this will be one of DataBuffer.TYPE_BYTE, DataBuffer.TYPE_USHORT,
1444      * DataBuffer.TYPE_INT, DataBuffer.TYPE_SHORT, DataBuffer.TYPE_FLOAT,
1445      * or DataBuffer.TYPE_DOUBLE.  Data may be returned in a packed format,
1446      * thus increasing efficiency for data transfers.
1447      * An ArrayIndexOutOfBoundsException may be thrown
1448      * if the coordinates are not in bounds.  However, explicit bounds
1449      * checking is not guaranteed.
1450      * A ClassCastException will be thrown if the input object is non null
1451      * and references anything other than an array of TransferType.
1452      * @see java.awt.image.SampleModel#getDataElements(int, int, Object, DataBuffer)
1453      * @param x        The X coordinate of the pixel location
1454      * @param y        The Y coordinate of the pixel location
1455      * @param outData  An object reference to an array of type defined by
1456      *                 getTransferType() and length getNumDataElements().
1457      *                 If null, an array of appropriate type and size will be
1458      *                 allocated
1459      * @return         An object reference to an array of type defined by
1460      *                 getTransferType() with the requested pixel data.
1461      *
1462      * @throws ArrayIndexOutOfBoundsException if the coordinates are not
1463      * in bounds, or if outData is too small to hold the output.
1464      */
1465     public Object getDataElements(int x, int y, Object outData) {
1466         return sampleModel.getDataElements(x - sampleModelTranslateX,
1467                                            y - sampleModelTranslateY,
1468                                            outData, dataBuffer);
1469     }
1470 
1471     /**
1472      * Returns the pixel data for the specified rectangle of pixels in a
1473      * primitive array of type TransferType.
1474      * For image data supported by the Java 2D API, this
1475      * will be one of DataBuffer.TYPE_BYTE, DataBuffer.TYPE_USHORT,
1476      * DataBuffer.TYPE_INT, DataBuffer.TYPE_SHORT, DataBuffer.TYPE_FLOAT,
1477      * or DataBuffer.TYPE_DOUBLE.  Data may be returned in a packed format,
1478      * thus increasing efficiency for data transfers.
1479      * An ArrayIndexOutOfBoundsException may be thrown
1480      * if the coordinates are not in bounds.  However, explicit bounds
1481      * checking is not guaranteed.
1482      * A ClassCastException will be thrown if the input object is non null
1483      * and references anything other than an array of TransferType.
1484      * @see java.awt.image.SampleModel#getDataElements(int, int, int, int, Object, DataBuffer)
1485      * @param x    The X coordinate of the upper-left pixel location
1486      * @param y    The Y coordinate of the upper-left pixel location
1487      * @param w    Width of the pixel rectangle
1488      * @param h   Height of the pixel rectangle
1489      * @param outData  An object reference to an array of type defined by
1490      *                 getTransferType() and length w*h*getNumDataElements().
1491      *                 If null, an array of appropriate type and size will be
1492      *                 allocated.
1493      * @return         An object reference to an array of type defined by
1494      *                 getTransferType() with the requested pixel data.
1495      *
1496      * @throws ArrayIndexOutOfBoundsException if the coordinates are not
1497      * in bounds, or if outData is too small to hold the output.
1498      */
1499     public Object getDataElements(int x, int y, int w, int h, Object outData) {
1500         return sampleModel.getDataElements(x - sampleModelTranslateX,
1501                                            y - sampleModelTranslateY,
1502                                            w, h, outData, dataBuffer);
1503     }
1504 
1505     /**
1506      * Returns the samples in an array of int for the specified pixel.
1507      * An ArrayIndexOutOfBoundsException may be thrown
1508      * if the coordinates are not in bounds.  However, explicit bounds
1509      * checking is not guaranteed.
1510      * @param x The X coordinate of the pixel location
1511      * @param y The Y coordinate of the pixel location
1512      * @param iArray An optionally preallocated int array
1513      * @return the samples for the specified pixel.
1514      *
1515      * @throws ArrayIndexOutOfBoundsException if the coordinates are not
1516      * in bounds, or if iArray is too small to hold the output.
1517      */
1518     public int[] getPixel(int x, int y, int iArray[]) {
1519         return sampleModel.getPixel(x - sampleModelTranslateX,
1520                                     y - sampleModelTranslateY,
1521                                     iArray, dataBuffer);
1522     }
1523 
1524     /**
1525      * Returns the samples in an array of float for the
1526      * specified pixel.
1527      * An ArrayIndexOutOfBoundsException may be thrown
1528      * if the coordinates are not in bounds.  However, explicit bounds
1529      * checking is not guaranteed.
1530      * @param x The X coordinate of the pixel location
1531      * @param y The Y coordinate of the pixel location
1532      * @param fArray An optionally preallocated float array
1533      * @return the samples for the specified pixel.
1534      *
1535      * @throws ArrayIndexOutOfBoundsException if the coordinates are not
1536      * in bounds, or if fArray is too small to hold the output.
1537      */
1538     public float[] getPixel(int x, int y, float fArray[]) {
1539         return sampleModel.getPixel(x - sampleModelTranslateX,
1540                                     y - sampleModelTranslateY,
1541                                     fArray, dataBuffer);
1542     }
1543 
1544     /**
1545      * Returns the samples in an array of double for the specified pixel.
1546      * An ArrayIndexOutOfBoundsException may be thrown
1547      * if the coordinates are not in bounds.  However, explicit bounds
1548      * checking is not guaranteed.
1549      * @param x The X coordinate of the pixel location
1550      * @param y The Y coordinate of the pixel location
1551      * @param dArray An optionally preallocated double array
1552      * @return the samples for the specified pixel.
1553      *
1554      * @throws ArrayIndexOutOfBoundsException if the coordinates are not
1555      * in bounds, or if dArray is too small to hold the output.
1556      */
1557     public double[] getPixel(int x, int y, double dArray[]) {
1558         return sampleModel.getPixel(x - sampleModelTranslateX,
1559                                     y - sampleModelTranslateY,
1560                                     dArray, dataBuffer);
1561     }
1562 
1563     /**
1564      * Returns an int array containing all samples for a rectangle of pixels,
1565      * one sample per array element.
1566      * An ArrayIndexOutOfBoundsException may be thrown
1567      * if the coordinates are not in bounds.  However, explicit bounds
1568      * checking is not guaranteed.
1569      * @param x      The X coordinate of the upper-left pixel location
1570      * @param y      The Y coordinate of the upper-left pixel location
1571      * @param w      Width of the pixel rectangle
1572      * @param h      Height of the pixel rectangle
1573      * @param iArray An optionally pre-allocated int array
1574      * @return the samples for the specified rectangle of pixels.
1575      *
1576      * @throws ArrayIndexOutOfBoundsException if the coordinates are not
1577      * in bounds, or if iArray is too small to hold the output.
1578      */
1579     public int[] getPixels(int x, int y, int w, int h, int iArray[]) {
1580         return sampleModel.getPixels(x - sampleModelTranslateX,
1581                                      y - sampleModelTranslateY, w, h,
1582                                      iArray, dataBuffer);
1583     }
1584 
1585     /**
1586      * Returns a float array containing all samples for a rectangle of pixels,
1587      * one sample per array element.
1588      * An ArrayIndexOutOfBoundsException may be thrown
1589      * if the coordinates are not in bounds.  However, explicit bounds
1590      * checking is not guaranteed.
1591      * @param x        The X coordinate of the pixel location
1592      * @param y        The Y coordinate of the pixel location
1593      * @param w        Width of the pixel rectangle
1594      * @param h        Height of the pixel rectangle
1595      * @param fArray   An optionally pre-allocated float array
1596      * @return the samples for the specified rectangle of pixels.
1597      *
1598      * @throws ArrayIndexOutOfBoundsException if the coordinates are not
1599      * in bounds, or if fArray is too small to hold the output.
1600      */
1601     public float[] getPixels(int x, int y, int w, int h,
1602                              float fArray[]) {
1603         return sampleModel.getPixels(x - sampleModelTranslateX,
1604                                      y - sampleModelTranslateY, w, h,
1605                                      fArray, dataBuffer);
1606     }
1607 
1608     /**
1609      * Returns a double array containing all samples for a rectangle of pixels,
1610      * one sample per array element.
1611      * An ArrayIndexOutOfBoundsException may be thrown
1612      * if the coordinates are not in bounds.  However, explicit bounds
1613      * checking is not guaranteed.
1614      * @param x        The X coordinate of the upper-left pixel location
1615      * @param y        The Y coordinate of the upper-left pixel location
1616      * @param w        Width of the pixel rectangle
1617      * @param h        Height of the pixel rectangle
1618      * @param dArray   An optionally pre-allocated double array
1619      * @return the samples for the specified rectangle of pixels.
1620      *
1621      * @throws ArrayIndexOutOfBoundsException if the coordinates are not
1622      * in bounds, or if dArray is too small to hold the output.
1623      */
1624     public double[] getPixels(int x, int y, int w, int h,
1625                               double dArray[]) {
1626         return sampleModel.getPixels(x - sampleModelTranslateX,
1627                                      y - sampleModelTranslateY,
1628                                      w, h, dArray, dataBuffer);
1629     }
1630 
1631 
1632     /**
1633      * Returns the sample in a specified band for the pixel located
1634      * at (x,y) as an int.
1635      * An ArrayIndexOutOfBoundsException may be thrown
1636      * if the coordinates are not in bounds.  However, explicit bounds
1637      * checking is not guaranteed.
1638      * @param x        The X coordinate of the pixel location
1639      * @param y        The Y coordinate of the pixel location
1640      * @param b        The band to return
1641      * @return the sample in the specified band for the pixel at the
1642      *         specified coordinate.
1643      *
1644      * @throws ArrayIndexOutOfBoundsException if the coordinates or
1645      * the band index are not in bounds.
1646      */
1647     public int getSample(int x, int y, int b) {
1648         return sampleModel.getSample(x - sampleModelTranslateX,
1649                                      y - sampleModelTranslateY, b,
1650                                      dataBuffer);
1651     }
1652 
1653     /**
1654      * Returns the sample in a specified band
1655      * for the pixel located at (x,y) as a float.
1656      * An ArrayIndexOutOfBoundsException may be thrown
1657      * if the coordinates are not in bounds.  However, explicit bounds
1658      * checking is not guaranteed.
1659      * @param x        The X coordinate of the pixel location
1660      * @param y        The Y coordinate of the pixel location
1661      * @param b        The band to return
1662      * @return the sample in the specified band for the pixel at the
1663      *         specified coordinate.
1664      *
1665      * @throws ArrayIndexOutOfBoundsException if the coordinates or
1666      * the band index are not in bounds.
1667      */
1668     public float getSampleFloat(int x, int y, int b) {
1669         return sampleModel.getSampleFloat(x - sampleModelTranslateX,
1670                                           y - sampleModelTranslateY, b,
1671                                           dataBuffer);
1672     }
1673 
1674     /**
1675      * Returns the sample in a specified band
1676      * for a pixel located at (x,y) as a double.
1677      * An ArrayIndexOutOfBoundsException may be thrown
1678      * if the coordinates are not in bounds.  However, explicit bounds
1679      * checking is not guaranteed.
1680      * @param x        The X coordinate of the pixel location
1681      * @param y        The Y coordinate of the pixel location
1682      * @param b        The band to return
1683      * @return the sample in the specified band for the pixel at the
1684      *         specified coordinate.
1685      *
1686      * @throws ArrayIndexOutOfBoundsException if the coordinates or
1687      * the band index are not in bounds.
1688      */
1689     public double getSampleDouble(int x, int y, int b) {
1690         return sampleModel.getSampleDouble(x - sampleModelTranslateX,
1691                                            y - sampleModelTranslateY,
1692                                            b, dataBuffer);
1693     }
1694 
1695     /**
1696      * Returns the samples for a specified band for the specified rectangle
1697      * of pixels in an int array, one sample per array element.
1698      * An ArrayIndexOutOfBoundsException may be thrown
1699      * if the coordinates are not in bounds.  However, explicit bounds
1700      * checking is not guaranteed.
1701      * @param x        The X coordinate of the upper-left pixel location
1702      * @param y        The Y coordinate of the upper-left pixel location
1703      * @param w        Width of the pixel rectangle
1704      * @param h        Height of the pixel rectangle
1705      * @param b        The band to return
1706      * @param iArray   An optionally pre-allocated int array
1707      * @return the samples for the specified band for the specified
1708      *         rectangle of pixels.
1709      *
1710      * @throws ArrayIndexOutOfBoundsException if the coordinates or
1711      * the band index are not in bounds, or if iArray is too small to
1712      * hold the output.
1713      */
1714     public int[] getSamples(int x, int y, int w, int h, int b,
1715                             int iArray[]) {
1716         return sampleModel.getSamples(x - sampleModelTranslateX,
1717                                       y - sampleModelTranslateY,
1718                                       w, h, b, iArray,
1719                                       dataBuffer);
1720     }
1721 
1722     /**
1723      * Returns the samples for a specified band for the specified rectangle
1724      * of pixels in a float array, one sample per array element.
1725      * An ArrayIndexOutOfBoundsException may be thrown
1726      * if the coordinates are not in bounds.  However, explicit bounds
1727      * checking is not guaranteed.
1728      * @param x        The X coordinate of the upper-left pixel location
1729      * @param y        The Y coordinate of the upper-left pixel location
1730      * @param w        Width of the pixel rectangle
1731      * @param h        Height of the pixel rectangle
1732      * @param b        The band to return
1733      * @param fArray   An optionally pre-allocated float array
1734      * @return the samples for the specified band for the specified
1735      *         rectangle of pixels.
1736      *
1737      * @throws ArrayIndexOutOfBoundsException if the coordinates or
1738      * the band index are not in bounds, or if fArray is too small to
1739      * hold the output.
1740      */
1741     public float[] getSamples(int x, int y, int w, int h, int b,
1742                               float fArray[]) {
1743         return sampleModel.getSamples(x - sampleModelTranslateX,
1744                                       y - sampleModelTranslateY,
1745                                       w, h, b, fArray, dataBuffer);
1746     }
1747 
1748     /**
1749      * Returns the samples for a specified band for a specified rectangle
1750      * of pixels in a double array, one sample per array element.
1751      * An ArrayIndexOutOfBoundsException may be thrown
1752      * if the coordinates are not in bounds.  However, explicit bounds
1753      * checking is not guaranteed.
1754      * @param x        The X coordinate of the upper-left pixel location
1755      * @param y        The Y coordinate of the upper-left pixel location
1756      * @param w        Width of the pixel rectangle
1757      * @param h        Height of the pixel rectangle
1758      * @param b        The band to return
1759      * @param dArray   An optionally pre-allocated double array
1760      * @return the samples for the specified band for the specified
1761      *         rectangle of pixels.
1762      *
1763      * @throws ArrayIndexOutOfBoundsException if the coordinates or
1764      * the band index are not in bounds, or if dArray is too small to
1765      * hold the output.
1766      */
1767     public double[] getSamples(int x, int y, int w, int h, int b,
1768                                double dArray[]) {
1769          return sampleModel.getSamples(x - sampleModelTranslateX,
1770                                        y - sampleModelTranslateY,
1771                                        w, h, b, dArray, dataBuffer);
1772     }
1773 
1774 }