001: /*
002: * $RCSfile: ConfiguredUniverse.java,v $
003: *
004: * Copyright (c) 2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * Redistribution and use in source and binary forms, with or without
007: * modification, are permitted provided that the following conditions
008: * are met:
009: *
010: * - Redistribution of source code must retain the above copyright
011: * notice, this list of conditions and the following disclaimer.
012: *
013: * - Redistribution in binary form must reproduce the above copyright
014: * notice, this list of conditions and the following disclaimer in
015: * the documentation and/or other materials provided with the
016: * distribution.
017: *
018: * Neither the name of Sun Microsystems, Inc. or the names of
019: * contributors may be used to endorse or promote products derived
020: * from this software without specific prior written permission.
021: *
022: * This software is provided "AS IS," without a warranty of any
023: * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
024: * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY,
025: * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY
026: * EXCLUDED. SUN MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL
027: * NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF
028: * USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS
029: * DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR
030: * ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
031: * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
032: * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR
033: * INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
034: * POSSIBILITY OF SUCH DAMAGES.
035: *
036: * You acknowledge that this software is not designed, licensed or
037: * intended for use in the design, construction, operation or
038: * maintenance of any nuclear facility.
039: *
040: * $Revision: 1.6 $
041: * $Date: 2007/02/09 17:20:44 $
042: * $State: Exp $
043: */
044:
045: package com.sun.j3d.utils.universe;
046:
047: import java.net.URL;
048: import java.net.MalformedURLException;
049: import java.util.Collection;
050: import java.util.Iterator;
051: import java.util.Map;
052: import javax.media.j3d.*;
053:
054: /**
055: * This utility class creates all the necessary objects on the view side of
056: * the scene graph. Specifically, it creates a Locale, one or more
057: * ViewingPlatforms, and at least one Viewer object.<p>
058: *
059: * ConfiguredUniverse can set up a viewing environment based upon the contents
060: * of a configuration file. This allows an application to run without change
061: * across a broad range of viewing configurations, such as windows on
062: * conventional desktops, stereo-enabled views, full screen immersive displays
063: * on single or multiple screens, or virtual reality installations including
064: * cave and head-mounted displays incorporating 6 degree of freedom sensor
065: * devices.<p>
066: *
067: * A configuration file may create InputDevice, Sensor, and
068: * ViewPlatformBehavior instances as well as Viewers and ViewingPlatforms. At
069: * least one Viewer must be provided by the configuration. If a
070: * ViewingPlatform is not provided, a default one will be created and the
071: * Viewer will be attached to it.<p>
072: *
073: * A configuration file may be specified directly by passing a URL to a
074: * ConfiguredUniverse constructor. Alternatively, a ConfigContainer may be
075: * created from a configuration file first, and then passed to an appropriate
076: * ConfiguredUniverse constructor. The latter technique allows Java system
077: * properties that affect Java 3D to be specified in the configuration file,
078: * as long as no references to a VirtualUniverse are made before creating the
079: * container.<p>
080: *
081: * If a configuration file or container is not provided, then
082: * ConfiguredUniverse creates a default viewing environment in the same way as
083: * SimpleUniverse. If one or more Canvas3D objects are provided, it will use
084: * them instead of creating new ones. All of the constructors provided by
085: * SimpleUniverse are also available here.<p>
086: *
087: * The syntax and description of the configuration file may be found
088: * <A href="doc-files/config-syntax.html">here.</a> Example config files can
089: * be found <A href="doc-files/config-examples.html">here.</a>
090: *
091: * @see Locale
092: * @see Viewer
093: * @see ViewingPlatform
094: * @see ConfigContainer
095: * @see <a href="doc-files/config-syntax.html">
096: * The Java 3D Configuration File</a>
097: * @see <a href="doc-files/config-examples.html">
098: * Example Configuration Files</a>
099: *
100: * @since Java 3D 1.3
101: */
102: public class ConfiguredUniverse extends SimpleUniverse {
103:
104: /**
105: * The configuration instance for this universe.
106: */
107: private ConfigContainer configContainer = null;
108:
109: /**
110: * Equivalent to <code>SimpleUniverse()</code>. Creates a
111: * Locale, a single ViewingPlatform, and a Viewer object.
112: *
113: * @see SimpleUniverse#SimpleUniverse()
114: * @see Locale
115: * @see Viewer
116: * @see ViewingPlatform
117: */
118: public ConfiguredUniverse() {
119: super ();
120: }
121:
122: /**
123: * Equivalent to <code>SimpleUniverse(int)</code>.
124: * Creates a Locale, a single ViewingPlatform with the specified number of
125: * transforms, and a Viewer object.
126: *
127: * @param transformCount the number of transforms in the
128: * MultiTransformGroup object to be created
129: *
130: * @see SimpleUniverse#SimpleUniverse(int)
131: * @see Locale
132: * @see Viewer
133: * @see ViewingPlatform
134: * @see MultiTransformGroup
135: */
136: public ConfiguredUniverse(int transformCount) {
137: super (transformCount);
138: }
139:
140: /**
141: * Equivalent to <code>SimpleUniverse(Canvas3D)</code>.
142: * Creates a Locale, a single ViewingPlatform, and a Viewer object using
143: * the given Canvas3D instance.
144: *
145: * @param canvas the canvas to associate with the Viewer object;
146: * passing in null will cause this parameter to be ignored and a canvas
147: * to be created by the utility
148: *
149: * @see SimpleUniverse#SimpleUniverse(Canvas3D)
150: * @see Locale
151: * @see Viewer
152: * @see ViewingPlatform
153: */
154: public ConfiguredUniverse(Canvas3D canvas) {
155: super (canvas);
156: }
157:
158: /**
159: * Equivalent to <code>SimpleUniverse(Canvas3D, int)</code>.
160: * Creates a Locale, a single ViewingPlatform with the specified number of
161: * transforms, and a Viewer object with the given Canvas3D.
162: *
163: * @param canvas the canvas to associate with the Viewer object;
164: * passing in null will cause this parameter to be ignored and a canvas
165: * to be created by the utility
166: * @param transformCount the number of transforms in the
167: * MultiTransformGroup object to be created
168: *
169: * @see SimpleUniverse#SimpleUniverse(Canvas3D, int)
170: * @see Locale
171: * @see Viewer
172: * @see ViewingPlatform
173: * @see MultiTransformGroup
174: */
175: public ConfiguredUniverse(Canvas3D canvas, int transformCount) {
176: super (canvas, transformCount);
177: }
178:
179: /**
180: * Equivalent to <code>SimpleUniverse(ViewingPlatform, Viewer)</code>.
181: * Creates the view side of the scene graph with the given ViewingPlatform
182: * and Viewer.
183: *
184: * @param viewingPlatform the viewingPlatform to use to create
185: * the view side of the scene graph
186: * @param viewer the viewer object to use to create
187: * the view side of the scene graph
188: *
189: * @see SimpleUniverse#SimpleUniverse(ViewingPlatform, Viewer)
190: * @see ViewingPlatform
191: * @see Viewer
192: */
193: public ConfiguredUniverse(ViewingPlatform viewingPlatform,
194: Viewer viewer) {
195: super (viewingPlatform, viewer, null);
196: }
197:
198: /**
199: * Equivalent to <code>SimpleUniverse(ViewingPlatform, Viewer,
200: * LocalFactory)</code>. Creates the view side of the scene graph with
201: * the given ViewingPlatform, Viewer, and Locale created by the specified
202: * LocaleFactory.
203: *
204: * @param viewingPlatform the viewingPlatform to use to create
205: * the view side of the scene graph
206: * @param viewer the viewer object to use to create
207: * the view side of the scene graph
208: * @param localeFactory the factory object used to create the Locale
209: *
210: * @see SimpleUniverse#SimpleUniverse(ViewingPlatform, Viewer,
211: * LocaleFactory)
212: * @see ViewingPlatform
213: * @see Viewer
214: * @see LocaleFactory
215: */
216: public ConfiguredUniverse(ViewingPlatform viewingPlatform,
217: Viewer viewer, LocaleFactory localeFactory) {
218: super (viewingPlatform, viewer, localeFactory);
219: }
220:
221: /**
222: * Creates a Locale, a single ViewingPlatform, and a Viewer object from
223: * the given array of Canvas3D instances.
224: *
225: * @param canvases the canvases to associate with the Viewer object;
226: * passing in null will cause this parameter to be ignored and a canvas
227: * to be created by the utility
228: *
229: * @see Locale
230: * @see Viewer
231: * @see ViewingPlatform
232: */
233: public ConfiguredUniverse(Canvas3D[] canvases) {
234: this (1, canvases, null, null, null, true);
235: }
236:
237: /**
238: * Creates a Locale, a single ViewingPlatform with the specified number of
239: * transforms, and a Viewer object using the given array of Canvas3D
240: * instances.
241: *
242: * @param canvases the canvases to associate with the Viewer object;
243: * passing in null will cause this parameter to be ignored and a canvas
244: * to be created by the utility
245: * @param transformCount the number of transforms in the
246: * MultiTransformGroup object to be created
247: *
248: * @see Locale
249: * @see Viewer
250: * @see ViewingPlatform
251: * @see MultiTransformGroup
252: */
253: public ConfiguredUniverse(Canvas3D[] canvases, int transformCount) {
254: this (transformCount, canvases, null, null, null, true);
255: }
256:
257: /**
258: * Creates a Locale, a single ViewingPlatform with the specified number of
259: * transforms, and a Viewer object using the given array of Canvas3D
260: * instances.
261: *
262: * @param canvases the canvases to associate with the Viewer object;
263: * passing in null will cause this parameter to be ignored and a canvas
264: * to be created by the utility
265: * @param transformCount the number of transforms in the
266: * MultiTransformGroup object to be created
267: * @param localeFactory the factory object used to create the Locale
268: *
269: * @since Java 3D 1.5.1
270: *
271: * @see Locale
272: * @see Viewer
273: * @see ViewingPlatform
274: * @see MultiTransformGroup
275: */
276: public ConfiguredUniverse(Canvas3D[] canvases, int transformCount,
277: LocaleFactory localeFactory) {
278: this (transformCount, canvases, null, localeFactory, null, true);
279: }
280:
281: /**
282: * Reads the configuration specified by the given URL to create a Locale,
283: * one or more ViewingPlatforms, and at least one Viewer object. The
284: * configuration file may also create InputDevice, Sensor, and
285: * ViewPlatformBehavior instances.
286: *
287: * @param userConfig the URL to the user's configuration file; passing in
288: * null creates a default Viewer and ViewingPlatform
289: *
290: * @see Locale
291: * @see Viewer
292: * @see ViewingPlatform
293: */
294: public ConfiguredUniverse(URL userConfig) {
295: this (1, null, userConfig, null, null, true);
296: }
297:
298: /**
299: * Reads the configuration specified by the given URL to create a Locale,
300: * one or more ViewingPlatforms with the specified number of transforms,
301: * and at least one Viewer object. The configuration file may also create
302: * InputDevice, Sensor, and ViewPlatformBehavior instances.
303: *
304: * @param userConfig the URL to the user's configuration file; passing in
305: * null creates a default Viewer and ViewingPlatform with the specified
306: * number of transforms
307: * @param transformCount the number of transforms in the
308: * MultiTransformGroup objects to be created
309: *
310: * @see Locale
311: * @see Viewer
312: * @see ViewingPlatform
313: * @see MultiTransformGroup
314: */
315: public ConfiguredUniverse(URL userConfig, int transformCount) {
316: this (transformCount, null, userConfig, null, null, true);
317: }
318:
319: /**
320: * Reads the configuration specified by the given URL to create a Locale,
321: * one or more ViewingPlatforms with the specified number of transforms,
322: * and at least one Viewer object with optional visibility. AWT
323: * components used by the Viewers will remain invisible unless the
324: * <code>setVisible</code> flag is true. The configuration file may also
325: * create InputDevice, Sensor, and ViewPlatformBehavior instances.
326: *
327: * @param userConfig the URL to the user's configuration file; passing in
328: * null creates a default Viewer with the specified visibility and a
329: * ViewingPlatform with the specified number of transforms
330: * @param transformCount the number of transforms in the
331: * MultiTransformGroup object to be created
332: * @param setVisible if true, calls <code>setVisible(true)</code> on all
333: * created window components; otherwise, they remain invisible
334: *
335: * @see Locale
336: * @see Viewer
337: * @see ViewingPlatform
338: * @see MultiTransformGroup
339: */
340: public ConfiguredUniverse(URL userConfig, int transformCount,
341: boolean setVisible) {
342: this (transformCount, null, userConfig, null, null, setVisible);
343: }
344:
345: /**
346: * Reads the configuration specified by the given URL to create a Locale
347: * using the given LocaleFactory, one or more ViewingPlatforms, and at
348: * least one Viewer object. The configuration file may also create
349: * InputDevice, Sensor, and ViewPlatformBehavior instances.
350: *
351: * @param userConfig the URL to the user's configuration file; passing in
352: * null creates a default Viewer and ViewingPlatform with the specified
353: * number of transforms
354: * @param localeFactory the factory object used to create the Locale
355: *
356: * @see Locale
357: * @see Viewer
358: * @see ViewingPlatform
359: */
360: public ConfiguredUniverse(URL userConfig,
361: LocaleFactory localeFactory) {
362: this (1, null, userConfig, localeFactory, null, true);
363: }
364:
365: /**
366: * Reads the configuration specified by the given URL to create a Locale
367: * using the given LocaleFactory, one or more ViewingPlatforms, and at
368: * least one Viewer object with optional visibility. The configuration
369: * file may also create InputDevice, Sensor, and ViewPlatformBehavior
370: * instances. Window components used by the Viewers will remain invisible
371: * unless the <code>setVisible</code> flag is true.
372: *
373: * @param userConfig the URL to the user's configuration file; passing in
374: * null creates a default Viewer with the specified visibility and a
375: * default ViewingPlatform
376: * @param localeFactory the factory object used to create the Locale
377: * @param setVisible if true, calls <code>setVisible(true)</code> on all
378: * created window components; otherwise, they remain invisible
379: *
380: * @see Locale
381: * @see Viewer
382: * @see ViewingPlatform
383: */
384: public ConfiguredUniverse(URL userConfig,
385: LocaleFactory localeFactory, boolean setVisible) {
386: this (1, null, userConfig, localeFactory, null, setVisible);
387: }
388:
389: /**
390: * Reads the configuration specified by the given URL to create a Locale
391: * using the specified LocaleFactory with the given origin, one or more
392: * ViewingPlatforms with the specified number of transforms, and at least
393: * one Viewer object with optional visibility. Window components used by
394: * the Viewers will remain invisible unless the <code>setVisible</code>
395: * flag is true. The configuration file may also create InputDevice,
396: * Sensor, and ViewPlatformBehavior instances.
397: *
398: * @param userConfig the URL to the user's configuration file; passing in
399: * null creates a default Viewer with the specified visibility and a
400: * ViewingPlatform with the specified number of transforms
401: * @param localeFactory the factory object used to create the Locale
402: * @param origin the origin used to set the origin of the Locale object;
403: * if this object is null, then 0.0 is used
404: * @param transformCount the number of transforms in the
405: * MultiTransformGroup object to be created
406: * @param setVisible if true, calls <code>setVisible(true)</code> on all
407: * created window components; otherwise, they remain invisible
408: *
409: * @see Locale
410: * @see Viewer
411: * @see ViewingPlatform
412: * @see MultiTransformGroup
413: */
414: public ConfiguredUniverse(URL userConfig,
415: LocaleFactory localeFactory, HiResCoord origin,
416: int transformCount, boolean setVisible) {
417:
418: this (transformCount, null, userConfig, localeFactory, origin,
419: setVisible);
420: }
421:
422: /**
423: * Retrieves view-side scenegraph components from the given container to
424: * create a universe with one Locale, one or more ViewingPlatforms, and at
425: * least one Viewer object. Equivalent to
426: * <code>ConfiguredUniverse(ConfigContainer, null, null)</code>.
427: *
428: * @param userConfig container holding viewing configuration components;
429: * must not be null
430: *
431: * @see #ConfiguredUniverse(ConfigContainer, LocaleFactory, HiResCoord)
432: * @see Locale
433: * @see Viewer
434: * @see ViewingPlatform
435: * @since Java 3D 1.3.1
436: */
437: public ConfiguredUniverse(ConfigContainer userConfig) {
438: this (userConfig, null, null);
439: }
440:
441: /**
442: * Retrieves view-side scenegraph components from the given container to
443: * create a universe with one Locale created from the specified
444: * LocaleFactory and origin, one or more ViewingPlatforms, and at least
445: * one Viewer object. The container may also provide InputDevice, Sensor,
446: * and ViewPlatformBehavior instances which will be incorporated into the
447: * universe if they are referenced by any of the Viewer or ViewingPlatform
448: * instances.<p>
449: *
450: * This constructor and <code>ConfiguredUniverse(ConfigContainer)</code>
451: * both accept ConfigContainer references directly and are the preferred
452: * interfaces for constructing universes from configuration files. They
453: * differ from the constructors that accept URL objects in the
454: * following ways:<p>
455: * <ul>
456: * <li>A Viewer will be attached to a default ViewingPlatform only if
457: * no ViewingPlatforms are provided in the ConfigContainer. If one
458: * or more ViewingPlatforms are provided by the ConfigContainer, then
459: * Viewers must be attached to them explicitly in the configuration.<p>
460: * </li>
461: * <li>ViewPlatformBehaviors will be attached to their specified
462: * ViewingPlatforms before ConfiguredUniverse can set a reference to
463: * itself in the ViewingPlatform. This means that a behavior can't
464: * get a reference to the universe at the time its
465: * <code>setViewingPlatform</code> method is called; it must wait
466: * until its <code>initialize</code> method is called.<p>
467: * </li>
468: * <li>All Java properties used by Java 3D may be set in the beginning of
469: * the configuration file as long as there is no reference to a
470: * VirtualUniverse prior to creating the ConfigContainer. Note
471: * however, that some Java 3D utilities and objects such as
472: * Transform3D can cause static references to VirtualUniverse and
473: * trigger the evaluation of Java properties before they are set by
474: * ConfigContainer.<p>
475: * </li>
476: * </ul>
477: * @param userConfig container holding viewing configuration components;
478: * must not be null
479: * @param localeFactory the factory object used to create the Locale, or
480: * null
481: * @param origin the origin used to set the origin of the Locale object;
482: * if this object is null, then 0.0 is used
483: *
484: * @see Locale
485: * @see Viewer
486: * @see ViewingPlatform
487: * @since Java 3D 1.3.1
488: */
489: public ConfiguredUniverse(ConfigContainer userConfig,
490: LocaleFactory localeFactory, HiResCoord origin) {
491:
492: super (origin, localeFactory);
493: configContainer = userConfig;
494:
495: Collection c = configContainer.getViewers();
496: if (c == null || c.size() == 0)
497: throw new IllegalArgumentException(
498: "no views defined in configuration file");
499:
500: viewer = (Viewer[]) c.toArray(new Viewer[1]);
501:
502: c = configContainer.getViewingPlatforms();
503: if (c == null || c.size() == 0) {
504: createDefaultViewingPlatform(configContainer
505: .getViewPlatformTransformCount());
506: } else {
507: Iterator i = c.iterator();
508: while (i.hasNext()) {
509: ViewingPlatform vp = (ViewingPlatform) i.next();
510: vp.setUniverse(this );
511: locale.addBranchGraph(vp);
512: }
513: }
514: }
515:
516: /**
517: * Package-scope constructor that creates the view side of the
518: * scene graph. The passed in parameters override the default
519: * values where appropriate. Note that the userCanvases parameter
520: * is ignored when the userConfig is non-null.
521: *
522: * @param transformCount the number of transforms in the
523: * MultiTransformGroup object to be created
524: * @param canvases the canvases to associate with the Viewer object;
525: * passing in null will cause this parameter to be ignored and a canvas
526: * to be created by the utility
527: * @param userConfig the URL to the user's configuration file; passing in
528: * null causes the default values to be used.
529: * @param localeFactory the factory object used to create the Locale
530: * @param origin the origin used to set the origin of the Locale object;
531: * if this object is null, then 0.0 is used
532: * @param setVisible if true, calls <code>setVisible(true)</code> on all
533: * created window components; otherwise, they remain invisible
534: *
535: * @see Locale
536: * @see Viewer
537: * @see ViewingPlatform
538: * @see MultiTransformGroup
539: */
540: ConfiguredUniverse(int transformCount, Canvas3D[] canvases,
541: URL userConfig, LocaleFactory localeFactory,
542: HiResCoord origin, boolean setVisible) {
543:
544: super (origin, localeFactory);
545:
546: if (userConfig == null) {
547: viewer = new Viewer[1];
548: viewer[0] = new Viewer(canvases, null, null, setVisible);
549: createDefaultViewingPlatform(transformCount);
550: } else {
551: // Create a ConfigContainer without attaching behaviors. The
552: // package-scope constructor is used for backward compatibility.
553: configContainer = new ConfigContainer(userConfig,
554: setVisible, transformCount, false);
555:
556: Collection c = configContainer.getViewers();
557: if (c == null || c.size() == 0)
558: throw new IllegalArgumentException(
559: "no views defined in configuration file");
560:
561: viewer = (Viewer[]) c.toArray(new Viewer[1]);
562:
563: // Get ViewingPlatforms from the ConfigContainer and add them to
564: // the locale. The package-scoped findConfigObjects() accesor is
565: // used so that backward compatibility can be maintained for older
566: // configuration files.
567: c = configContainer.findConfigObjects("ViewPlatform");
568: if (c == null || c.size() == 0) {
569: createDefaultViewingPlatform(transformCount);
570: } else {
571: Iterator i = c.iterator();
572: while (i.hasNext()) {
573: ConfigViewPlatform cvp = (ConfigViewPlatform) i
574: .next();
575: ViewingPlatform vp = cvp.viewingPlatform;
576:
577: // For backward compatibility, handle the default
578: // attachment of one Viewer to one ViewingPlatform. If
579: // there are multiple Viewers and ViewingPlatforms then
580: // attachments must be made explicitly in the config file.
581: if (vp.getViewers() == null && viewer.length == 1
582: && c.size() == 1) {
583: if (cvp.viewAttachPolicy == -1) {
584: setDerivedAttachPolicy(viewer[0], vp);
585: }
586: viewer[0].setViewingPlatform(vp);
587: }
588: vp.setUniverse(this );
589: locale.addBranchGraph(vp);
590:
591: // If there's a behavior associated with the platform,
592: // attach it now after the setting the universe reference.
593: cvp.processBehavior();
594: }
595: }
596: }
597: }
598:
599: /**
600: * Creates a default ViewingPlatform, attaches the first Viewer, and then
601: * attaches the platform to the Locale.
602: *
603: * @param transformCount number of TransformGroups to create in the
604: * ViewingPlatform
605: */
606: private void createDefaultViewingPlatform(int transformCount) {
607: ViewingPlatform vp = new ViewingPlatform(transformCount);
608: setDerivedAttachPolicy(viewer[0], vp);
609: viewer[0].setViewingPlatform(vp);
610: vp.setUniverse(this );
611: locale.addBranchGraph(vp);
612: }
613:
614: /**
615: * Sets a view attach policy appropriate for a window eyepoint policy.
616: *
617: * @param v Viewer to which the ViewingPlatform will be attached
618: * @param vp ViewingPlatform to which the Viewer will be attached
619: */
620: private void setDerivedAttachPolicy(Viewer v, ViewingPlatform vp) {
621: if (v.getView().getWindowEyepointPolicy() != View.RELATIVE_TO_FIELD_OF_VIEW) {
622: vp.getViewPlatform().setViewAttachPolicy(
623: View.NOMINAL_SCREEN);
624: }
625: }
626:
627: /**
628: * Returns the Viewer object specified by the given index.
629: *
630: * @param index The index of which Viewer object to return.
631: *
632: * @return The Viewer object specified by the given index.
633: */
634: public Viewer getViewer(int index) {
635: return viewer[index];
636: }
637:
638: /**
639: * Returns all of the Viewer objects associated with this scene graph.
640: *
641: * @return The Viewer objects associated with this scene graph.
642: */
643: public Viewer[] getViewers() {
644: Viewer[] ret = new Viewer[viewer.length];
645: for (int i = 0; i < viewer.length; i++) {
646: ret[i] = viewer[i];
647: }
648: return ret;
649: }
650:
651: /**
652: * Call <code>setVisible()</code> on all AWT components created by this
653: * ConfiguredUniverse instance.<p>
654: *
655: * @param visible boolean to be passed to the <code>setVisible()</code>
656: * calls on the window components created by this
657: * ConfiguredUniverse instance
658: */
659: public void setVisible(boolean visible) {
660: for (int i = 0; i < viewer.length; i++)
661: if (viewer[i] != null)
662: viewer[i].setVisible(visible);
663: }
664:
665: /**
666: * Returns the config file URL based on system properties. This is
667: * equivalent to calling <code>ConfigContainer.getConfigURL()</code>. The
668: * current implementation of this method parses the j3d.configURL property
669: * as a URL string. For example, the following command line would specify
670: * that the config file is taken from the file "j3dconfig" in the current
671: * directory:
672: * <ul>
673: * <code>java -Dj3d.configURL=file:j3dconfig ...</code>
674: * </ul>
675: *
676: * @return the URL of the config file; null is returned if no valid
677: * URL is defined by the system properties
678: */
679: public static URL getConfigURL() {
680: return ConfigContainer.getConfigURL(null);
681: }
682:
683: /**
684: * Returns the config file URL based on system properties. This is the
685: * same as calling <code>ConfigContainer.getConfigURL(String)</code>. The
686: * current implementation of this method parses the j3d.configURL property
687: * as a URL string. For example, the following command line would specify
688: * that the config file is taken from the file "j3dconfig" in the current
689: * directory:
690: * <ul>
691: * <code>java -Dj3d.configURL=file:j3dconfig ...</code>
692: * </ul>
693: *
694: * @param defaultURLString the default string used to construct
695: * the URL if the appropriate system properties are not defined
696: * @return the URL of the config file; null is returned if no
697: * valid URL is defined either by the system properties or the
698: * default URL string
699: */
700: public static URL getConfigURL(String defaultURLString) {
701: return ConfigContainer.getConfigURL(defaultURLString);
702: }
703:
704: /**
705: * Returns all named Sensors defined by the configuration file used to
706: * create the ConfiguredUniverse, if any. Equivalent to
707: * <code>getConfigContainer().getNamedSensors()</code>.<p>
708: *
709: * With the sole exception of the Sensor assigned to the head tracker,
710: * none of the Sensors defined in the configuration file are placed into
711: * the Sensor array maintained by PhysicalEnvironment. The head tracker
712: * Sensor is the only one read by the Java 3D core and must generate reads
713: * with a full 6 degrees of freedom (3D position and 3D orientation).<p>
714: *
715: * Other Sensors need not generate reads with a full 6 degrees of freedom,
716: * although their reads must be expressed using Transform3D. Some
717: * joysticks may provide only 2D relative X and Y axis movement; dials,
718: * levers, and sliders are 1D devices, and some devices may combine dials
719: * and levers to generate 3D positional data.<p>
720: *
721: * The index names to identify left / right / dominant / non-dominant hand
722: * Sensors in the PhysicalEnvironement Sensor array are not adequate to
723: * distinguish these differences, so this method allows applications to
724: * look up Sensors based on the names bound to them in the configuration
725: * file. There are no set rules on naming. Applications that use Sensors
726: * may set up conventions for generic devices such as "mouse6D" or
727: * "joystick2D" or specific product names.<p>
728: *
729: * @return read-only Map which maps Sensor names to the associated Sensors,
730: * or null if no Sensors have been named
731: */
732: public Map getNamedSensors() {
733: if (configContainer == null)
734: return null;
735: else
736: return configContainer.getNamedSensors();
737: }
738:
739: /**
740: * Returns all named ViewPlatformBehaviors defined by the configuration
741: * file used to create the ConfiguredUniverse, if any. Equivalent
742: * to <code>getConfigContainer().getNamedViewPlatformBehaviors()</code>.<p>
743: *
744: * @return read-only Map which maps behavior names to the associated
745: * ViewPlatformBehavior instances, or null if none have been named.
746: * @since Java 3D 1.3.1
747: */
748: public Map getNamedBehaviors() {
749: if (configContainer == null)
750: return null;
751: else
752: return configContainer.getNamedViewPlatformBehaviors();
753: }
754:
755: /**
756: * Returns a container holding all the objects defined by the
757: * configuration file used to create the ConfiguredUniverse.
758: *
759: * @return the container
760: * @since Java 3D 1.3.1
761: */
762: public ConfigContainer getConfigContainer() {
763: return configContainer;
764: }
765:
766: /**
767: * Cleanup memory references used by ConfiguredUniverse.
768: * @since Java 3D 1.3.1
769: */
770: public void cleanup() {
771: if (viewer != null) {
772: for (int i = 0; i < viewer.length; i++) {
773: viewer[i].getView().removeAllCanvas3Ds();
774: viewer[i].setViewingPlatform(null);
775: viewer[i] = null;
776: }
777: }
778:
779: locale = null;
780: removeAllLocales();
781: Viewer.clearViewerMap();
782:
783: configContainer.clear();
784: configContainer = null;
785: }
786: }
|