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 private static 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}
186 * Rasters are not supported. To create a 1-band Raster of type
187 * {@code DataBuffer.TYPE_INT}, 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}
196 * @return a WritableRaster object with the specified data type,
197 * width, height and number of bands.
198 * @throws RasterFormatException if {@code w} or {@code h}
199 * is less than or equal to zero, or computing either
200 * {@code location.x + w} or
201 * {@code location.y + h} 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}
228 * Rasters are not supported. To create a 1-band Raster of type
229 * {@code DataBuffer.TYPE_INT}, 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}
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} or {@code h}
244 * is less than or equal to zero, or computing either
245 * {@code location.x + w} or
246 * {@code location.y + h} results in integer
247 * overflow
248 * @throws IllegalArgumentException if {@code dataType} is not
249 * one of the supported data types, which are
250 * {@code DataBuffer.TYPE_BYTE}, or
251 * {@code DataBuffer.TYPE_USHORT}.
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}
298 * @return a WritableRaster object with the specified data type,
299 * width, height and number of bands.
300 * @throws RasterFormatException if {@code w} or {@code h}
301 * is less than or equal to zero, or computing either
302 * {@code location.x + w} or
303 * {@code location.y + h} results in integer
304 * overflow
305 * @throws ArrayIndexOutOfBoundsException if {@code bands}
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}
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} or {@code h}
353 * is less than or equal to zero, or computing either
354 * {@code location.x + w} or
355 * {@code location.y + h} results in integer
356 * overflow
357 * @throws IllegalArgumentException if {@code dataType} is not
358 * one of the supported data types, which are
359 * {@code DataBuffer.TYPE_BYTE},
360 * {@code DataBuffer.TYPE_USHORT}
361 * or {@code DataBuffer.TYPE_INT}
362 * @throws ArrayIndexOutOfBoundsException if {@code bankIndices}
363 * or {@code bandOffsets} is {@code null}
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) + // first (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}
438 * @return a WritableRaster object with the specified data type,
439 * width, height, and band masks.
440 * @throws RasterFormatException if {@code w} or {@code h}
441 * is less than or equal to zero, or computing either
442 * {@code location.x + w} or
443 * {@code location.y + h} results in integer
444 * overflow
445 * @throws IllegalArgumentException if {@code dataType} is not
446 * one of the supported data types, which are
447 * {@code DataBuffer.TYPE_BYTE},
448 * {@code DataBuffer.TYPE_USHORT}
449 * or {@code DataBuffer.TYPE_INT}
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}
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} or {@code h}
506 * is less than or equal to zero, or computing either
507 * {@code location.x + w} or
508 * {@code location.y + h} results in integer
509 * overflow
510 * @throws IllegalArgumentException if the product of
511 * {@code bitsPerBand} and {@code bands} is
512 * greater than the number of bits held by
513 * {@code dataType}
514 * @throws IllegalArgumentException if {@code bitsPerBand} or
515 * {@code bands} is not greater than zero
516 * @throws IllegalArgumentException if {@code dataType} is not
517 * one of the supported data types, which are
518 * {@code DataBuffer.TYPE_BYTE},
519 * {@code DataBuffer.TYPE_USHORT}
520 * or {@code DataBuffer.TYPE_INT}
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}
600 * Rasters are not supported. To create a 1-band Raster of type
601 * {@code DataBuffer.TYPE_INT}, use
602 * Raster.createPackedRaster().
603 * @param dataBuffer the {@code DataBuffer} 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}
611 * @return a WritableRaster object with the specified
612 * {@code DataBuffer}, width, height, scanline stride,
613 * pixel stride and band offsets.
614 * @throws RasterFormatException if {@code w} or {@code h}
615 * is less than or equal to zero, or computing either
616 * {@code location.x + w} or
617 * {@code location.y + h} results in integer
618 * overflow
619 * @throws IllegalArgumentException if {@code dataType} is not
620 * one of the supported data types, which are
621 * {@code DataBuffer.TYPE_BYTE},
622 * {@code DataBuffer.TYPE_USHORT}
623 * @throws RasterFormatException if {@code dataBuffer} has more
624 * than one bank.
625 * @throws NullPointerException if {@code dataBuffer} 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} 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}
674 * @return a WritableRaster object with the specified
675 * {@code DataBuffer}, width, height, scanline stride,
676 * bank indices and band offsets.
677 * @throws RasterFormatException if {@code w} or {@code h}
678 * is less than or equal to zero, or computing either
679 * {@code location.x + w} or
680 * {@code location.y + h} results in integer
681 * overflow
682 * @throws IllegalArgumentException if {@code dataType} is not
683 * one of the supported data types, which are
684 * {@code DataBuffer.TYPE_BYTE},
685 * {@code DataBuffer.TYPE_USHORT}
686 * or {@code DataBuffer.TYPE_INT}
687 * @throws NullPointerException if {@code dataBuffer} 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} 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}
743 * @return a WritableRaster object with the specified
744 * {@code DataBuffer}, width, height, scanline stride,
745 * and band masks.
746 * @throws RasterFormatException if {@code w} or {@code h}
747 * is less than or equal to zero, or computing either
748 * {@code location.x + w} or
749 * {@code location.y + h} results in integer
750 * overflow
751 * @throws IllegalArgumentException if {@code dataType} is not
752 * one of the supported data types, which are
753 * {@code DataBuffer.TYPE_BYTE},
754 * {@code DataBuffer.TYPE_USHORT}
755 * or {@code DataBuffer.TYPE_INT}
756 * @throws RasterFormatException if {@code dataBuffer} has more
757 * than one bank.
758 * @throws NullPointerException if {@code dataBuffer} 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} 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}
804 * @return a WritableRaster object with the specified
805 * {@code DataBuffer}, width, height, and
806 * bits per pixel.
807 * @throws RasterFormatException if {@code w} or {@code h}
808 * is less than or equal to zero, or computing either
809 * {@code location.x + w} or
810 * {@code location.y + h} results in integer
811 * overflow
812 * @throws IllegalArgumentException if {@code dataType} is not
813 * one of the supported data types, which are
814 * {@code DataBuffer.TYPE_BYTE},
815 * {@code DataBuffer.TYPE_USHORT}
816 * or {@code DataBuffer.TYPE_INT}
817 * @throws RasterFormatException if {@code dataBuffer} has more
818 * than one bank.
819 * @throws NullPointerException if {@code dataBuffer} 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}
863 * @param db the specified {@code DataBuffer}
864 * @param location the upper-left corner of the {@code Raster}
865 * @return a {@code Raster} with the specified
866 * {@code SampleModel}, {@code DataBuffer}, and
867 * location.
868 * @throws RasterFormatException if computing either
869 * {@code location.x + sm.getWidth()} or
870 * {@code location.y + sm.getHeight()} results in integer
871 * overflow
872 * @throws RasterFormatException if {@code db} has more
873 * than one bank and {@code sm} 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}
926 * @param location the upper-left corner of the
927 * {@code WritableRaster}
928 * @return a {@code WritableRaster} with the specified
929 * {@code SampleModel} and location.
930 * @throws RasterFormatException if computing either
931 * {@code location.x + sm.getWidth()} or
932 * {@code location.y + sm.getHeight()} 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}
949 * @param db the specified {@code DataBuffer}
950 * @param location the upper-left corner of the
951 * {@code WritableRaster}
952 * @return a {@code WritableRaster} with the specified
953 * {@code SampleModel}, {@code DataBuffer}, and
954 * location.
955 * @throws RasterFormatException if computing either
956 * {@code location.x + sm.getWidth()} or
957 * {@code location.y + sm.getHeight()} results in integer
958 * overflow
959 * @throws RasterFormatException if {@code db} has more
960 * than one bank and {@code sm} 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 if (db instanceof DataBufferByte) {
981 return new ByteInterleavedRaster(sm, db, location);
982 }
983 break;
984
985 case DataBuffer.TYPE_USHORT:
986 if (db instanceof DataBufferUShort) {
987 return new ShortInterleavedRaster(sm, db, location);
988 }
989 break;
990 }
991 } else if (sm instanceof SinglePixelPackedSampleModel) {
992 switch(dataType) {
993 case DataBuffer.TYPE_BYTE:
994 if (db instanceof DataBufferByte) {
995 return new ByteInterleavedRaster(sm, db, location);
996 }
997 break;
998
999 case DataBuffer.TYPE_USHORT:
1000 if (db instanceof DataBufferUShort) {
1001 return new ShortInterleavedRaster(sm, db, location);
1002 }
1003 break;
1004
1005 case DataBuffer.TYPE_INT:
1006 if (db instanceof DataBufferInt) {
1007 return new IntegerInterleavedRaster(sm, db, location);
1008 }
1009 break;
1010 }
1011 } else if (sm instanceof MultiPixelPackedSampleModel &&
1012 dataType == DataBuffer.TYPE_BYTE &&
1013 db instanceof DataBufferByte &&
1014 sm.getSampleSize(0) < 8) {
1015 return new BytePackedRaster(sm, db, location);
1016 }
1017
1018 // we couldn't do anything special - do the generic thing
1019 return new SunWritableRaster(sm,db,location);
1020 }
1021
1022 /**
1023 * Constructs a Raster with the given SampleModel. The Raster's
1024 * upper left corner is origin and it is the same size as the
1025 * SampleModel. A DataBuffer large enough to describe the
1026 * Raster is automatically created.
1027 * @param sampleModel The SampleModel that specifies the layout
1028 * @param origin The Point that specified the origin
1029 * @throws RasterFormatException if computing either
1030 * {@code origin.x + sampleModel.getWidth()} or
1031 * {@code origin.y + sampleModel.getHeight()} results in
1032 * integer overflow
1033 * @throws NullPointerException either {@code sampleModel} or
1034 * {@code origin} is null
1035 */
1036 protected Raster(SampleModel sampleModel,
1037 Point origin) {
1038 this(sampleModel,
1039 sampleModel.createDataBuffer(),
1040 new Rectangle(origin.x,
1041 origin.y,
1042 sampleModel.getWidth(),
1043 sampleModel.getHeight()),
1044 origin,
1045 null);
1046 }
1047
1048 /**
1049 * Constructs a Raster with the given SampleModel and DataBuffer.
1050 * The Raster's upper left corner is origin and it is the same size
1051 * as the SampleModel. The DataBuffer is not initialized and must
1052 * be compatible with SampleModel.
1053 * @param sampleModel The SampleModel that specifies the layout
1054 * @param dataBuffer The DataBuffer that contains the image data
1055 * @param origin The Point that specifies the origin
1056 * @throws RasterFormatException if computing either
1057 * {@code origin.x + sampleModel.getWidth()} or
1058 * {@code origin.y + sampleModel.getHeight()} results in
1059 * integer overflow
1060 * @throws NullPointerException either {@code sampleModel} or
1061 * {@code origin} is null
1062 */
1063 protected Raster(SampleModel sampleModel,
1064 DataBuffer dataBuffer,
1065 Point origin) {
1066 this(sampleModel,
1067 dataBuffer,
1068 new Rectangle(origin.x,
1069 origin.y,
1070 sampleModel.getWidth(),
1071 sampleModel.getHeight()),
1072 origin,
1073 null);
1074 }
1075
1076 /**
1077 * Constructs a Raster with the given SampleModel, DataBuffer, and
1078 * parent. aRegion specifies the bounding rectangle of the new
1079 * Raster. When translated into the base Raster's coordinate
1080 * system, aRegion must be contained by the base Raster.
1081 * (The base Raster is the Raster's ancestor which has no parent.)
1082 * sampleModelTranslate specifies the sampleModelTranslateX and
1083 * sampleModelTranslateY values of the new Raster.
1084 *
1085 * Note that this constructor should generally be called by other
1086 * constructors or create methods, it should not be used directly.
1087 * @param sampleModel The SampleModel that specifies the layout
1088 * @param dataBuffer The DataBuffer that contains the image data
1089 * @param aRegion The Rectangle that specifies the image area
1090 * @param sampleModelTranslate The Point that specifies the translation
1091 * from SampleModel to Raster coordinates
1092 * @param parent The parent (if any) of this raster
1093 * @throws NullPointerException if any of {@code sampleModel},
1094 * {@code dataBuffer}, {@code aRegion} or
1095 * {@code sampleModelTranslate} is null
1096 * @throws RasterFormatException if {@code aRegion} has width
1097 * or height less than or equal to zero, or computing either
1098 * {@code aRegion.x + aRegion.width} or
1099 * {@code aRegion.y + aRegion.height} results in integer
1100 * overflow
1101 */
1102 protected Raster(SampleModel sampleModel,
1103 DataBuffer dataBuffer,
1104 Rectangle aRegion,
1105 Point sampleModelTranslate,
1106 Raster parent) {
1107
1108 if ((sampleModel == null) || (dataBuffer == null) ||
1109 (aRegion == null) || (sampleModelTranslate == null)) {
1110 throw new NullPointerException("SampleModel, dataBuffer, aRegion and " +
1111 "sampleModelTranslate cannot be null");
1112 }
1113 this.sampleModel = sampleModel;
1114 this.dataBuffer = dataBuffer;
1115 minX = aRegion.x;
1116 minY = aRegion.y;
1117 width = aRegion.width;
1118 height = aRegion.height;
1119 if (width <= 0 || height <= 0) {
1120 throw new RasterFormatException("negative or zero " +
1121 ((width <= 0) ? "width" : "height"));
1122 }
1123 if ((minX + width) < minX) {
1124 throw new RasterFormatException(
1125 "overflow condition for X coordinates of Raster");
1126 }
1127 if ((minY + height) < minY) {
1128 throw new RasterFormatException(
1129 "overflow condition for Y coordinates of Raster");
1130 }
1131
1132 sampleModelTranslateX = sampleModelTranslate.x;
1133 sampleModelTranslateY = sampleModelTranslate.y;
1134
1135 numBands = sampleModel.getNumBands();
1136 numDataElements = sampleModel.getNumDataElements();
1137 this.parent = parent;
1138 }
1139
1140
1141 /**
1142 * Returns the parent Raster (if any) of this Raster or null.
1143 * @return the parent Raster or {@code null}.
1144 */
1145 public Raster getParent() {
1146 return parent;
1147 }
1148
1149 /**
1150 * Returns the X translation from the coordinate system of the
1151 * SampleModel to that of the Raster. To convert a pixel's X
1152 * coordinate from the Raster coordinate system to the SampleModel
1153 * coordinate system, this value must be subtracted.
1154 * @return the X translation from the coordinate space of the
1155 * Raster's SampleModel to that of the Raster.
1156 */
1157 public final int getSampleModelTranslateX() {
1158 return sampleModelTranslateX;
1159 }
1160
1161 /**
1162 * Returns the Y translation from the coordinate system of the
1163 * SampleModel to that of the Raster. To convert a pixel's Y
1164 * coordinate from the Raster coordinate system to the SampleModel
1165 * coordinate system, this value must be subtracted.
1166 * @return the Y translation from the coordinate space of the
1167 * Raster's SampleModel to that of the Raster.
1168 */
1169 public final int getSampleModelTranslateY() {
1170 return sampleModelTranslateY;
1171 }
1172
1173 /**
1174 * Create a compatible WritableRaster the same size as this Raster with
1175 * the same SampleModel and a new initialized DataBuffer.
1176 * @return a compatible {@code WritableRaster} with the same sample
1177 * model and a new data buffer.
1178 */
1179 public WritableRaster createCompatibleWritableRaster() {
1180 return new SunWritableRaster(sampleModel, new Point(0,0));
1181 }
1182
1183 /**
1184 * Create a compatible WritableRaster with the specified size, a new
1185 * SampleModel, and a new initialized DataBuffer.
1186 * @param w the specified width of the new {@code WritableRaster}
1187 * @param h the specified height of the new {@code WritableRaster}
1188 * @return a compatible {@code WritableRaster} with the specified
1189 * size and a new sample model and data buffer.
1190 * @exception RasterFormatException if the width or height is less than
1191 * or equal to zero.
1192 */
1193 public WritableRaster createCompatibleWritableRaster(int w, int h) {
1194 if (w <= 0 || h <=0) {
1195 throw new RasterFormatException("negative " +
1196 ((w <= 0) ? "width" : "height"));
1197 }
1198
1199 SampleModel sm = sampleModel.createCompatibleSampleModel(w,h);
1200
1201 return new SunWritableRaster(sm, new Point(0,0));
1202 }
1203
1204 /**
1205 * Create a compatible WritableRaster with location (minX, minY)
1206 * and size (width, height) specified by rect, a
1207 * new SampleModel, and a new initialized DataBuffer.
1208 * @param rect a {@code Rectangle} that specifies the size and
1209 * location of the {@code WritableRaster}
1210 * @return a compatible {@code WritableRaster} with the specified
1211 * size and location and a new sample model and data buffer.
1212 * @throws RasterFormatException if {@code rect} has width
1213 * or height less than or equal to zero, or computing either
1214 * {@code rect.x + rect.width} or
1215 * {@code rect.y + rect.height} results in integer
1216 * overflow
1217 * @throws NullPointerException if {@code rect} is null
1218 */
1219 public WritableRaster createCompatibleWritableRaster(Rectangle rect) {
1220 if (rect == null) {
1221 throw new NullPointerException("Rect cannot be null");
1222 }
1223 return createCompatibleWritableRaster(rect.x, rect.y,
1224 rect.width, rect.height);
1225 }
1226
1227 /**
1228 * Create a compatible WritableRaster with the specified
1229 * location (minX, minY) and size (width, height), a
1230 * new SampleModel, and a new initialized DataBuffer.
1231 * @param x the X coordinate of the upper-left corner of
1232 * the {@code WritableRaster}
1233 * @param y the Y coordinate of the upper-left corner of
1234 * the {@code WritableRaster}
1235 * @param w the specified width of the {@code WritableRaster}
1236 * @param h the specified height of the {@code WritableRaster}
1237 * @return a compatible {@code WritableRaster} with the specified
1238 * size and location and a new sample model and data buffer.
1239 * @throws RasterFormatException if {@code w} or {@code h}
1240 * is less than or equal to zero, or computing either
1241 * {@code x + w} or
1242 * {@code y + h} results in integer
1243 * overflow
1244 */
1245 public WritableRaster createCompatibleWritableRaster(int x, int y,
1246 int w, int h) {
1247 WritableRaster ret = createCompatibleWritableRaster(w, h);
1248 return ret.createWritableChild(0,0,w,h,x,y,null);
1249 }
1250
1251 /**
1252 * Create a Raster with the same size, SampleModel and DataBuffer
1253 * as this one, but with a different location. The new Raster
1254 * will possess a reference to the current Raster, accessible
1255 * through its getParent() method.
1256 *
1257 * @param childMinX the X coordinate of the upper-left
1258 * corner of the new {@code Raster}
1259 * @param childMinY the Y coordinate of the upper-left
1260 * corner of the new {@code Raster}
1261 * @return a new {@code Raster} with the same size, SampleModel,
1262 * and DataBuffer as this {@code Raster}, but with the
1263 * specified location.
1264 * @throws RasterFormatException if computing either
1265 * {@code childMinX + this.getWidth()} or
1266 * {@code childMinY + this.getHeight()} results in integer
1267 * overflow
1268 */
1269 public Raster createTranslatedChild(int childMinX, int childMinY) {
1270 return createChild(minX,minY,width,height,
1271 childMinX,childMinY,null);
1272 }
1273
1274 /**
1275 * Returns a new Raster which shares all or part of this Raster's
1276 * DataBuffer. The new Raster will possess a reference to the
1277 * current Raster, accessible through its getParent() method.
1278 *
1279 * <p> The parentX, parentY, width and height parameters
1280 * form a Rectangle in this Raster's coordinate space,
1281 * indicating the area of pixels to be shared. An error will
1282 * be thrown if this Rectangle is not contained with the bounds
1283 * of the current Raster.
1284 *
1285 * <p> The new Raster may additionally be translated to a
1286 * different coordinate system for the plane than that used by the current
1287 * Raster. The childMinX and childMinY parameters give the new
1288 * (x, y) coordinate of the upper-left pixel of the returned
1289 * Raster; the coordinate (childMinX, childMinY) in the new Raster
1290 * will map to the same pixel as the coordinate (parentX, parentY)
1291 * in the current Raster.
1292 *
1293 * <p> The new Raster may be defined to contain only a subset of
1294 * the bands of the current Raster, possibly reordered, by means
1295 * of the bandList parameter. If bandList is null, it is taken to
1296 * include all of the bands of the current Raster in their current
1297 * order.
1298 *
1299 * <p> To create a new Raster that contains a subregion of the current
1300 * Raster, but shares its coordinate system and bands,
1301 * this method should be called with childMinX equal to parentX,
1302 * childMinY equal to parentY, and bandList equal to null.
1303 *
1304 * @param parentX The X coordinate of the upper-left corner
1305 * in this Raster's coordinates
1306 * @param parentY The Y coordinate of the upper-left corner
1307 * in this Raster's coordinates
1308 * @param width Width of the region starting at (parentX, parentY)
1309 * @param height Height of the region starting at (parentX, parentY).
1310 * @param childMinX The X coordinate of the upper-left corner
1311 * of the returned Raster
1312 * @param childMinY The Y coordinate of the upper-left corner
1313 * of the returned Raster
1314 * @param bandList Array of band indices, or null to use all bands
1315 * @return a new {@code Raster}.
1316 * @exception RasterFormatException if the specified subregion is outside
1317 * of the raster bounds.
1318 * @throws RasterFormatException if {@code width} or
1319 * {@code height}
1320 * is less than or equal to zero, or computing any of
1321 * {@code parentX + width}, {@code parentY + height},
1322 * {@code childMinX + width}, or
1323 * {@code childMinY + height} results in integer
1324 * overflow
1325 */
1326 public Raster createChild(int parentX, int parentY,
1327 int width, int height,
1328 int childMinX, int childMinY,
1329 int bandList[]) {
1330 if (parentX < this.minX) {
1331 throw new RasterFormatException("parentX lies outside raster");
1332 }
1333 if (parentY < this.minY) {
1334 throw new RasterFormatException("parentY lies outside raster");
1335 }
1336 if ((parentX + width < parentX) ||
1337 (parentX + width > this.width + this.minX)) {
1338 throw new RasterFormatException("(parentX + width) is outside raster");
1339 }
1340 if ((parentY + height < parentY) ||
1341 (parentY + height > this.height + this.minY)) {
1342 throw new RasterFormatException("(parentY + height) is outside raster");
1343 }
1344
1345 SampleModel subSampleModel;
1346 // Note: the SampleModel for the child Raster should have the same
1347 // width and height as that for the parent, since it represents
1348 // the physical layout of the pixel data. The child Raster's width
1349 // and height represent a "virtual" view of the pixel data, so
1350 // they may be different than those of the SampleModel.
1351 if (bandList == null) {
1352 subSampleModel = sampleModel;
1353 } else {
1354 subSampleModel = sampleModel.createSubsetSampleModel(bandList);
1355 }
1356
1357 int deltaX = childMinX - parentX;
1358 int deltaY = childMinY - parentY;
1359
1360 return new Raster(subSampleModel, getDataBuffer(),
1361 new Rectangle(childMinX, childMinY, width, height),
1362 new Point(sampleModelTranslateX + deltaX,
1363 sampleModelTranslateY + deltaY), this);
1364 }
1365
1366 /**
1367 * Returns the bounding Rectangle of this Raster. This function returns
1368 * the same information as getMinX/MinY/Width/Height.
1369 * @return the bounding box of this {@code Raster}.
1370 */
1371 public Rectangle getBounds() {
1372 return new Rectangle(minX, minY, width, height);
1373 }
1374
1375 /** Returns the minimum valid X coordinate of the Raster.
1376 * @return the minimum x coordinate of this {@code Raster}.
1377 */
1378 public final int getMinX() {
1379 return minX;
1380 }
1381
1382 /** Returns the minimum valid Y coordinate of the Raster.
1383 * @return the minimum y coordinate of this {@code Raster}.
1384 */
1385 public final int getMinY() {
1386 return minY;
1387 }
1388
1389 /** Returns the width in pixels of the Raster.
1390 * @return the width of this {@code Raster}.
1391 */
1392 public final int getWidth() {
1393 return width;
1394 }
1395
1396 /** Returns the height in pixels of the Raster.
1397 * @return the height of this {@code Raster}.
1398 */
1399 public final int getHeight() {
1400 return height;
1401 }
1402
1403 /** Returns the number of bands (samples per pixel) in this Raster.
1404 * @return the number of bands of this {@code Raster}.
1405 */
1406 public final int getNumBands() {
1407 return numBands;
1408 }
1409
1410 /**
1411 * Returns the number of data elements needed to transfer one pixel
1412 * via the 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.
1419 * @return the number of data elements.
1420 */
1421 public final int getNumDataElements() {
1422 return sampleModel.getNumDataElements();
1423 }
1424
1425 /**
1426 * Returns the TransferType used to transfer pixels via the
1427 * getDataElements and setDataElements methods. When pixels
1428 * are transferred via these methods, they may be transferred in a
1429 * packed or unpacked format, depending on the implementation of the
1430 * underlying SampleModel. Using these methods, pixels are transferred
1431 * as an array of getNumDataElements() elements of a primitive type given
1432 * by getTransferType(). The TransferType may or may not be the same
1433 * as the storage data type of the DataBuffer. The TransferType will
1434 * be one of the types defined in DataBuffer.
1435 * @return this transfer type.
1436 */
1437 public final int getTransferType() {
1438 return sampleModel.getTransferType();
1439 }
1440
1441 /** Returns the DataBuffer associated with this Raster.
1442 * @return the {@code DataBuffer} of this {@code Raster}.
1443 */
1444 public DataBuffer getDataBuffer() {
1445 return dataBuffer;
1446 }
1447
1448 /** Returns the SampleModel that describes the layout of the image data.
1449 * @return the {@code SampleModel} of this {@code Raster}.
1450 */
1451 public SampleModel getSampleModel() {
1452 return sampleModel;
1453 }
1454
1455 /**
1456 * Returns data for a single pixel in a primitive array of type
1457 * TransferType. For image data supported by the Java 2D(tm) API,
1458 * this will be one of DataBuffer.TYPE_BYTE, DataBuffer.TYPE_USHORT,
1459 * DataBuffer.TYPE_INT, DataBuffer.TYPE_SHORT, DataBuffer.TYPE_FLOAT,
1460 * or DataBuffer.TYPE_DOUBLE. Data may be returned in a packed format,
1461 * thus increasing efficiency for data transfers.
1462 * An ArrayIndexOutOfBoundsException may be thrown
1463 * if the coordinates are not in bounds. However, explicit bounds
1464 * checking is not guaranteed.
1465 * A ClassCastException will be thrown if the input object is non null
1466 * and references anything other than an array of TransferType.
1467 * @see java.awt.image.SampleModel#getDataElements(int, int, Object, DataBuffer)
1468 * @param x The X coordinate of the pixel location
1469 * @param y The Y coordinate of the pixel location
1470 * @param outData An object reference to an array of type defined by
1471 * getTransferType() and length getNumDataElements().
1472 * If null, an array of appropriate type and size will be
1473 * allocated
1474 * @return An object reference to an array of type defined by
1475 * getTransferType() with the requested pixel data.
1476 *
1477 * @throws ArrayIndexOutOfBoundsException if the coordinates are not
1478 * in bounds, or if outData is too small to hold the output.
1479 */
1480 public Object getDataElements(int x, int y, Object outData) {
1481 return sampleModel.getDataElements(x - sampleModelTranslateX,
1482 y - sampleModelTranslateY,
1483 outData, dataBuffer);
1484 }
1485
1486 /**
1487 * Returns the pixel data for the specified rectangle of pixels in a
1488 * primitive array of type TransferType.
1489 * For image data supported by the Java 2D API, this
1490 * will be one of DataBuffer.TYPE_BYTE, DataBuffer.TYPE_USHORT,
1491 * DataBuffer.TYPE_INT, DataBuffer.TYPE_SHORT, DataBuffer.TYPE_FLOAT,
1492 * or DataBuffer.TYPE_DOUBLE. Data may be returned in a packed format,
1493 * thus increasing efficiency for data transfers.
1494 * An ArrayIndexOutOfBoundsException may be thrown
1495 * if the coordinates are not in bounds. However, explicit bounds
1496 * checking is not guaranteed.
1497 * A ClassCastException will be thrown if the input object is non null
1498 * and references anything other than an array of TransferType.
1499 * @see java.awt.image.SampleModel#getDataElements(int, int, int, int, Object, DataBuffer)
1500 * @param x The X coordinate of the upper-left pixel location
1501 * @param y The Y coordinate of the upper-left pixel location
1502 * @param w Width of the pixel rectangle
1503 * @param h Height of the pixel rectangle
1504 * @param outData An object reference to an array of type defined by
1505 * getTransferType() and length w*h*getNumDataElements().
1506 * If null, an array of appropriate type and size will be
1507 * allocated.
1508 * @return An object reference to an array of type defined by
1509 * getTransferType() with the requested pixel data.
1510 *
1511 * @throws ArrayIndexOutOfBoundsException if the coordinates are not
1512 * in bounds, or if outData is too small to hold the output.
1513 */
1514 public Object getDataElements(int x, int y, int w, int h, Object outData) {
1515 return sampleModel.getDataElements(x - sampleModelTranslateX,
1516 y - sampleModelTranslateY,
1517 w, h, outData, dataBuffer);
1518 }
1519
1520 /**
1521 * Returns the samples in an array of int for the specified pixel.
1522 * An ArrayIndexOutOfBoundsException may be thrown
1523 * if the coordinates are not in bounds. However, explicit bounds
1524 * checking is not guaranteed.
1525 * @param x The X coordinate of the pixel location
1526 * @param y The Y coordinate of the pixel location
1527 * @param iArray An optionally preallocated int array
1528 * @return the samples for the specified pixel.
1529 *
1530 * @throws ArrayIndexOutOfBoundsException if the coordinates are not
1531 * in bounds, or if iArray is too small to hold the output.
1532 */
1533 public int[] getPixel(int x, int y, int iArray[]) {
1534 return sampleModel.getPixel(x - sampleModelTranslateX,
1535 y - sampleModelTranslateY,
1536 iArray, dataBuffer);
1537 }
1538
1539 /**
1540 * Returns the samples in an array of float for the
1541 * specified pixel.
1542 * An ArrayIndexOutOfBoundsException may be thrown
1543 * if the coordinates are not in bounds. However, explicit bounds
1544 * checking is not guaranteed.
1545 * @param x The X coordinate of the pixel location
1546 * @param y The Y coordinate of the pixel location
1547 * @param fArray An optionally preallocated float array
1548 * @return the samples for the specified pixel.
1549 *
1550 * @throws ArrayIndexOutOfBoundsException if the coordinates are not
1551 * in bounds, or if fArray is too small to hold the output.
1552 */
1553 public float[] getPixel(int x, int y, float fArray[]) {
1554 return sampleModel.getPixel(x - sampleModelTranslateX,
1555 y - sampleModelTranslateY,
1556 fArray, dataBuffer);
1557 }
1558
1559 /**
1560 * Returns the samples in an array of double for the specified pixel.
1561 * An ArrayIndexOutOfBoundsException may be thrown
1562 * if the coordinates are not in bounds. However, explicit bounds
1563 * checking is not guaranteed.
1564 * @param x The X coordinate of the pixel location
1565 * @param y The Y coordinate of the pixel location
1566 * @param dArray An optionally preallocated double array
1567 * @return the samples for the specified pixel.
1568 *
1569 * @throws ArrayIndexOutOfBoundsException if the coordinates are not
1570 * in bounds, or if dArray is too small to hold the output.
1571 */
1572 public double[] getPixel(int x, int y, double dArray[]) {
1573 return sampleModel.getPixel(x - sampleModelTranslateX,
1574 y - sampleModelTranslateY,
1575 dArray, dataBuffer);
1576 }
1577
1578 /**
1579 * Returns an int array containing all samples for a rectangle of pixels,
1580 * one sample per array element.
1581 * An ArrayIndexOutOfBoundsException may be thrown
1582 * if the coordinates are not in bounds. However, explicit bounds
1583 * checking is not guaranteed.
1584 * @param x The X coordinate of the upper-left pixel location
1585 * @param y The Y coordinate of the upper-left pixel location
1586 * @param w Width of the pixel rectangle
1587 * @param h Height of the pixel rectangle
1588 * @param iArray An optionally pre-allocated int array
1589 * @return the samples for the specified rectangle of pixels.
1590 *
1591 * @throws ArrayIndexOutOfBoundsException if the coordinates are not
1592 * in bounds, or if iArray is too small to hold the output.
1593 */
1594 public int[] getPixels(int x, int y, int w, int h, int iArray[]) {
1595 return sampleModel.getPixels(x - sampleModelTranslateX,
1596 y - sampleModelTranslateY, w, h,
1597 iArray, dataBuffer);
1598 }
1599
1600 /**
1601 * Returns a float array containing all samples for a rectangle of pixels,
1602 * one sample per array element.
1603 * An ArrayIndexOutOfBoundsException may be thrown
1604 * if the coordinates are not in bounds. However, explicit bounds
1605 * checking is not guaranteed.
1606 * @param x The X coordinate of the pixel location
1607 * @param y The Y coordinate of the pixel location
1608 * @param w Width of the pixel rectangle
1609 * @param h Height of the pixel rectangle
1610 * @param fArray An optionally pre-allocated float array
1611 * @return the samples for the specified rectangle of pixels.
1612 *
1613 * @throws ArrayIndexOutOfBoundsException if the coordinates are not
1614 * in bounds, or if fArray is too small to hold the output.
1615 */
1616 public float[] getPixels(int x, int y, int w, int h,
1617 float fArray[]) {
1618 return sampleModel.getPixels(x - sampleModelTranslateX,
1619 y - sampleModelTranslateY, w, h,
1620 fArray, dataBuffer);
1621 }
1622
1623 /**
1624 * Returns a double array containing all samples for a rectangle of pixels,
1625 * one sample per array element.
1626 * An ArrayIndexOutOfBoundsException may be thrown
1627 * if the coordinates are not in bounds. However, explicit bounds
1628 * checking is not guaranteed.
1629 * @param x The X coordinate of the upper-left pixel location
1630 * @param y The Y coordinate of the upper-left pixel location
1631 * @param w Width of the pixel rectangle
1632 * @param h Height of the pixel rectangle
1633 * @param dArray An optionally pre-allocated double array
1634 * @return the samples for the specified rectangle of pixels.
1635 *
1636 * @throws ArrayIndexOutOfBoundsException if the coordinates are not
1637 * in bounds, or if dArray is too small to hold the output.
1638 */
1639 public double[] getPixels(int x, int y, int w, int h,
1640 double dArray[]) {
1641 return sampleModel.getPixels(x - sampleModelTranslateX,
1642 y - sampleModelTranslateY,
1643 w, h, dArray, dataBuffer);
1644 }
1645
1646
1647 /**
1648 * Returns the sample in a specified band for the pixel located
1649 * at (x,y) as an int.
1650 * An ArrayIndexOutOfBoundsException may be thrown
1651 * if the coordinates are not in bounds. However, explicit bounds
1652 * checking is not guaranteed.
1653 * @param x The X coordinate of the pixel location
1654 * @param y The Y coordinate of the pixel location
1655 * @param b The band to return
1656 * @return the sample in the specified band for the pixel at the
1657 * specified coordinate.
1658 *
1659 * @throws ArrayIndexOutOfBoundsException if the coordinates or
1660 * the band index are not in bounds.
1661 */
1662 public int getSample(int x, int y, int b) {
1663 return sampleModel.getSample(x - sampleModelTranslateX,
1664 y - sampleModelTranslateY, b,
1665 dataBuffer);
1666 }
1667
1668 /**
1669 * Returns the sample in a specified band
1670 * for the pixel located at (x,y) as a float.
1671 * An ArrayIndexOutOfBoundsException may be thrown
1672 * if the coordinates are not in bounds. However, explicit bounds
1673 * checking is not guaranteed.
1674 * @param x The X coordinate of the pixel location
1675 * @param y The Y coordinate of the pixel location
1676 * @param b The band to return
1677 * @return the sample in the specified band for the pixel at the
1678 * specified coordinate.
1679 *
1680 * @throws ArrayIndexOutOfBoundsException if the coordinates or
1681 * the band index are not in bounds.
1682 */
1683 public float getSampleFloat(int x, int y, int b) {
1684 return sampleModel.getSampleFloat(x - sampleModelTranslateX,
1685 y - sampleModelTranslateY, b,
1686 dataBuffer);
1687 }
1688
1689 /**
1690 * Returns the sample in a specified band
1691 * for a pixel located at (x,y) as a double.
1692 * An ArrayIndexOutOfBoundsException may be thrown
1693 * if the coordinates are not in bounds. However, explicit bounds
1694 * checking is not guaranteed.
1695 * @param x The X coordinate of the pixel location
1696 * @param y The Y coordinate of the pixel location
1697 * @param b The band to return
1698 * @return the sample in the specified band for the pixel at the
1699 * specified coordinate.
1700 *
1701 * @throws ArrayIndexOutOfBoundsException if the coordinates or
1702 * the band index are not in bounds.
1703 */
1704 public double getSampleDouble(int x, int y, int b) {
1705 return sampleModel.getSampleDouble(x - sampleModelTranslateX,
1706 y - sampleModelTranslateY,
1707 b, dataBuffer);
1708 }
1709
1710 /**
1711 * Returns the samples for a specified band for the specified rectangle
1712 * of pixels in an int array, one sample per array element.
1713 * An ArrayIndexOutOfBoundsException may be thrown
1714 * if the coordinates are not in bounds. However, explicit bounds
1715 * checking is not guaranteed.
1716 * @param x The X coordinate of the upper-left pixel location
1717 * @param y The Y coordinate of the upper-left pixel location
1718 * @param w Width of the pixel rectangle
1719 * @param h Height of the pixel rectangle
1720 * @param b The band to return
1721 * @param iArray An optionally pre-allocated int array
1722 * @return the samples for the specified band for the specified
1723 * rectangle of pixels.
1724 *
1725 * @throws ArrayIndexOutOfBoundsException if the coordinates or
1726 * the band index are not in bounds, or if iArray is too small to
1727 * hold the output.
1728 */
1729 public int[] getSamples(int x, int y, int w, int h, int b,
1730 int iArray[]) {
1731 return sampleModel.getSamples(x - sampleModelTranslateX,
1732 y - sampleModelTranslateY,
1733 w, h, b, iArray,
1734 dataBuffer);
1735 }
1736
1737 /**
1738 * Returns the samples for a specified band for the specified rectangle
1739 * of pixels in a float array, one sample per array element.
1740 * An ArrayIndexOutOfBoundsException may be thrown
1741 * if the coordinates are not in bounds. However, explicit bounds
1742 * checking is not guaranteed.
1743 * @param x The X coordinate of the upper-left pixel location
1744 * @param y The Y coordinate of the upper-left pixel location
1745 * @param w Width of the pixel rectangle
1746 * @param h Height of the pixel rectangle
1747 * @param b The band to return
1748 * @param fArray An optionally pre-allocated float array
1749 * @return the samples for the specified band for the specified
1750 * rectangle of pixels.
1751 *
1752 * @throws ArrayIndexOutOfBoundsException if the coordinates or
1753 * the band index are not in bounds, or if fArray is too small to
1754 * hold the output.
1755 */
1756 public float[] getSamples(int x, int y, int w, int h, int b,
1757 float fArray[]) {
1758 return sampleModel.getSamples(x - sampleModelTranslateX,
1759 y - sampleModelTranslateY,
1760 w, h, b, fArray, dataBuffer);
1761 }
1762
1763 /**
1764 * Returns the samples for a specified band for a specified rectangle
1765 * of pixels in a double array, one sample per array element.
1766 * An ArrayIndexOutOfBoundsException may be thrown
1767 * if the coordinates are not in bounds. However, explicit bounds
1768 * checking is not guaranteed.
1769 * @param x The X coordinate of the upper-left pixel location
1770 * @param y The Y coordinate of the upper-left pixel location
1771 * @param w Width of the pixel rectangle
1772 * @param h Height of the pixel rectangle
1773 * @param b The band to return
1774 * @param dArray An optionally pre-allocated double array
1775 * @return the samples for the specified band for the specified
1776 * rectangle of pixels.
1777 *
1778 * @throws ArrayIndexOutOfBoundsException if the coordinates or
1779 * the band index are not in bounds, or if dArray is too small to
1780 * hold the output.
1781 */
1782 public double[] getSamples(int x, int y, int w, int h, int b,
1783 double dArray[]) {
1784 return sampleModel.getSamples(x - sampleModelTranslateX,
1785 y - sampleModelTranslateY,
1786 w, h, b, dArray, dataBuffer);
1787 }
1788
1789 }