001: /*
002: * $RCSfile: ImageComponent3D.java,v $
003: *
004: * Copyright 1996-2008 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
006: *
007: * This code is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU General Public License version 2 only, as
009: * published by the Free Software Foundation. Sun designates this
010: * particular file as subject to the "Classpath" exception as provided
011: * by Sun in the LICENSE file that accompanied this code.
012: *
013: * This code is distributed in the hope that it will be useful, but WITHOUT
014: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
015: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
016: * version 2 for more details (a copy is included in the LICENSE file that
017: * accompanied this code).
018: *
019: * You should have received a copy of the GNU General Public License version
020: * 2 along with this work; if not, write to the Free Software Foundation,
021: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
022: *
023: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
024: * CA 95054 USA or visit www.sun.com if you need additional information or
025: * have any questions.
026: *
027: * $Revision: 1.7 $
028: * $Date: 2008/02/28 20:17:23 $
029: * $State: Exp $
030: */
031:
032: package javax.media.j3d;
033:
034: import java.awt.image.BufferedImage;
035: import java.awt.image.RenderedImage;
036:
037: /**
038: * This class defines a 3D image component. This is used for texture
039: * images.
040: * Prior to Java 3D 1.2, only BufferedImage objects could be used as
041: * the input to an ImageComponent3D object. As of Java 3D 1.2, an
042: * ImageComponent3D accepts an array of arbitrary RenderedImage
043: * objects (BufferedImage is an implementation of the RenderedImage
044: * interface). The methods that set/get a BufferedImage object are
045: * left in for compatibility. The new methods that set/get a
046: * RenderedImage are a superset of the old methods. In particular,
047: * the two set methods in the following example are equivalent:
048: *
049: * <p>
050: * <ul>
051: * <code>
052: * BufferedImage bi;<br>
053: * RenderedImage ri = bi;<br>
054: * ImageComponent3D ic;<br>
055: * <p>
056: * // Set image 0 to the specified BufferedImage<br>
057: * ic.set(0, bi);<br>
058: * <p>
059: * // Set image 0 to the specified RenderedImage<br>
060: * ic.set(0, ri);<br>
061: * </code>
062: * </ul>
063: *
064: */
065: public class ImageComponent3D extends ImageComponent {
066:
067: // non-public, no parameter constructor
068: ImageComponent3D() {
069: }
070:
071: /**
072: * Constructs a 3D image component object using the specified
073: * format, width, height, and depth. Default values are used for
074: * all other parameters. The default values are as follows:
075: * <ul>
076: * array of images : null<br>
077: * imageClass : ImageClass.BUFFERED_IMAGE<br>
078: * </ul>
079: *
080: * @param format the image component format, one of: FORMAT_RGB,
081: * FORMAT_RGBA, etc.
082: * @param width the number of columns of pixels in this image component
083: * object
084: * @param height the number of rows of pixels in this image component
085: * object
086: * @param depth the number of 2D slices in this image component object
087: * @exception IllegalArgumentException if format is invalid, or if
088: * any of width, height, or depth are not positive.
089: */
090: public ImageComponent3D(int format, int width, int height, int depth) {
091:
092: ((ImageComponent3DRetained) this .retained).processParams(
093: format, width, height, depth);
094: }
095:
096: /**
097: * Constructs a 3D image component object using the specified format,
098: * and the BufferedImage array.
099: * The image class is set to ImageClass.BUFFERED_IMAGE.
100: * Default values are used for all other parameters.
101: *
102: * @param format the image component format, one of: FORMAT_RGB,
103: * FORMAT_RGBA etc.
104: * @param images an array of BufferedImage objects. The
105: * first image in the array determines the width and height of this
106: * ImageComponent3D.
107: *
108: * @exception IllegalArgumentException if format is invalid, or if
109: * the width or height of the first image are not positive.
110: */
111: public ImageComponent3D(int format, BufferedImage[] images) {
112: ((ImageComponent3DRetained) this .retained).processParams(
113: format, images[0].getWidth(null), images[0]
114: .getHeight(null), images.length);
115: for (int i = 0; i < images.length; i++) {
116: ((ImageComponent3DRetained) this .retained)
117: .set(i, images[i]);
118: }
119: }
120:
121: /**
122: * Constructs a 3D image component object using the specified format,
123: * and the RenderedImage array.
124: * The image class is set to ImageClass.BUFFERED_IMAGE.
125: * Default values are used for all other parameters.
126: *
127: * @param format the image component format, one of: FORMAT_RGB,
128: * FORMAT_RGBA etc.
129: * @param images an array of RenderedImage objects. The
130: * first image in the array determines the width and height of this
131: * ImageComponent3D.
132: *
133: * @exception IllegalArgumentException if format is invalid, or if
134: * the width or height of the first image are not positive.
135: *
136: * @since Java 3D 1.2
137: */
138: public ImageComponent3D(int format, RenderedImage[] images) {
139:
140: ((ImageComponent3DRetained) this .retained).processParams(
141: format, images[0].getWidth(), images[0].getHeight(),
142: images.length);
143: for (int i = 0; i < images.length; i++) {
144: ((ImageComponent3DRetained) this .retained)
145: .set(i, images[i]);
146: }
147: }
148:
149: /**
150: * Constructs a 3D image component object using the specified
151: * format, width, height, depth, byReference flag, and yUp flag.
152: * Default values are used for all other parameters.
153: *
154: * @param format the image component format, one of: FORMAT_RGB,
155: * FORMAT_RGBA, etc.
156: * @param width the number of columns of pixels in this image component
157: * object
158: * @param height the number of rows of pixels in this image component
159: * object
160: * @param depth the number of 2D slices in this image component object
161: * @param byReference a flag that indicates whether the data is copied
162: * into this image component object or is accessed by reference.
163: * @param yUp a flag that indicates the y-orientation of this image
164: * component. If yUp is set to true, the origin of the image is
165: * the lower left; otherwise, the origin of the image is the upper
166: * left.
167: *
168: * @exception IllegalArgumentException if format is invalid, or if
169: * any of width, height, or depth are not positive.
170: *
171: * @since Java 3D 1.2
172: */
173: public ImageComponent3D(int format, int width, int height,
174: int depth, boolean byReference, boolean yUp) {
175:
176: ((ImageComponentRetained) this .retained)
177: .setByReference(byReference);
178: ((ImageComponentRetained) this .retained).setYUp(yUp);
179: ((ImageComponent3DRetained) this .retained).processParams(
180: format, width, height, depth);
181: }
182:
183: /**
184: * Constructs a 3D image component object using the specified format,
185: * BufferedImage array, byReference flag, and yUp flag.
186: * The image class is set to ImageClass.BUFFERED_IMAGE.
187: *
188: * @param format the image component format, one of: FORMAT_RGB,
189: * FORMAT_RGBA etc.
190: * @param images an array of BufferedImage objects. The
191: * first image in the array determines the width and height of this
192: * ImageComponent3D.
193: * @param byReference a flag that indicates whether the data is copied
194: * into this image component object or is accessed by reference.
195: * @param yUp a flag that indicates the y-orientation of this image
196: * component. If yUp is set to true, the origin of the image is
197: * the lower left; otherwise, the origin of the image is the upper
198: * left.
199: *
200: * @exception IllegalArgumentException if format is invalid, or if
201: * the width or height of the first image are not positive.
202: *
203: * @since Java 3D 1.2
204: */
205: public ImageComponent3D(int format, BufferedImage[] images,
206: boolean byReference, boolean yUp) {
207:
208: ((ImageComponentRetained) this .retained)
209: .setByReference(byReference);
210: ((ImageComponentRetained) this .retained).setYUp(yUp);
211: ((ImageComponent3DRetained) this .retained).processParams(
212: format, images[0].getWidth(null), images[0]
213: .getHeight(null), images.length);
214: for (int i = 0; i < images.length; i++) {
215: ((ImageComponent3DRetained) this .retained)
216: .set(i, images[i]);
217: }
218: }
219:
220: /**
221: * Constructs a 3D image component object using the specified format,
222: * RenderedImage array, byReference flag, and yUp flag.
223: * The image class is set to ImageClass.RENDERED_IMAGE if the byReference
224: * flag is true and any of the specified RenderedImages is <i>not</i> an
225: * instance of BufferedImage. In all other cases, the image class is set to
226: * ImageClass.BUFFERED_IMAGE.
227: *
228: * @param format the image component format, one of: FORMAT_RGB,
229: * FORMAT_RGBA etc.
230: * @param images an array of RenderedImage objects. The
231: * first image in the array determines the width and height of this
232: * ImageComponent3D.
233: * @param byReference a flag that indicates whether the data is copied
234: * into this image component object or is accessed by reference.
235: * @param yUp a flag that indicates the y-orientation of this image
236: * component. If yUp is set to true, the origin of the image is
237: * the lower left; otherwise, the origin of the image is the upper
238: * left.
239: * @exception IllegalArgumentException if format is invalid, or if
240: * the width or height of the first image are not positive.
241: *
242: * @since Java 3D 1.2
243: */
244: public ImageComponent3D(int format, RenderedImage[] images,
245: boolean byReference, boolean yUp) {
246:
247: ((ImageComponentRetained) this .retained)
248: .setByReference(byReference);
249: ((ImageComponentRetained) this .retained).setYUp(yUp);
250: ((ImageComponent3DRetained) this .retained).processParams(
251: format, images[0].getWidth(), images[0].getHeight(),
252: images.length);
253: for (int i = 0; i < images.length; i++) {
254: ((ImageComponent3DRetained) this .retained)
255: .set(i, images[i]);
256: }
257: }
258:
259: /**
260: * Constructs a 3D image component object using the specified format,
261: * NioImageBuffer array, byReference flag, and yUp flag.
262: * The image class is set to ImageClass.NIO_IMAGE_BUFFER.
263: *
264: * @param format the image component format, one of: FORMAT_RGB,
265: * FORMAT_RGBA etc.
266: * @param images an array of NioImageBuffer objects. The
267: * first image in the array determines the width and height of this
268: * ImageComponent3D.
269: * @param byReference a flag that indicates whether the data is copied
270: * into this image component object or is accessed by reference.
271: * @param yUp a flag that indicates the y-orientation of this image
272: * component. If yUp is set to true, the origin of the image is
273: * the lower left; otherwise, the origin of the image is the upper
274: * left.
275: *
276: * @exception IllegalArgumentException if format is invalid, or if
277: * the width or height of the first image are not positive.
278: *
279: * @exception IllegalArgumentException if the byReference flag is false.
280: *
281: * @exception IllegalArgumentException if the yUp flag is false.
282: *
283: * @exception UnsupportedOperationException this method is not supported
284: * for Java 3D 1.5.
285: *
286: * @since Java 3D 1.5
287: */
288: public ImageComponent3D(int format, NioImageBuffer[] images,
289: boolean byReference, boolean yUp) {
290:
291: throw new UnsupportedOperationException();
292: /*
293: ((ImageComponentRetained)this.retained).setByReference(byReference);
294: ((ImageComponentRetained)this.retained).setYUp(yUp);
295: ((ImageComponent3DRetained)this.retained).processParams(format,
296: images[0].getWidth(), images[0].getHeight(), images.length);
297: for (int i=0; i<images.length; i++) {
298: ((ImageComponent3DRetained)this.retained).set(i, images[i]);
299: }
300: */
301: }
302:
303: /**
304: * Retrieves the depth of this 3D image component object.
305: *
306: * @return the depth of this 3D image component object
307: *
308: * @exception CapabilityNotSetException if appropriate capability is
309: * not set and this object is part of live or compiled scene graph
310: */
311: public int getDepth() {
312: if (isLiveOrCompiled())
313: if (!this .getCapability(ImageComponent.ALLOW_SIZE_READ))
314: throw new CapabilityNotSetException(J3dI18N
315: .getString("ImageComponent3D0"));
316: return ((ImageComponent3DRetained) this .retained).getDepth();
317: }
318:
319: /**
320: * Sets the array of images in this image component to the
321: * specified array of BufferedImage objects. If the data access
322: * mode is not by-reference, then the BufferedImage data is copied
323: * into this object. If the data access mode is by-reference,
324: * then a shallow copy of the array of references to the
325: * BufferedImage objects is made, but the BufferedImage
326: * data is not necessarily copied.
327: * <p>
328: * The image class is set to ImageClass.BUFFERED_IMAGE.
329: *
330: * @param images array of BufferedImage objects containing the image.
331: * The size (width and height) of each image must be the same as the
332: * size of the image component, and the length of the images array
333: * must equal the depth of the image component.
334: *
335: * @exception CapabilityNotSetException if appropriate capability is
336: * not set and this object is part of live or compiled scene graph
337: *
338: * @exception IllegalArgumentException if the length of the images array is
339: * not equal to the depth of this ImageComponent object.
340: *
341: * @exception IllegalArgumentException if the width and height of each
342: * image in the images array is not equal to the width and height of this
343: * ImageComponent object.
344: */
345: public void set(BufferedImage[] images) {
346: checkForLiveOrCompiled();
347: int depth = ((ImageComponent3DRetained) this .retained)
348: .getDepth();
349:
350: if (depth != images.length)
351: throw new IllegalArgumentException(J3dI18N
352: .getString("ImageComponent3D1"));
353: for (int i = 0; i < depth; i++) {
354: ((ImageComponent3DRetained) this .retained)
355: .set(i, images[i]);
356: }
357: }
358:
359: /**
360: * Sets the array of images in this image component to the
361: * specified array of RenderedImage objects. If the data access
362: * mode is not by-reference, then the RenderedImage data is copied
363: * into this object. If the data access mode is by-reference,
364: * then a shallow copy of the array of references to the
365: * RenderedImage objects is made, but the RenderedImage
366: * data is not necessarily copied.
367: * <p>
368: * The image class is set to ImageClass.RENDERED_IMAGE if the data access
369: * mode is by-reference and any of the specified RenderedImages
370: * is <i>not</i> an instance of BufferedImage. In all other cases,
371: * the image class is set to ImageClass.BUFFERED_IMAGE.
372: *
373: * @param images array of RenderedImage objects containing the image.
374: * The size (width and height) of each image must be the same as the
375: * size of the image component, and the length of the images array
376: * must equal the depth of the image component.
377: *
378: * @exception CapabilityNotSetException if appropriate capability is
379: * not set and this object is part of live or compiled scene graph
380: *
381: * @exception IllegalArgumentException if the length of the images array is
382: * not equal to the depth of this ImageComponent object.
383: *
384: * @exception IllegalArgumentException if the width and height of each
385: * image in the images array is not equal to the width and height of this
386: * ImageComponent object.
387: *
388: * @since Java 3D 1.2
389: */
390: public void set(RenderedImage[] images) {
391:
392: checkForLiveOrCompiled();
393: int depth = ((ImageComponent3DRetained) this .retained)
394: .getDepth();
395:
396: if (depth != images.length)
397: throw new IllegalArgumentException(J3dI18N
398: .getString("ImageComponent3D1"));
399: for (int i = 0; i < depth; i++) {
400: ((ImageComponent3DRetained) this .retained)
401: .set(i, images[i]);
402: }
403: }
404:
405: /**
406: * Sets the array of images in this image component to the
407: * specified array of NioImageBuffer objects. If the data access
408: * mode is not by-reference, then the NioImageBuffer data is copied
409: * into this object. If the data access mode is by-reference,
410: * then a shallow copy of the array of references to the
411: * NioImageBuffer objects is made, but the NioImageBuffer
412: * data is not necessarily copied.
413: * <p>
414: * The image class is set to ImageClass.NIO_IMAGE_BUFFER.
415: *
416: * @param images array of NioImageBuffer objects containing the image.
417: * The size (width and height) of each image must be the same as the
418: * size of the image component, and the length of the images array
419: * must equal the depth of the image component.
420: *
421: * @exception CapabilityNotSetException if appropriate capability is
422: * not set and this object is part of live or compiled scene graph
423: *
424: * @exception IllegalStateException if this ImageComponent object
425: * is <i>not</i> yUp.
426: *
427: * @exception IllegalArgumentException if the length of the images array is
428: * not equal to the depth of this ImageComponent object.
429: *
430: * @exception IllegalArgumentException if the width and height of each
431: * image in the images array is not equal to the width and height of this
432: * ImageComponent object.
433: *
434: * @exception UnsupportedOperationException this method is not supported
435: * for Java 3D 1.5.
436: *
437: * @since Java 3D 1.5
438: */
439: public void set(NioImageBuffer[] images) {
440:
441: throw new UnsupportedOperationException();
442: /*
443: checkForLiveOrCompiled();
444: int depth = ((ImageComponent3DRetained)this.retained).getDepth();
445:
446: if (depth != images.length)
447: throw new IllegalArgumentException(J3dI18N.getString("ImageComponent3D1"));
448: for (int i=0; i<depth; i++) {
449: ((ImageComponent3DRetained)this.retained).set(i, images[i]);
450: }
451: */
452: }
453:
454: /**
455: * Sets this image component at the specified index to the
456: * specified BufferedImage object. If the data access mode is not
457: * by-reference, then the BufferedImage data is copied into this
458: * object. If the data access mode is by-reference, then a
459: * reference to the BufferedImage is saved, but the data is not
460: * necessarily copied.
461: *
462: * @param index the image index.
463: * The index must be less than the depth of this ImageComponent3D object.
464: *
465: * @param image BufferedImage object containing the image.
466: * The size (width and height) must be the same as the current size of this
467: * ImageComponent3D object.
468: *
469: * @exception CapabilityNotSetException if appropriate capability is
470: * not set and this object is part of live or compiled scene graph
471: *
472: * @exception IllegalStateException if the image class is not
473: * ImageClass.BUFFERED_IMAGE.
474: *
475: * @exception IllegalArgumentException if the width and height the image
476: * is not equal to the width and height of this ImageComponent object.
477: */
478: public void set(int index, BufferedImage image) {
479: checkForLiveOrCompiled();
480: if (image.getWidth(null) != this .getWidth())
481: throw new IllegalArgumentException(J3dI18N
482: .getString("ImageComponent3D2"));
483:
484: if (image.getHeight(null) != this .getHeight())
485: throw new IllegalArgumentException(J3dI18N
486: .getString("ImageComponent3D4"));
487:
488: ((ImageComponent3DRetained) this .retained).set(index, image);
489: }
490:
491: /**
492: * Sets this image component at the specified index to the
493: * specified RenderedImage object. If the data access mode is not
494: * by-reference, then the RenderedImage data is copied into this
495: * object. If the data access mode is by-reference, then a
496: * reference to the RenderedImage is saved, but the data is not
497: * necessarily copied.
498: *
499: * @param index the image index.
500: * The index must be less than the depth of this ImageComponent3D object.
501: *
502: * @param image RenderedImage object containing the image.
503: * The size (width and height) must be the same as the current size of this
504: * ImageComponent3D object.
505: *
506: * @exception CapabilityNotSetException if appropriate capability is
507: * not set and this object is part of live or compiled scene graph
508: *
509: * @exception IllegalStateException if the image class is not one of:
510: * ImageClass.BUFFERED_IMAGE or ImageClass.RENDERED_IMAGE.
511: *
512: * @exception IllegalArgumentException if the width and height the image
513: * is not equal to the width and height of this ImageComponent object.
514: *
515: * @since Java 3D 1.2
516: */
517: public void set(int index, RenderedImage image) {
518:
519: checkForLiveOrCompiled();
520: // For RenderedImage the width and height checking is done in the retained.
521: ((ImageComponent3DRetained) this .retained).set(index, image);
522: }
523:
524: /**
525: * Sets this image component at the specified index to the
526: * specified NioImageBuffer object. If the data access mode is not
527: * by-reference, then the NioImageBuffer data is copied into this
528: * object. If the data access mode is by-reference, then a
529: * reference to the NioImageBuffer is saved, but the data is not
530: * necessarily copied.
531: *
532: * @param index the image index.
533: * The index must be less than the depth of this ImageComponent3D object.
534: *
535: * @param image NioImageBuffer object containing the image.
536: * The size (width and height) must be the same as the current size of this
537: * ImageComponent3D object.
538: *
539: * @exception CapabilityNotSetException if appropriate capability is
540: * not set and this object is part of live or compiled scene graph
541: *
542: * @exception IllegalStateException if the image class is not
543: * ImageClass.NIO_IMAGE_BUFFER.
544: *
545: * @exception IllegalArgumentException if the width and height the image
546: * is not equal to the width and height of this ImageComponent object.
547: *
548: * @exception UnsupportedOperationException this method is not supported
549: * for Java 3D 1.5.
550: *
551: * @since Java 3D 1.5
552: */
553: public void set(int index, NioImageBuffer image) {
554:
555: throw new UnsupportedOperationException();
556: /*
557: checkForLiveOrCompiled();
558: // For NioImageBuffer the width and height checking is done in the retained.
559: ((ImageComponent3DRetained)this.retained).set(index, image);
560: */
561: }
562:
563: /**
564: * Retrieves the images from this ImageComponent3D object. If the
565: * data access mode is not by-reference, then a copy of the images
566: * is made. If the data access mode is by-reference, then the
567: * references are returned.
568: *
569: * @return either a new array of new BufferedImage objects created from
570: * the data
571: * in this image component, or a new array of
572: * references to the BufferedImages that this image component refers to.
573: *
574: * @exception CapabilityNotSetException if appropriate capability is
575: * not set and this object is part of live or compiled scene graph
576: *
577: * @exception IllegalStateException if the image class is not
578: * ImageClass.BUFFERED_IMAGE.
579: */
580: public BufferedImage[] getImage() {
581: if (isLiveOrCompiled())
582: if (!this .getCapability(ImageComponent.ALLOW_IMAGE_READ))
583: throw new CapabilityNotSetException(J3dI18N
584: .getString("ImageComponent3D3"));
585: return ((ImageComponent3DRetained) this .retained).getImage();
586: }
587:
588: /**
589: * Retrieves the images from this ImageComponent3D object. If the
590: * data access mode is not by-reference, then a copy of the images
591: * is made. If the data access mode is by-reference, then the
592: * references are returned.
593: *
594: * @return either a new array of new RenderedImage objects created from
595: * the data
596: * in this image component, or a new array of
597: * references to the RenderedImages that this image component refers to.
598: *
599: * @exception CapabilityNotSetException if appropriate capability is
600: * not set and this object is part of live or compiled scene graph
601: *
602: * @exception IllegalStateException if the image class is not one of:
603: * ImageClass.BUFFERED_IMAGE or ImageClass.RENDERED_IMAGE.
604: *
605: * @since Java 3D 1.2
606: */
607: public RenderedImage[] getRenderedImage() {
608: if (isLiveOrCompiled())
609: if (!this .getCapability(ImageComponent.ALLOW_IMAGE_READ))
610: throw new CapabilityNotSetException(J3dI18N
611: .getString("ImageComponent3D3"));
612: return ((ImageComponent3DRetained) this .retained)
613: .getRenderedImage();
614: }
615:
616: /**
617: * Retrieves the images from this ImageComponent3D object. If the
618: * data access mode is not by-reference, then a copy of the images
619: * is made. If the data access mode is by-reference, then the
620: * references are returned.
621: *
622: * @return either a new array of new RenderedImage objects created from
623: * the data
624: * in this image component, or a new array of
625: * references to the RenderedImages that this image component refers to.
626: *
627: * @exception CapabilityNotSetException if appropriate capability is
628: * not set and this object is part of live or compiled scene graph
629: *
630: * @exception IllegalStateException if the image class is not
631: * ImageClass.NIO_IMAGE_BUFFER.
632: *
633: * @exception UnsupportedOperationException this method is not supported
634: * for Java 3D 1.5.
635: *
636: * @since Java 3D 1.5
637: */
638: public NioImageBuffer[] getNioImage() {
639:
640: throw new UnsupportedOperationException();
641: }
642:
643: /**
644: * Retrieves one of the images from this ImageComponent3D object. If the
645: * data access mode is not by-reference, then a copy of the image
646: * is made. If the data access mode is by-reference, then the
647: * reference is returned.
648: *
649: * @param index the index of the image to retrieve.
650: * The index must be less than the depth of this ImageComponent3D object.
651: *
652: * @return either a new BufferedImage object created from the data
653: * in this image component, or the BufferedImage object referenced
654: * by this image component.
655: *
656: * @exception CapabilityNotSetException if appropriate capability is
657: * not set and this object is part of live or compiled scene graph
658: *
659: * @exception IllegalStateException if the image class is not
660: * ImageClass.BUFFERED_IMAGE.
661: */
662: public BufferedImage getImage(int index) {
663: if (isLiveOrCompiled())
664: if (!this .getCapability(ImageComponent.ALLOW_IMAGE_READ))
665: throw new CapabilityNotSetException(J3dI18N
666: .getString("ImageComponent3D3"));
667:
668: RenderedImage img = ((ImageComponent3DRetained) this .retained)
669: .getImage(index);
670: if ((img != null) && !(img instanceof BufferedImage)) {
671: throw new IllegalStateException(J3dI18N
672: .getString("ImageComponent3D9"));
673: }
674: return (BufferedImage) img;
675: }
676:
677: /**
678: * Retrieves one of the images from this ImageComponent3D object. If the
679: * data access mode is not by-reference, then a copy of the image
680: * is made. If the data access mode is by-reference, then the
681: * reference is returned.
682: *
683: * @param index the index of the image to retrieve.
684: * The index must be less than the depth of this ImageComponent3D object.
685: *
686: * @return either a new RenderedImage object created from the data
687: * in this image component, or the RenderedImage object referenced
688: * by this image component.
689: *
690: * @exception CapabilityNotSetException if appropriate capability is
691: * not set and this object is part of live or compiled scene graph
692: *
693: * @exception IllegalStateException if the image class is not one of:
694: * ImageClass.BUFFERED_IMAGE or ImageClass.RENDERED_IMAGE.
695: *
696: * @since Java 3D 1.2
697: */
698: public RenderedImage getRenderedImage(int index) {
699:
700: if (isLiveOrCompiled())
701: if (!this .getCapability(ImageComponent.ALLOW_IMAGE_READ))
702: throw new CapabilityNotSetException(J3dI18N
703: .getString("ImageComponent3D3"));
704: return ((ImageComponent3DRetained) this .retained)
705: .getImage(index);
706: }
707:
708: /**
709: * Retrieves one of the images from this ImageComponent3D object. If the
710: * data access mode is not by-reference, then a copy of the image
711: * is made. If the data access mode is by-reference, then the
712: * reference is returned.
713: *
714: * @param index the index of the image to retrieve.
715: * The index must be less than the depth of this ImageComponent3D object.
716: *
717: * @return either a new NioImageBuffer object created from the data
718: * in this image component, or the NioImageBuffer object referenced
719: * by this image component.
720: *
721: * @exception CapabilityNotSetException if appropriate capability is
722: * not set and this object is part of live or compiled scene graph
723: *
724: * @exception IllegalStateException if the image class is not
725: * ImageClass.NIO_IMAGE_BUFFER.
726: *
727: * @exception UnsupportedOperationException this method is not supported
728: * for Java 3D 1.5.
729: *
730: * @since Java 3D 1.5
731: */
732: public NioImageBuffer getNioImage(int index) {
733:
734: throw new UnsupportedOperationException();
735: }
736:
737: /**
738: * Modifies a contiguous subregion of a particular slice of
739: * image of this ImageComponent3D object.
740: * Block of data of dimension (width * height)
741: * starting at the offset (srcX, srcY) of the specified
742: * RenderedImage object will be copied into the particular slice of
743: * image component
744: * starting at the offset (dstX, dstY) of this ImageComponent3D object.
745: * The specified RenderedImage object must be of the same format as
746: * the current format of this object.
747: * This method can only be used if the data access mode is
748: * by-copy. If it is by-reference, see updateData().
749: *
750: * @param index index of the image to be modified.
751: * The index must be less than the depth of this ImageComponent3D object.
752: * @param image RenderedImage object containing the subimage.
753: * @param width width of the subregion.
754: * @param height height of the subregion.
755: * @param srcX starting X offset of the subregion in the specified image.
756: * @param srcY starting Y offset of the subregion in the specified image.
757: * @param dstX startin X offset of the subregion in the image
758: * component of this object.
759: * @param dstY starting Y offset of the subregion in the image
760: * component of this object.
761: *
762: * @exception CapabilityNotSetException if appropriate capability is
763: * not set and this object is part of live or compiled scene graph
764: *
765: * @exception IllegalStateException if the data access mode is
766: * <code>BY_REFERENCE</code>.
767: *
768: * @exception IllegalArgumentException if <code>width</code> or
769: * <code>height</code> of
770: * the subregion exceeds the dimension of the image in this object.
771: *
772: * @exception IllegalArgumentException if <code>dstX</code> < 0, or
773: * (<code>dstX</code> + <code>width</code>) > width of this object, or
774: * <code>dstY</code> < 0, or
775: * (<code>dstY</code> + <code>height</code>) > height of this object.
776: *
777: * @exception IllegalArgumentException if <code>srcX</code> < 0, or
778: * (<code>srcX</code> + <code>width</code>) > width of the RenderedImage
779: * object containing the subimage, or
780: * <code>srcY</code> < 0, or
781: * (<code>srcY</code> + <code>height</code>) > height of the
782: * RenderedImage object containing the subimage.
783: *
784: * @exception IllegalArgumentException if the specified RenderedImage
785: * is not compatible with the existing RenderedImage.
786: *
787: * @exception IllegalStateException if the image class is not one of:
788: * ImageClass.BUFFERED_IMAGE or ImageClass.RENDERED_IMAGE.
789: *
790: * @since Java 3D 1.3
791: */
792: public void setSubImage(int index, RenderedImage image, int width,
793: int height, int srcX, int srcY, int dstX, int dstY) {
794: if (isLiveOrCompiled()
795: && !this .getCapability(ALLOW_IMAGE_WRITE)) {
796: throw new CapabilityNotSetException(J3dI18N
797: .getString("ImageComponent3D5"));
798: }
799:
800: if (((ImageComponent3DRetained) this .retained).isByReference()) {
801: throw new IllegalStateException(J3dI18N
802: .getString("ImageComponent3D8"));
803: }
804:
805: int w = ((ImageComponent3DRetained) this .retained).getWidth();
806: int h = ((ImageComponent3DRetained) this .retained).getHeight();
807:
808: if ((srcX < 0) || (srcY < 0) || ((srcX + width) > w)
809: || ((srcY + height) > h) || (dstX < 0) || (dstY < 0)
810: || ((dstX + width) > w) || ((dstY + height) > h)) {
811: throw new IllegalArgumentException(J3dI18N
812: .getString("ImageComponent3D7"));
813: }
814:
815: ((ImageComponent3DRetained) this .retained).setSubImage(index,
816: image, width, height, srcX, srcY, dstX, dstY);
817: }
818:
819: /**
820: * Updates a particular slice of image data that is accessed by reference.
821: * This method calls the updateData method of the specified
822: * ImageComponent3D.Updater object to synchronize updates to the
823: * image data that is referenced by this ImageComponent3D object.
824: * Applications that wish to modify such data must perform all
825: * updates via this method.
826: * <p>
827: * The data to be modified has to be within the boundary of the
828: * subregion
829: * specified by the offset (x, y) and the dimension (width*height).
830: * It is illegal to modify data outside this boundary. If any
831: * referenced data is modified outside the updateData method, or
832: * any data outside the specified boundary is modified, the
833: * results are undefined.
834: * <p>
835: * @param updater object whose updateData callback method will be
836: * called to update the data referenced by this ImageComponent3D object.
837: * @param index index of the image to be modified.
838: * The index must be less than the depth of this ImageComponent3D object.
839: * @param x starting X offset of the subregion.
840: * @param y starting Y offset of the subregion.
841: * @param width width of the subregion.
842: * @param height height of the subregion.
843: *
844: * @exception CapabilityNotSetException if appropriate capability is
845: * not set and this object is part of live or compiled scene graph
846: * @exception IllegalStateException if the data access mode is
847: * <code>BY_COPY</code>.
848: * @exception IllegalArgumentException if <code>width</code> or
849: * <code>height</code> of
850: * the subregion exceeds the dimension of the image in this object.
851: * @exception IllegalArgumentException if <code>x</code> < 0, or
852: * (<code>x</code> + <code>width</code>) > width of this object, or
853: * <code>y</code> < 0, or
854: * (<code>y</code> + <code>height</code>) > height of this object.
855: * @exception ArrayIndexOutOfBoundsException if <code>index</code> > the
856: * depth of this object.
857: *
858: * @since Java 3D 1.3
859: */
860: public void updateData(Updater updater, int index, int x, int y,
861: int width, int height) {
862: if (isLiveOrCompiled()
863: && !this .getCapability(ALLOW_IMAGE_WRITE)) {
864: throw new CapabilityNotSetException(J3dI18N
865: .getString("ImageComponent3D5"));
866: }
867:
868: if (!((ImageComponent3DRetained) this .retained).isByReference()) {
869: throw new IllegalStateException(J3dI18N
870: .getString("ImageComponent3D6"));
871: }
872:
873: int w = ((ImageComponent3DRetained) this .retained).getWidth();
874: int h = ((ImageComponent3DRetained) this .retained).getHeight();
875:
876: if ((x < 0) || (y < 0) || ((x + width) > w)
877: || ((y + height) > h)) {
878: throw new IllegalArgumentException(J3dI18N
879: .getString("ImageComponent3D7"));
880: }
881:
882: ((ImageComponent3DRetained) this .retained).updateData(updater,
883: index, x, y, width, height);
884: }
885:
886: /**
887: * Creates a retained mode ImageComponent3DRetained object that this
888: * ImageComponent3D component object will point to.
889: */
890: void createRetained() {
891: this .retained = new ImageComponent3DRetained();
892: this .retained.setSource(this );
893: }
894:
895: /**
896: * @deprecated replaced with cloneNodeComponent(boolean forceDuplicate)
897: */
898: public NodeComponent cloneNodeComponent() {
899: ImageComponent3DRetained rt = (ImageComponent3DRetained) retained;
900:
901: ImageComponent3D img = new ImageComponent3D(rt.getFormat(),
902: rt.width, rt.height, rt.depth);
903:
904: // XXXX : replace by this to duplicate other attributes
905: /*
906: ImageComponent3D img = new ImageComponent3D(rt.format,
907: rt.width,
908: rt.height,
909: rt.depth,
910: rt.byReference,
911: rt.yUp);
912: */
913: img.duplicateNodeComponent(this );
914: return img;
915: }
916:
917: /**
918: * Copies all node information from <code>originalNodeComponent</code> into
919: * the current node. This method is called from the
920: * <code>duplicateNode</code> method. This routine does
921: * the actual duplication of all "local data" (any data defined in
922: * this object).
923: *
924: * @param originalNodeComponent the original node to duplicate.
925: * @param forceDuplicate when set to <code>true</code>, causes the
926: * <code>duplicateOnCloneTree</code> flag to be ignored. When
927: * <code>false</code>, the value of each node's
928: * <code>duplicateOnCloneTree</code> variable determines whether
929: * NodeComponent data is duplicated or copied.
930: *
931: * @see Node#cloneTree
932: * @see NodeComponent#setDuplicateOnCloneTree
933: */
934: void duplicateAttributes(NodeComponent originalNodeComponent,
935: boolean forceDuplicate) {
936: super
937: .duplicateAttributes(originalNodeComponent,
938: forceDuplicate);
939: // TODO : Handle NioImageBuffer if its supported.
940: RenderedImage imgs[] = ((ImageComponent3DRetained) originalNodeComponent.retained)
941: .getImage();
942:
943: if (imgs != null) {
944: ImageComponent3DRetained rt = (ImageComponent3DRetained) retained;
945:
946: for (int i = rt.depth - 1; i >= 0; i--) {
947: if (imgs[i] != null) {
948: rt.set(i, imgs[i]);
949: }
950: }
951: }
952: }
953:
954: /**
955: * The ImageComponent3D.Updater interface is used in updating image data
956: * that is accessed by reference from a live or compiled ImageComponent
957: * object. Applications that wish to modify such data must define a
958: * class that implements this interface. An instance of that class is
959: * then passed to the <code>updateData</code> method of the
960: * ImageComponent object to be modified.
961: *
962: * @since Java 3D 1.3
963: */
964: public static interface Updater {
965: /**
966: * Updates image data that is accessed by reference.
967: * This method is called by the updateData method of an
968: * ImageComponent object to effect
969: * safe updates to image data that
970: * is referenced by that object. Applications that wish to modify
971: * such data must implement this method and perform all updates
972: * within it.
973: * <br>
974: * NOTE: Applications should <i>not</i> call this method directly.
975: *
976: * @param imageComponent the ImageComponent object being updated.
977: * @param index index of the image to be modified.
978: * @param x starting X offset of the subregion.
979: * @param y starting Y offset of the subregion.
980: * @param width width of the subregion.
981: * @param height height of the subregion.
982: *
983: * @see ImageComponent3D#updateData
984: */
985: public void updateData(ImageComponent3D imageComponent,
986: int index, int x, int y, int width, int height);
987: }
988:
989: }
|