001: /*
002: * $RCSfile: SimpleUniverse.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.7 $
041: * $Date: 2007/02/09 17:20:45 $
042: * $State: Exp $
043: */
044:
045: package com.sun.j3d.utils.universe;
046:
047: import com.sun.j3d.utils.geometry.Primitive;
048: import java.awt.GraphicsEnvironment;
049: import java.awt.GraphicsConfiguration;
050: import java.net.URL;
051:
052: import javax.media.j3d.*;
053:
054: /**
055: * This class sets up a minimal user environment to quickly and easily
056: * get a Java 3D program up and running. This utility class creates
057: * all the necessary objects on the "view" side of the scene graph.
058: * Specifically, this class creates a locale, a single ViewingPlatform,
059: * and a Viewer object (both with their default values).
060: * Many basic Java 3D applications
061: * will find that SimpleUniverse provides all necessary functionality
062: * needed by their applications. More sophisticated applications
063: * may find that they need more control in order to get extra functionality
064: * and will not be able to use this class.
065: *
066: * @see Viewer
067: * @see ViewingPlatform
068: */
069: public class SimpleUniverse extends VirtualUniverse {
070:
071: /**
072: * Locale reference needed to create the "view" portion
073: * of the scene graph.
074: */
075: protected Locale locale;
076:
077: /**
078: * Viewer reference needed to create the "view" portion
079: * of the scene graph.
080: */
081: protected Viewer[] viewer = null;
082:
083: /**
084: * Creates a locale, a single ViewingPlatform, and
085: * and a Viewer object (both with their default values).
086: *
087: * @see Locale
088: * @see Viewer
089: * @see ViewingPlatform
090: */
091: public SimpleUniverse() {
092: // call main constructor with default values.
093: this (null, 1, null, null);
094: }
095:
096: /**
097: * Creates a locale, a single ViewingPlatform, and a Viewer object
098: * (with default values). The ViewingPlatform is created with the
099: * specified number of TransformGroups.
100: *
101: * @param numTransforms The number of transforms to be in the
102: * MultiTransformGroup object.
103: *
104: * @see Locale
105: * @see Viewer
106: * @see ViewingPlatform
107: *
108: * @since Java 3D 1.2.1
109: */
110: public SimpleUniverse(int numTransforms) {
111: // call main constructor with default values except numTransforms
112: this (null, numTransforms, null, null);
113: }
114:
115: /**
116: * Creates a locale, a single ViewingPlatform (with default values), and
117: * and a Viewer object. The Viewer object uses default values for
118: * everything but the canvas.
119: *
120: * @param canvas The canvas to associate with the Viewer object. Passing
121: * in null will cause this parameter to be ignored and a canvas to be
122: * created by the utility.
123: *
124: * @see Locale
125: * @see Viewer
126: * @see ViewingPlatform
127: */
128: public SimpleUniverse(Canvas3D canvas) {
129: // call main constructor with default values for everything but
130: // the canvas parameter.
131: this (null, 1, canvas, null);
132: }
133:
134: /**
135: * Creates a locale, a single ViewingPlatform, and a Viewer object
136: * The Viewer object uses default values for everything but the canvas.
137: * The ViewingPlatform is created with the specified number of
138: * TransformGroups.
139: *
140: * @param canvas The canvas to associate with the Viewer object. Passing
141: * in null will cause this parameter to be ignored and a canvas to be
142: * created by the utility.
143: * @param numTransforms The number of transforms to be in the
144: * MultiTransformGroup object.
145: *
146: * @see Locale
147: * @see Viewer
148: * @see ViewingPlatform
149: * @see MultiTransformGroup
150: *
151: * @since Java 3D 1.2.1
152: */
153: public SimpleUniverse(Canvas3D canvas, int numTransforms) {
154: // call main constructor with default values except canvas
155: // and numTransforms
156: this (null, numTransforms, canvas, null);
157: }
158:
159: /**
160: * Creates a locale, a single ViewingPlatform, and a Viewer object
161: * The Viewer object uses default values for everything but the canvas.
162: * The ViewingPlatform is created with the specified number of
163: * TransformGroups.
164: *
165: * @param canvas The canvas to associate with the Viewer object. Passing
166: * in null will cause this parameter to be ignored and a canvas to be
167: * created by the utility.
168: * @param numTransforms The number of transforms to be in the
169: * MultiTransformGroup object.
170: * @param localeFactory Factory for creating the locale
171: *
172: * @see Locale
173: * @see Viewer
174: * @see ViewingPlatform
175: * @see MultiTransformGroup
176: *
177: * @since Java 3D 1.5.1
178: */
179: public SimpleUniverse(Canvas3D canvas, int numTransforms,
180: LocaleFactory localeFactory) {
181: // call main constructor with default values except canvas,
182: // numTransforms and localeFactory
183: this (null, numTransforms, canvas, null, localeFactory);
184: }
185:
186: /**
187: * Creates the "view" side of the scene graph. The passed in parameters
188: * override the default values where appropriate.
189: *
190: * @param origin The origin used to set the origin of the Locale object.
191: * If this object is null, then 0.0 is used.
192: * @param numTransforms The number of transforms to be in the
193: * MultiTransformGroup object.
194: * @param canvas The canvas to draw into. If this is null, it is
195: * ignored and a canvas will be created by the utility.
196: * @param userConfig The URL to the user's configuration file, used
197: * by the Viewer object. This is never examined and default values are
198: * always taken.
199: *
200: * @see Locale
201: * @see Viewer
202: * @see ViewingPlatform
203: * @see MultiTransformGroup
204: * @deprecated use ConfiguredUniverse constructors to read a
205: * configuration file
206: */
207: public SimpleUniverse(HiResCoord origin, int numTransforms,
208: Canvas3D canvas, URL userConfig) {
209: this (origin, numTransforms, canvas, userConfig, null);
210: }
211:
212: /**
213: * Creates the "view" side of the scene graph. The passed in parameters
214: * override the default values where appropriate.
215: *
216: * @param origin The origin used to set the origin of the Locale object.
217: * If this object is null, then 0.0 is used.
218: * @param numTransforms The number of transforms to be in the
219: * MultiTransformGroup object.
220: * @param canvas The canvas to draw into. If this is null, it is
221: * ignored and a canvas will be created by the utility.
222: * @param userConfig The URL to the user's configuration file, used
223: * by the Viewer object. This is never examined and default values are
224: * always taken.
225: * @param localeFactory The Locale Factory which will instantiate the
226: * locale(s) for this universe.
227: *
228: * @see Locale
229: * @see Viewer
230: * @see ViewingPlatform
231: * @see MultiTransformGroup
232: * @deprecated use ConfiguredUniverse constructors to read a
233: * configuration file
234: */
235: public SimpleUniverse(HiResCoord origin, int numTransforms,
236: Canvas3D canvas, URL userConfig, LocaleFactory localeFactory) {
237: ViewingPlatform vwp;
238:
239: createLocale(origin, localeFactory);
240:
241: // Create the ViewingPlatform and Viewer objects, passing
242: // down the appropriate parameters.
243: vwp = new ViewingPlatform(numTransforms);
244: vwp.setUniverse(this );
245: viewer = new Viewer[1];
246: // viewer[0] = new Viewer(canvas, userConfig);
247: viewer[0] = new Viewer(canvas);
248: viewer[0].setViewingPlatform(vwp);
249:
250: // Add the ViewingPlatform to the locale - the scene
251: // graph is now "live".
252: locale.addBranchGraph(vwp);
253: }
254:
255: /**
256: * Creates the "view" side of the scene graph. The passed in parameters
257: * override the default values where appropriate.
258: *
259: * @param viewingPlatform The viewingPlatform to use to create
260: * the "view" side of the scene graph.
261: * @param viewer The viewer object to use to create
262: * the "view" side of the scene graph.
263: */
264: public SimpleUniverse(ViewingPlatform viewingPlatform, Viewer viewer) {
265: this (viewingPlatform, viewer, null);
266: }
267:
268: /**
269: * Creates the "view" side of the scene graph. The passed in parameters
270: * override the default values where appropriate.
271: *
272: * @param viewingPlatform The viewingPlatform to use to create
273: * the "view" side of the scene graph.
274: * @param viewer The viewer object to use to create
275: * the "view" side of the scene graph.
276: * @param localeFactory The factory used to create the Locale Object
277: */
278: public SimpleUniverse(ViewingPlatform viewingPlatform,
279: Viewer viewer, LocaleFactory localeFactory) {
280: createLocale(null, localeFactory);
281: viewingPlatform.setUniverse(this );
282:
283: // Assign object references.
284: this .viewer = new Viewer[1];
285: this .viewer[0] = viewer;
286:
287: // Add the ViewingPlatform to the Viewer object.
288: this .viewer[0].setViewingPlatform(viewingPlatform);
289:
290: // Add the ViewingPlatform to the locale - the scene
291: // graph is now "live".
292: locale.addBranchGraph(viewingPlatform);
293: }
294:
295: /**
296: * Constructor for use by Configured Universe
297: */
298: SimpleUniverse(HiResCoord origin, LocaleFactory localeFactory) {
299: createLocale(origin, localeFactory);
300: }
301:
302: /**
303: * Create the Locale using the LocaleFactory and HiRes origin,
304: * if specified.
305: */
306: private void createLocale(HiResCoord origin,
307: LocaleFactory localeFactory) {
308:
309: if (localeFactory != null) {
310: if (origin != null)
311: locale = localeFactory.createLocale(this , origin);
312: else
313: locale = localeFactory.createLocale(this );
314: } else {
315: if (origin != null)
316: locale = new Locale(this , origin);
317: else
318: locale = new Locale(this );
319: }
320: }
321:
322: /**
323: * Returns the Locale object associated with this scene graph.
324: *
325: * @return The Locale object used in the construction of this scene
326: * graph.
327: */
328: public Locale getLocale() {
329: return locale;
330: }
331:
332: /**
333: * Returns the Viewer object associated with this scene graph.
334: * SimpleUniverse creates a single Viewer object for use in the
335: * scene graph.
336: *
337: * @return The Viewer object associated with this scene graph.
338: */
339: public Viewer getViewer() {
340: return viewer[0];
341: }
342:
343: /**
344: * Returns the ViewingPlatform object associated with this scene graph.
345: *
346: * @return The ViewingPlatform object of this scene graph.
347: */
348: public ViewingPlatform getViewingPlatform() {
349: return viewer[0].getViewingPlatform();
350: }
351:
352: /**
353: * Returns the Canvas3D object associated with this Java 3D Universe.
354: *
355: * @return A reference to the Canvas3D object associated with the
356: * Viewer object. This method is equivalent to calling getCanvas(0).
357: *
358: * @see Viewer
359: */
360: public Canvas3D getCanvas() {
361: return getCanvas(0);
362: }
363:
364: /**
365: * Returns the Canvas3D object at the specified index associated with
366: * this Java 3D Universe.
367: *
368: * @param canvasNum The index of the Canvas3D object to retrieve.
369: * If there is no Canvas3D object for the given index, null is returned.
370: *
371: * @return A reference to the Canvas3D object associated with the
372: * Viewer object.
373: */
374: public Canvas3D getCanvas(int canvasNum) {
375: return viewer[0].getCanvas3D(canvasNum);
376: }
377:
378: /**
379: * Used to add Nodes to the geometry side (as opposed to the view side)
380: * of the scene graph. This is a short cut to getting the Locale object
381: * and calling that object's addBranchGraph() method.
382: *
383: * @param bg The BranchGroup to attach to this Universe's Locale.
384: */
385: public void addBranchGraph(BranchGroup bg) {
386: locale.addBranchGraph(bg);
387: }
388:
389: /**
390: * Finds the preferred <code>GraphicsConfiguration</code> object
391: * for the system. This object can then be used to create the
392: * Canvas3D objet for this system.
393: *
394: * @return The best <code>GraphicsConfiguration</code> object for
395: * the system.
396: */
397: public static GraphicsConfiguration getPreferredConfiguration() {
398: GraphicsConfigTemplate3D template = new GraphicsConfigTemplate3D();
399: String stereo;
400:
401: // Check if the user has set the Java 3D stereo option.
402: // Getting the system properties causes appletviewer to fail with a
403: // security exception without a try/catch.
404:
405: stereo = (String) java.security.AccessController
406: .doPrivileged(new java.security.PrivilegedAction() {
407: public Object run() {
408: return System.getProperty("j3d.stereo");
409: }
410: });
411:
412: // update template based on properties.
413: if (stereo != null) {
414: if (stereo.equals("REQUIRED"))
415: template.setStereo(template.REQUIRED);
416: else if (stereo.equals("PREFERRED"))
417: template.setStereo(template.PREFERRED);
418: }
419:
420: // Return the GraphicsConfiguration that best fits our needs.
421: return GraphicsEnvironment.getLocalGraphicsEnvironment()
422: .getDefaultScreenDevice()
423: .getBestConfiguration(template);
424: }
425:
426: /**
427: * Cleanup memory use and reference by SimpleUniverse.
428: * Typically it should be invoked by the applet's destroy method.
429: */
430: public void cleanup() {
431: // Get view associated with this SimpleUniverse
432: View view = viewer[0].getView();
433:
434: // Issue 134: cleanup all off-screen canvases
435: for (int i = view.numCanvas3Ds() - 1; i >= 0; i--) {
436: Canvas3D c = view.getCanvas3D(i);
437: if (c.isOffScreen()) {
438: c.setOffScreenBuffer(null);
439: }
440: }
441:
442: // Remove all canvases from view; remove the viewing platform from
443: // this viewer; remove all locales to cleanup the scene graph
444: view.removeAllCanvas3Ds();
445: viewer[0].setViewingPlatform(null);
446: removeAllLocales();
447:
448: // viewerMap cleanup here to prevent memory leak problem.
449: Viewer.clearViewerMap();
450: Primitive.clearGeometryCache();
451:
452: }
453: }
|