001: /*
002: * $RCSfile: Background.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.8 $
028: * $Date: 2008/02/28 20:17:19 $
029: * $State: Exp $
030: */
031:
032: package javax.media.j3d;
033:
034: import javax.vecmath.*;
035:
036: /**
037: * The Background leaf node defines a solid background color
038: * and a background image that are used to fill the window at the
039: * beginning of each new frame. The background image may be null.
040: * It optionally allows background
041: * geometry---which is pre-tessellated onto a unit sphere and is drawn
042: * at infinity---to be referenced. It also specifies an application
043: * region in which this background is active. A Background node is
044: * active when its application region intersects the ViewPlatform's
045: * activation volume. If multiple Background nodes are active, the
046: * Background node that is "closest" to the eye will be used. If no
047: * Background nodes are active, then the window is cleared to black.
048: *
049: * <p>
050: * The set of nodes that can be added to a BranchGroup associated with
051: * a Background node is limited. All Group nodes except
052: * ViewSpecificGroup are legal in a background geometry branch
053: * graph. The only Leaf nodes that are legal are Shape3D (except
054: * OrientedShape3D), Morph, Light, and Fog. The presence of any other
055: * Leaf node, including OrientedShape3D, or of a ViewSpecificGroup
056: * node will cause an IllegalSceneGraphException to be thrown. Note
057: * that Link nodes are not allowed; a background geometry branch graph
058: * must not reference shared subgraphs. NodeComponent objects can be
059: * shared between background branches and ordinary (non-background)
060: * branches or among different background branches, however.
061: *
062: * <p>
063: * Light and Fog nodes in a background geometry branch graph do not
064: * affect nodes outside of the background geometry branch graph, and
065: * vice versa. Light and Fog nodes that appear in a background
066: * geometry branch graph must not be hierarchically scoped to any
067: * group node outside of that background geometry branch graph.
068: * Conversely, Light and Fog nodes that appear outside of a particular
069: * background geometry branch graph must not be hierarchically scoped
070: * to any group node in that background geometry branch graph. Any
071: * attempt to do so will be ignored.
072: *
073: * <p>
074: * The influencing bounds of any Light or Fog node in a background
075: * geometry branch graph is effectively infinite (meaning that all
076: * lights can affect all geometry objects nodes within the background
077: * geometry graph, and that an arbitrary fog is selected). An
078: * application wishing to limit the scope of a Light or Fog node must
079: * use hierarchical scoping.
080: *
081: * <p>
082: * Picking and collision is ignored for nodes inside a background
083: * geometry branch graph.
084: */
085: public class Background extends Leaf {
086: /**
087: * Specifies that the Background allows read access to its application
088: * bounds and bounding leaf at runtime.
089: */
090: public static final int ALLOW_APPLICATION_BOUNDS_READ = CapabilityBits.BACKGROUND_ALLOW_APPLICATION_BOUNDS_READ;
091:
092: /**
093: * Specifies that the Background allows write access to its application
094: * bounds and bounding leaf at runtime.
095: */
096: public static final int ALLOW_APPLICATION_BOUNDS_WRITE = CapabilityBits.BACKGROUND_ALLOW_APPLICATION_BOUNDS_WRITE;
097:
098: /**
099: * Specifies that the Background allows read access to its image
100: * at runtime.
101: */
102: public static final int ALLOW_IMAGE_READ = CapabilityBits.BACKGROUND_ALLOW_IMAGE_READ;
103:
104: /**
105: * Specifies that the Background allows write access to its image
106: * at runtime.
107: */
108: public static final int ALLOW_IMAGE_WRITE = CapabilityBits.BACKGROUND_ALLOW_IMAGE_WRITE;
109:
110: /**
111: * Specifies that the Background allows read access to its color
112: * at runtime.
113: */
114: public static final int ALLOW_COLOR_READ = CapabilityBits.BACKGROUND_ALLOW_COLOR_READ;
115:
116: /**
117: * Specifies that the Background allows write access to its color
118: * at runtime.
119: */
120: public static final int ALLOW_COLOR_WRITE = CapabilityBits.BACKGROUND_ALLOW_COLOR_WRITE;
121:
122: /**
123: * Specifies that the Background allows read access to its
124: * background geometry at runtime.
125: */
126: public static final int ALLOW_GEOMETRY_READ = CapabilityBits.BACKGROUND_ALLOW_GEOMETRY_READ;
127:
128: /**
129: * Specifies that the Background allows write access to its
130: * background geometry at runtime.
131: */
132: public static final int ALLOW_GEOMETRY_WRITE = CapabilityBits.BACKGROUND_ALLOW_GEOMETRY_WRITE;
133:
134: /**
135: * Specifies that the Background allows read access to its image
136: * scale mode at runtime.
137: *
138: * @since Java 3D 1.3
139: */
140: public static final int ALLOW_IMAGE_SCALE_MODE_READ = CapabilityBits.BACKGROUND_ALLOW_IMAGE_SCALE_MODE_READ;
141:
142: /**
143: * Specifies that the Background allows write access to its image
144: * scale mode at runtime.
145: *
146: * @since Java 3D 1.3
147: */
148: public static final int ALLOW_IMAGE_SCALE_MODE_WRITE = CapabilityBits.BACKGROUND_ALLOW_IMAGE_SCALE_MODE_WRITE;
149:
150: /**
151: * Indicates that no scaling of the background image is done. The
152: * image will be drawn in its actual size. If the window is
153: * smaller than the image, the image will be clipped. If the
154: * window is larger than the image, the portion of the window not
155: * filled by the image will be filled with the background color.
156: * In all cases, the upper left corner of the image is anchored at
157: * the upper-left corner of the window.
158: * This is the default mode.
159: *
160: * @see #setImageScaleMode
161: *
162: * @since Java 3D 1.3
163: */
164: public static final int SCALE_NONE = 0;
165:
166: /**
167: * Indicates that the background image is uniformly scaled to fit
168: * the window such that the entire image is visible. The image is
169: * scaled by the smaller of <code>window.width/image.width</code>
170: * and <code>window.height/image.height</code>. The image will
171: * exactly fill either the width or height of the window, but not
172: * necessarily both. The portion of the window not filled by the
173: * image will be filled with the background color.
174: * The upper left corner of the image is anchored at the
175: * upper-left corner of the window.
176: *
177: * @see #setImageScaleMode
178: *
179: * @since Java 3D 1.3
180: */
181: public static final int SCALE_FIT_MIN = 1;
182:
183: /**
184: * Indicates that the background image is uniformly scaled to fit
185: * the window such that the entire window is filled. The image is
186: * scaled by the larger of <code>window.width/image.width</code>
187: * and <code>window.height/image.height</code>. The image will
188: * entirely fill the window, but may by clipped either in <i>X</i>
189: * or <i>Y</i>.
190: * The upper left corner of the image is anchored at the
191: * upper-left corner of the window.
192: *
193: * @see #setImageScaleMode
194: *
195: * @since Java 3D 1.3
196: */
197: public static final int SCALE_FIT_MAX = 2;
198:
199: /**
200: * Indicates that the background image is scaled to fit the
201: * window. The image is scaled non-uniformly in <i>x</i> and
202: * <i>y</i> by <code>window.width/image.width</code> and and
203: * <code>window.height/image.height</code>, respectively. The
204: * image will entirely fill the window.
205: *
206: * @see #setImageScaleMode
207: *
208: * @since Java 3D 1.3
209: */
210: public static final int SCALE_FIT_ALL = 3;
211:
212: /**
213: * Indicates that the background image is tiled to fill the entire
214: * window. The image is not scaled.
215: * The upper left corner of the image is anchored at the
216: * upper-left corner of the window.
217: *
218: * @see #setImageScaleMode
219: *
220: * @since Java 3D 1.3
221: */
222: public static final int SCALE_REPEAT = 4;
223:
224: /**
225: * Indicates that the background image is centered in the window
226: * and that no scaling of the image is done. The image will be
227: * drawn in its actual size. If the window is smaller than the
228: * image, the image will be clipped. If the window is larger than
229: * the image, the portion of the window not filled by the image
230: * will be filled with the background color.
231: *
232: * @see #setImageScaleMode
233: *
234: * @since Java 3D 1.3
235: */
236: public static final int SCALE_NONE_CENTER = 5;
237:
238: // Array for setting default read capabilities
239: private static final int[] readCapabilities = {
240: ALLOW_APPLICATION_BOUNDS_READ, ALLOW_COLOR_READ,
241: ALLOW_GEOMETRY_READ, ALLOW_IMAGE_READ,
242: ALLOW_IMAGE_SCALE_MODE_READ };
243:
244: /**
245: * Constructs a Background node with default parameters. The default
246: * values are as follows:
247: * <ul>
248: * color : black (0,0,0)<br>
249: * image : null<br>
250: * geometry : null<br>
251: * image scale mode : SCALE_NONE<br>
252: * application bounds : null<br>
253: * application bounding leaf : null<br>
254: * </ul>
255: */
256: public Background() {
257: // Just use the defaults
258: // set default read capabilities
259: setDefaultReadCapabilities(readCapabilities);
260: }
261:
262: /**
263: * Constructs a Background node with the specified color.
264: * This color is used to fill the window prior to drawing any
265: * objects in the scene.
266: */
267: public Background(Color3f color) {
268: // set default read capabilities
269: setDefaultReadCapabilities(readCapabilities);
270:
271: ((BackgroundRetained) this .retained).setColor(color);
272: }
273:
274: /**
275: * Constructs a Background node with the specified color.
276: * This color is used to fill the window prior to drawing any
277: * objects in the scene.
278: */
279: public Background(float r, float g, float b) {
280: // set default read capabilities
281: setDefaultReadCapabilities(readCapabilities);
282:
283: ((BackgroundRetained) this .retained).setColor(r, g, b);
284: }
285:
286: /**
287: * Constructs a Background node with the specified image. If this
288: * image is non-null, it is rendered to the window prior to
289: * drawing any objects in the scene. If the image is smaller
290: * than the window,
291: * then that portion of the window not covered by the image is
292: * filled with the background color.
293: *
294: * @param image pixel array object used as the background image
295: *
296: * @exception IllegalArgumentException if the image class of the specified
297: * ImageComponent2D is ImageClass.NIO_IMAGE_BUFFER.
298: */
299: public Background(ImageComponent2D image) {
300: // set default read capabilities
301: setDefaultReadCapabilities(readCapabilities);
302:
303: if ((image != null)
304: && (image.getImageClass() == ImageComponent.ImageClass.NIO_IMAGE_BUFFER)) {
305: throw new IllegalArgumentException(J3dI18N
306: .getString("Background14"));
307: }
308:
309: ((BackgroundRetained) this .retained).setImage(image);
310: }
311:
312: /**
313: * Constructs a Background node with the specified geometry.
314: * If non-null, this background geometry is drawn on top of
315: * the background color and image using a projection
316: * matrix that essentially puts the geometry at infinity. The geometry
317: * should be pre-tessellated onto a unit sphere.
318: * @param branch the root of the background geometry
319: * @exception IllegalSharingException if the BranchGroup node
320: * is a child of any Group node, or is already attached to a Locale,
321: * or is already referenced by another Background node.
322: * @exception IllegalSceneGraphException if specified branch graph
323: * contains an illegal node.
324: */
325: public Background(BranchGroup branch) {
326: // set default read capabilities
327: setDefaultReadCapabilities(readCapabilities);
328:
329: ((BackgroundRetained) this .retained).setGeometry(branch);
330: }
331:
332: /**
333: * Sets the background color to the specified color.
334: * This color is used to fill the window prior to drawing any
335: * objects in the scene.
336: * @param color the new background color
337: * @exception CapabilityNotSetException if appropriate capability is
338: * not set and this object is part of live or compiled scene graph
339: */
340: public void setColor(Color3f color) {
341: if (isLiveOrCompiled())
342: if (!this .getCapability(ALLOW_COLOR_WRITE))
343: throw new CapabilityNotSetException(J3dI18N
344: .getString("Background0"));
345:
346: if (isLive())
347: ((BackgroundRetained) this .retained).setColor(color);
348: else
349: ((BackgroundRetained) this .retained).initColor(color);
350:
351: }
352:
353: /**
354: * Sets the background color to the specified color.
355: * This color is used to fill the window prior to drawing any
356: * objects in the scene.
357: * @param r the red component of the background color
358: * @param g the green component of the background color
359: * @param b the blue component of the background color
360: * @exception CapabilityNotSetException if appropriate capability is
361: * not set and this object is part of live or compiled scene graph
362: */
363: public void setColor(float r, float g, float b) {
364: if (isLiveOrCompiled())
365: if (!this .getCapability(ALLOW_COLOR_WRITE))
366: throw new CapabilityNotSetException(J3dI18N
367: .getString("Background0"));
368:
369: if (isLive())
370: ((BackgroundRetained) this .retained).setColor(r, g, b);
371: else
372: ((BackgroundRetained) this .retained).initColor(r, g, b);
373: }
374:
375: /**
376: * Retrieves the background color.
377: * @param color the vector that will receive the current background color
378: * @exception CapabilityNotSetException if appropriate capability is
379: * not set and this object is part of live or compiled scene graph
380: */
381: public void getColor(Color3f color) {
382: if (isLiveOrCompiled())
383: if (!this .getCapability(ALLOW_COLOR_READ))
384: throw new CapabilityNotSetException(J3dI18N
385: .getString("Background2"));
386:
387: ((BackgroundRetained) this .retained).getColor(color);
388: }
389:
390: /**
391: * Sets the background image to the specified image. If this
392: * image is non-null, it is rendered to the window prior to
393: * drawing any objects in the scene. If the image is smaller
394: * than the window,
395: * then that portion of the window not covered by the image is
396: * filled with the background color.
397: *
398: * @param image new pixel array object used as the background image
399: *
400: * @exception CapabilityNotSetException if appropriate capability is
401: * not set and this object is part of live or compiled scene graph
402: *
403: * @exception IllegalSharingException if this Background is live and
404: * the specified image is being used by a Canvas3D as an off-screen buffer.
405: *
406: * @exception IllegalSharingException if this Background is
407: * being used by an immediate mode context and
408: * the specified image is being used by a Canvas3D as an off-screen buffer.
409: *
410: * @exception IllegalArgumentException if the image class of the specified
411: * ImageComponent2D is ImageClass.NIO_IMAGE_BUFFER.
412: */
413: public void setImage(ImageComponent2D image) {
414: if (isLiveOrCompiled())
415: if (!this .getCapability(ALLOW_IMAGE_WRITE))
416: throw new CapabilityNotSetException(J3dI18N
417: .getString("Background3"));
418:
419: BackgroundRetained bgRetained = (BackgroundRetained) this .retained;
420:
421: if ((image != null)
422: && (image.getImageClass() == ImageComponent.ImageClass.NIO_IMAGE_BUFFER)) {
423: throw new IllegalArgumentException(J3dI18N
424: .getString("Background14"));
425: }
426:
427: // Do illegal sharing check
428: if (image != null) {
429: ImageComponent2DRetained imageRetained = (ImageComponent2DRetained) image.retained;
430: if (imageRetained.getUsedByOffScreen()) {
431: if (isLive()) {
432: throw new IllegalSharingException(J3dI18N
433: .getString("Background12"));
434: }
435: if (bgRetained.getInImmCtx()) {
436: throw new IllegalSharingException(J3dI18N
437: .getString("Background13"));
438: }
439: }
440: }
441:
442: if (isLive())
443: bgRetained.setImage(image);
444: else
445: bgRetained.initImage(image);
446: }
447:
448: /**
449: * Retrieves the background image.
450: * @return the current background image
451: * @exception CapabilityNotSetException if appropriate capability is
452: * not set and this object is part of live or compiled scene graph
453: */
454: public ImageComponent2D getImage() {
455: if (isLiveOrCompiled())
456: if (!this .getCapability(ALLOW_IMAGE_READ))
457: throw new CapabilityNotSetException(J3dI18N
458: .getString("Background4"));
459:
460: return ((BackgroundRetained) this .retained).getImage();
461: }
462:
463: /**
464: * Sets the image scale mode for this Background node.
465: *
466: * @param imageScaleMode the new image scale mode, one of:
467: * SCALE_NONE, SCALE_FIT_MIN, SCALE_FIT_MAX, SCALE_FIT_ALL,
468: * SCALE_REPEAT, or SCALE_NONE_CENTER.
469: *
470: * @exception IllegalArgumentException if <code>imageScaleMode</code>
471: * is a value other than SCALE_NONE, SCALE_FIT_MIN, SCALE_FIT_MAX,
472: * SCALE_FIT_ALL, SCALE_REPEAT, or SCALE_NONE_CENTER.
473: * @exception CapabilityNotSetException if appropriate capability is
474: * not set and this object is part of live or compiled scene graph
475: *
476: * @since Java 3D 1.3
477: */
478: public void setImageScaleMode(int imageScaleMode) {
479: if (isLiveOrCompiled())
480: if (!this .getCapability(ALLOW_IMAGE_SCALE_MODE_WRITE))
481: throw new CapabilityNotSetException(J3dI18N
482: .getString("Background9"));
483:
484: switch (imageScaleMode) {
485: case SCALE_NONE:
486: case SCALE_FIT_MIN:
487: case SCALE_FIT_MAX:
488: case SCALE_FIT_ALL:
489: case SCALE_REPEAT:
490: case SCALE_NONE_CENTER:
491: break;
492: default:
493: throw new IllegalArgumentException(J3dI18N
494: .getString("Background11"));
495: }
496:
497: if (isLive())
498: ((BackgroundRetained) this .retained)
499: .setImageScaleMode(imageScaleMode);
500: else
501: ((BackgroundRetained) this .retained)
502: .initImageScaleMode(imageScaleMode);
503:
504: }
505:
506: /**
507: * Retrieves the current image scale mode.
508: * @return the current image scale mode, one of:
509: * SCALE_NONE, SCALE_FIT_MIN, SCALE_FIT_MAX, SCALE_FIT_ALL,
510: * SCALE_REPEAT, or SCALE_NONE_CENTER.
511: *
512: * @exception CapabilityNotSetException if appropriate capability is
513: * not set and this object is part of live or compiled scene graph
514: *
515: * @since Java 3D 1.3
516: */
517: public int getImageScaleMode() {
518: if (isLiveOrCompiled())
519: if (!this .getCapability(ALLOW_IMAGE_SCALE_MODE_READ))
520: throw new CapabilityNotSetException(J3dI18N
521: .getString("Background10"));
522: return ((BackgroundRetained) this .retained).getImageScaleMode();
523: }
524:
525: /**
526: * Sets the background geometry to the specified BranchGroup node.
527: * If non-null, this background geometry is drawn on top of
528: * the background color and image using a projection
529: * matrix that essentially puts the geometry at infinity. The geometry
530: * should be pre-tessellated onto a unit sphere.
531: * @param branch the root of the background geometry
532: * @exception CapabilityNotSetException if appropriate capability is
533: * not set and this object is part of live or compiled scene graph
534: * @exception IllegalSharingException if the BranchGroup node
535: * is a child of any Group node, or is already attached to a Locale,
536: * or is already referenced by another Background node.
537: * @exception IllegalSceneGraphException if specified branch graph
538: * contains an illegal node.
539: */
540: public void setGeometry(BranchGroup branch) {
541: if (isLiveOrCompiled())
542: if (!this .getCapability(ALLOW_GEOMETRY_WRITE))
543: throw new CapabilityNotSetException(J3dI18N
544: .getString("Background5"));
545:
546: if (isLive())
547: ((BackgroundRetained) this .retained).setGeometry(branch);
548: else
549: ((BackgroundRetained) this .retained).initGeometry(branch);
550: }
551:
552: /**
553: * Retrieves the background geometry.
554: * @return the BranchGroup node that is the root of the background
555: * geometry
556: * @exception CapabilityNotSetException if appropriate capability is
557: * not set and this object is part of live or compiled scene graph
558: */
559: public BranchGroup getGeometry() {
560: if (isLiveOrCompiled())
561: if (!this .getCapability(ALLOW_GEOMETRY_READ))
562: throw new CapabilityNotSetException(J3dI18N
563: .getString("Background6"));
564:
565: return ((BackgroundRetained) this .retained).getGeometry();
566: }
567:
568: /**
569: * Set the Background's application region to the specified bounds.
570: * This is used when the application bounding leaf is set to null.
571: * @param region the bounds that contains the Background's new application
572: * region.
573: * @exception CapabilityNotSetException if appropriate capability is
574: * not set and this object is part of live or compiled scene graph
575: */
576: public void setApplicationBounds(Bounds region) {
577: if (isLiveOrCompiled())
578: if (!this .getCapability(ALLOW_APPLICATION_BOUNDS_WRITE))
579: throw new CapabilityNotSetException(J3dI18N
580: .getString("Background7"));
581:
582: if (isLive())
583: ((BackgroundRetained) this .retained)
584: .setApplicationBounds(region);
585: else
586: ((BackgroundRetained) this .retained)
587: .initApplicationBounds(region);
588: }
589:
590: /**
591: * Retrieves the Background node's application bounds.
592: * @return this Background's application bounds information
593: * @exception CapabilityNotSetException if appropriate capability is
594: * not set and this object is part of live or compiled scene graph
595: */
596: public Bounds getApplicationBounds() {
597: if (isLiveOrCompiled())
598: if (!this .getCapability(ALLOW_APPLICATION_BOUNDS_READ))
599: throw new CapabilityNotSetException(J3dI18N
600: .getString("Background8"));
601:
602: return ((BackgroundRetained) this .retained)
603: .getApplicationBounds();
604: }
605:
606: /**
607: * Set the Background's application region to the specified bounding leaf.
608: * When set to a value other than null, this overrides the application
609: * bounds object.
610: * @param region the bounding leaf node used to specify the Background
611: * node's new application region.
612: * @exception CapabilityNotSetException if appropriate capability is
613: * not set and this object is part of live or compiled scene graph
614: */
615: public void setApplicationBoundingLeaf(BoundingLeaf region) {
616: if (isLiveOrCompiled())
617: if (!this .getCapability(ALLOW_APPLICATION_BOUNDS_WRITE))
618: throw new CapabilityNotSetException(J3dI18N
619: .getString("Background7"));
620:
621: if (isLive())
622: ((BackgroundRetained) this .retained)
623: .setApplicationBoundingLeaf(region);
624: else
625: ((BackgroundRetained) this .retained)
626: .initApplicationBoundingLeaf(region);
627: }
628:
629: /**
630: * Retrieves the Background node's application bounding leaf.
631: * @return this Background's application bounding leaf information
632: * @exception CapabilityNotSetException if appropriate capability is
633: * not set and this object is part of live or compiled scene graph
634: */
635: public BoundingLeaf getApplicationBoundingLeaf() {
636: if (isLiveOrCompiled())
637: if (!this .getCapability(ALLOW_APPLICATION_BOUNDS_READ))
638: throw new CapabilityNotSetException(J3dI18N
639: .getString("Background8"));
640:
641: return ((BackgroundRetained) this .retained)
642: .getApplicationBoundingLeaf();
643: }
644:
645: /**
646: * Creates the retained mode BackgroundRetained object that this
647: * Background component object will point to.
648: */
649: void createRetained() {
650: this .retained = new BackgroundRetained();
651: this .retained.setSource(this );
652: }
653:
654: /**
655: * Creates a new instance of the node. This routine is called
656: * by <code>cloneTree</code> to duplicate the current node.
657: * @param forceDuplicate when set to <code>true</code>, causes the
658: * <code>duplicateOnCloneTree</code> flag to be ignored. When
659: * <code>false</code>, the value of each node's
660: * <code>duplicateOnCloneTree</code> variable determines whether
661: * NodeComponent data is duplicated or copied.<br>
662: * Background geometry will not clone in this operation.
663: * It is the user's responsibility
664: * to call <code>cloneTree</code> on that branchGroup.
665: *
666: * @see Node#cloneTree
667: * @see Node#cloneNode
668: * @see Node#duplicateNode
669: * @see NodeComponent#setDuplicateOnCloneTree
670: */
671: public Node cloneNode(boolean forceDuplicate) {
672: Background b = new Background();
673: b.duplicateNode(this , forceDuplicate);
674: return b;
675: }
676:
677: /**
678: * Copies all node information from <code>originalNode</code> into
679: * the current node. This method is called from the
680: * <code>cloneNode</code> method which is, in turn, called by the
681: * <code>cloneTree</code> method.
682: * <P>
683: * For any <code>NodeComponent</code> objects
684: * contained by the object being duplicated, each <code>NodeComponent</code>
685: * object's <code>duplicateOnCloneTree</code> value is used to determine
686: * whether the <code>NodeComponent</code> should be duplicated in the new node
687: * or if just a reference to the current node should be placed in the
688: * new node. This flag can be overridden by setting the
689: * <code>forceDuplicate</code> parameter in the <code>cloneTree</code>
690: * method to <code>true</code>.
691: *
692: * <br>
693: * NOTE: Applications should <i>not</i> call this method directly.
694: * It should only be called by the cloneNode method.
695: *
696: * @param originalNode the original node to duplicate.
697: * @param forceDuplicate when set to <code>true</code>, causes the
698: * <code>duplicateOnCloneTree</code> flag to be ignored. When
699: * <code>false</code>, the value of each node's
700: * <code>duplicateOnCloneTree</code> variable determines whether
701: * NodeComponent data is duplicated or copied.
702: * @exception ClassCastException if originalNode is not an instance of
703: * <code>Background</code>
704: *
705: * @see Node#cloneTree
706: * @see Node#cloneNode
707: * @see NodeComponent#setDuplicateOnCloneTree
708: */
709: public void duplicateNode(Node originalNode, boolean forceDuplicate) {
710: checkDuplicateNode(originalNode, forceDuplicate);
711: }
712:
713: /**
714: * Copies all Background information from
715: * <code>originalNode</code> into
716: * the current node. This method is called from the
717: * <code>cloneNode</code> method which is, in turn, called by the
718: * <code>cloneTree</code> method.<P>
719: *
720: * @param originalNode the original node to duplicate
721: * @param forceDuplicate when set to <code>true</code>, causes the
722: * <code>duplicateOnCloneTree</code> flag to be ignored. When
723: * <code>false</code>, the value of each node's
724: * <code>duplicateOnCloneTree</code> variable determines whether
725: * NodeComponent data is duplicated or copied.
726: *
727: * @exception RestrictedAccessException if this object is part of a live
728: * or compiled scenegraph.
729: *
730: * @see Node#duplicateNode
731: * @see Node#cloneTree
732: * @see NodeComponent#setDuplicateOnCloneTree
733: */
734: void duplicateAttributes(Node originalNode, boolean forceDuplicate) {
735: super .duplicateAttributes(originalNode, forceDuplicate);
736:
737: BackgroundRetained attr = (BackgroundRetained) originalNode.retained;
738: BackgroundRetained rt = (BackgroundRetained) retained;
739:
740: Color3f c = new Color3f();
741: attr.getColor(c);
742: rt.initColor(c);
743: rt.initApplicationBounds(attr.getApplicationBounds());
744: rt.initGeometry(attr.getGeometry());
745: // issue # 563: add call to cloneTree()
746: rt
747: .initGeometry((BranchGroup) (attr.getGeometry() == null ? null
748: : attr.getGeometry().cloneTree(true)));
749: rt
750: .initImage((ImageComponent2D) getNodeComponent(attr
751: .getImage(), forceDuplicate,
752: originalNode.nodeHashtable));
753:
754: // this will be updated in updateNodeReferences
755: rt.initApplicationBoundingLeaf(attr
756: .getApplicationBoundingLeaf());
757: }
758:
759: /**
760: * Callback used to allow a node to check if any scene graph objects
761: * referenced
762: * by that node have been duplicated via a call to <code>cloneTree</code>.
763: * This method is called by <code>cloneTree</code> after all nodes in
764: * the sub-graph have been duplicated. The cloned Leaf node's method
765: * will be called and the Leaf node can then look up any object references
766: * by using the <code>getNewObjectReference</code> method found in the
767: * <code>NodeReferenceTable</code> object. If a match is found, a
768: * reference to the corresponding object in the newly cloned sub-graph
769: * is returned. If no corresponding reference is found, either a
770: * DanglingReferenceException is thrown or a reference to the original
771: * object is returned depending on the value of the
772: * <code>allowDanglingReferences</code> parameter passed in the
773: * <code>cloneTree</code> call.
774: * <p>
775: * NOTE: Applications should <i>not</i> call this method directly.
776: * It should only be called by the cloneTree method.
777: *
778: * @param referenceTable a NodeReferenceTableObject that contains the
779: * <code>getNewObjectReference</code> method needed to search for
780: * new object instances
781: *
782: * @see NodeReferenceTable
783: * @see Node#cloneTree
784: * @see DanglingReferenceException
785: */
786: public void updateNodeReferences(NodeReferenceTable referenceTable) {
787: super .updateNodeReferences(referenceTable);
788:
789: BackgroundRetained rt = (BackgroundRetained) retained;
790: BoundingLeaf bl = rt.getApplicationBoundingLeaf();
791:
792: if (bl != null) {
793: Object o = referenceTable.getNewObjectReference(bl);
794: rt.initApplicationBoundingLeaf((BoundingLeaf) o);
795: }
796: }
797: }
|