001: /*
002: * $RCSfile: ViewPlatform.java,v $
003: *
004: * Copyright 1997-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.6 $
028: * $Date: 2008/02/28 20:17:33 $
029: * $State: Exp $
030: */
031:
032: package javax.media.j3d;
033:
034: /**
035: * The ViewPlatform leaf node object controls the position, orientation
036: * and scale of the viewer. It is the node in the scene graph that a
037: * View object connects to. A viewer navigates through the virtual
038: * universe by changing the transform in the scene graph hierarchy above
039: * the ViewPlatform.
040: * <p>
041: * <b>The View Attach Policy</b>
042: * <p>
043: * The actual view that Java 3D's renderer draws depends on the view
044: * attach policy specified within the currently attached ViewPlatform.
045: * The view attach policy, set by the setViewAttachPolicy
046: * method, is one of the following:
047: * <p>
048: * <UL>
049: * <LI>View.NOMINAL_HEAD - ensures that the end-user's nominal eye
050: * position in the physical world corresponds to the virtual eye's
051: * nominal eye position in the virtual world (the ViewPlatform's origin).
052: * In essence, this policy tells Java 3D to position the virtual eyepoint
053: * relative to the ViewPlatform origin in the same way as the physical
054: * eyepoint is positioned relative to its nominal physical-world
055: * origin. Deviations in the physical eye's position and orientation from
056: * nominal in the physical world generate corresponding deviations of the
057: * virtual eye's position and orientation in the virtual world. This
058: * is the default view attach policy.</LI>
059: * <p>
060: * <LI>View.NOMINAL_FEET - ensures that the end-user's virtual feet
061: * always touch the virtual ground. This policy tells Java 3D to compute
062: * the physical-to-virtual-world correspondence in a way that enforces
063: * this constraint. Java 3D does so by appropriately offsetting the
064: * physical eye's position by the end-user's physical height. Java 3D
065: * uses the nominalEyeHeightFromGround parameter found in the
066: * PhysicalBody object to perform this computation.</LI>
067: * <p>
068: * <LI>View.NOMINAL_SCREEN - allows an application to always have
069: * the virtual eyepoint appear at some "viewable" distance from a point
070: * of interest. This policy tells Java 3D to compute the
071: * physical-to-virtual-world correspondence in a way
072: * that ensures that the renderer moves the nominal virtual eyepoint
073: * away from the point of interest by the amount specified by the
074: * nominalEyeOffsetFromNominalScreen parameter found in the
075: * PhysicalBody object.</LI></UL>
076: * <p>
077: * <b>Activation Radius</b>
078: * <p>
079: * The ViewPlatform's activation radius defines an activation
080: * volume surrounding the center of the ViewPlatform. This activation
081: * volume is a spherical region that intersects with the scheduling regions
082: * and application regions
083: * of other leaf node objects to determine which of those objects may
084: * affect rendering. Only active view platforms--that is, view platforms
085: * attached to a View--will be used to schedule or select other leaf nodes.
086: * <p>
087: * Different leaf objects interact with the ViewPlatform's activation
088: * volume differently. The Background, Clip, and Soundscape leaf objects
089: * each define a set of attributes and an application region in which
090: * those attributes are applied. If more than one node of a given type
091: * (Background, Clip, or Soundscape) intersects an active ViewPlatform's
092: * activation volume, the "most appropriate" node is selected for that View.
093: * Sound leaf objects and Behavior objects become active when
094: * their scheduling region intersects an active ViewPlatform's activation
095: * volume.
096: * <p>
097: * The activation radius is in view platform coordinates. For the
098: * default screen scale policy of SCALE_SCREEN_SIZE, the
099: * activationRadius parameter value is multiplied by half the
100: * monitor screen size to derive the actual activation radius. For example,
101: * for the default screen size of 0.35 meters, and the default activation
102: * radius value of 62, the actual activation radius would be 10.85
103: * meters.
104: * <p>
105: * <UL>
106: * <code>62 * 0.35 / 2 = 10.85</code>
107: * </UL>
108: * <p>
109: *
110: * @see View
111: */
112:
113: public class ViewPlatform extends Leaf {
114:
115: /**
116: * Specifies that the ViewPlatform allows read access to its view
117: * attach policy information at runtime.
118: */
119: public static final int ALLOW_POLICY_READ = CapabilityBits.VIEW_PLATFORM_ALLOW_POLICY_READ;
120:
121: /**
122: * Specifies that the ViewPlatform allows write access to its view
123: * attach policy information at runtime.
124: */
125: public static final int ALLOW_POLICY_WRITE = CapabilityBits.VIEW_PLATFORM_ALLOW_POLICY_WRITE;
126:
127: // Array for setting default read capabilities
128: private static final int[] readCapabilities = { ALLOW_POLICY_READ };
129:
130: /**
131: * Constructs a ViewPlatform object with default parameters.
132: * The default values are as follows:
133: * <ul>
134: * view attach policy : View.NOMINAL_HEAD<br>
135: * activation radius : 62<br>
136: * </ul>
137: */
138: public ViewPlatform() {
139: // set default read capabilities
140: setDefaultReadCapabilities(readCapabilities);
141: }
142:
143: /**
144: * Creates the retained mode ViewPlatformRetained object that this
145: * ViewPlatform component object will point to.
146: */
147: void createRetained() {
148: this .retained = new ViewPlatformRetained();
149: this .retained.setSource(this );
150: }
151:
152: /**
153: * Sets the view attach policy that determines the coexistence center
154: * in the virtual world. This policy determines how Java 3D places the
155: * view platform relative to the position of the user's head, one of
156: * View.NOMINAL_SCREEN, View.NOMINAL_HEAD, or View.NOMINAL_FEET.
157: * The default policy is View.NOMINAL_HEAD.
158: * @param policy the new policy
159: * @exception CapabilityNotSetException if appropriate capability is
160: * not set and this object is part of live or compiled scene graph
161: * @see View#NOMINAL_SCREEN
162: * @see View#NOMINAL_HEAD
163: * @see View#NOMINAL_FEET
164: */
165: public void setViewAttachPolicy(int policy) {
166: if (isLiveOrCompiled())
167: if (!this .getCapability(ALLOW_POLICY_WRITE))
168: throw new CapabilityNotSetException(J3dI18N
169: .getString("ViewPlatform0"));
170:
171: switch (policy) {
172: case View.NOMINAL_SCREEN:
173: case View.NOMINAL_HEAD:
174: case View.NOMINAL_FEET:
175: break;
176:
177: default:
178: throw new IllegalArgumentException(J3dI18N
179: .getString("ViewPlatform1"));
180: }
181:
182: ((ViewPlatformRetained) this .retained)
183: .setViewAttachPolicy(policy);
184: }
185:
186: /**
187: * Returns the current coexistence center in virtual-world policy.
188: * @return one of: View.NOMINAL_SCREEN, View.NOMINAL_HEAD, or
189: * View.NOMINAL_FEET
190: * @exception CapabilityNotSetException if appropriate capability is
191: * not set and this object is part of live or compiled scene graph
192: */
193: public int getViewAttachPolicy() {
194: if (isLiveOrCompiled())
195: if (!this .getCapability(ALLOW_POLICY_READ))
196: throw new CapabilityNotSetException(J3dI18N
197: .getString("ViewPlatform2"));
198:
199: return ((ViewPlatformRetained) this .retained)
200: .getViewAttachPolicy();
201: }
202:
203: /**
204: * Set the ViewPlatform's activation radius which defines an activation
205: * volume around the view platform.
206: * @param activationRadius the new activation radius
207: */
208: public void setActivationRadius(float activationRadius) {
209: ((ViewPlatformRetained) this .retained)
210: .setActivationRadius(activationRadius);
211: }
212:
213: /**
214: * Get the ViewPlatform's activation radius.
215: * @return the ViewPlatform activation radius
216: */
217: public float getActivationRadius() {
218: return ((ViewPlatformRetained) this .retained)
219: .getActivationRadius();
220: }
221:
222: /**
223: * Used to create a new instance of the node. This routine is called
224: * by <code>cloneTree</code> to duplicate the current node.
225: * <code>cloneNode</code> should be overridden by any user subclassed
226: * objects. All subclasses must have their <code>cloneNode</code>
227: * method consist of the following lines:
228: * <P><blockquote><pre>
229: * public Node cloneNode(boolean forceDuplicate) {
230: * UserSubClass usc = new UserSubClass();
231: * usc.duplicateNode(this, forceDuplicate);
232: * return usc;
233: * }
234: * </pre></blockquote>
235: * @param forceDuplicate when set to <code>true</code>, causes the
236: * <code>duplicateOnCloneTree</code> flag to be ignored. When
237: * <code>false</code>, the value of each node's
238: * <code>duplicateOnCloneTree</code> variable determines whether
239: * NodeComponent data is duplicated or copied.
240: *
241: * @see Node#cloneTree
242: * @see Node#duplicateNode
243: * @see NodeComponent#setDuplicateOnCloneTree
244: */
245: public Node cloneNode(boolean forceDuplicate) {
246: ViewPlatform v = new ViewPlatform();
247: v.duplicateNode(this , forceDuplicate);
248: return v;
249: }
250:
251: /**
252: * Copies all ViewPlatform information from <code>originalNode</code> into
253: * the current node. This method is called from the
254: * <code>duplicateNode</code> method. This routine does
255: * the actual duplication of all "local data" (any data defined in
256: * this object). It then will duplicate the retained side of the
257: * tree if this method was called from its own 2 parameter
258: * <code>duplicateNode</code> method. This is designate by setting the
259: * <code>duplicateRetained</code> flag to <code>true</code>.
260: * Without this flag a <code>duplicateNode</code> method would not
261: * whether or not to duplicate the retained side of the object.
262: *
263: * @param originalNode the original node to duplicate.
264: * @param forceDuplicate when set to <code>true</code>, causes the
265: * <code>duplicateOnCloneTree</code> flag to be ignored. When
266: * <code>false</code>, the value of each node's
267: * <code>duplicateOnCloneTree</code> variable determines whether
268: * NodeComponent data is duplicated or copied.
269: * @param duplicateRetained set to <code>true</code> when this
270: * method is should initiate the duplicateRetained call. This
271: * call walks up a nodes superclasses so it should only be called
272: * once from the class of the original node.
273: *
274: * @see Node#duplicateNode
275: * @see Node#cloneTree
276: * @see NodeComponent#setDuplicateOnCloneTree
277: */
278:
279: void duplicateAttributes(Node originalNode, boolean forceDuplicate) {
280: super .duplicateAttributes(originalNode, forceDuplicate);
281:
282: ViewPlatformRetained attr = (ViewPlatformRetained) originalNode.retained;
283: ViewPlatformRetained rt = (ViewPlatformRetained) retained;
284:
285: rt.setActivationRadius(attr.getActivationRadius());
286: rt.setViewAttachPolicy(attr.getViewAttachPolicy());
287: }
288:
289: }
|