javax.media.j3d.ViewPlatform Maven / Gradle / Ivy
/*
* Copyright 1997-2008 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*
*/
package javax.media.j3d;
/**
* The ViewPlatform leaf node object controls the position, orientation
* and scale of the viewer. It is the node in the scene graph that a
* View object connects to. A viewer navigates through the virtual
* universe by changing the transform in the scene graph hierarchy above
* the ViewPlatform.
*
* The View Attach Policy
*
* The actual view that Java 3D's renderer draws depends on the view
* attach policy specified within the currently attached ViewPlatform.
* The view attach policy, set by the setViewAttachPolicy
* method, is one of the following:
*
*
* - View.NOMINAL_HEAD - ensures that the end-user's nominal eye
* position in the physical world corresponds to the virtual eye's
* nominal eye position in the virtual world (the ViewPlatform's origin).
* In essence, this policy tells Java 3D to position the virtual eyepoint
* relative to the ViewPlatform origin in the same way as the physical
* eyepoint is positioned relative to its nominal physical-world
* origin. Deviations in the physical eye's position and orientation from
* nominal in the physical world generate corresponding deviations of the
* virtual eye's position and orientation in the virtual world. This
* is the default view attach policy.
*
*
- View.NOMINAL_FEET - ensures that the end-user's virtual feet
* always touch the virtual ground. This policy tells Java 3D to compute
* the physical-to-virtual-world correspondence in a way that enforces
* this constraint. Java 3D does so by appropriately offsetting the
* physical eye's position by the end-user's physical height. Java 3D
* uses the nominalEyeHeightFromGround parameter found in the
* PhysicalBody object to perform this computation.
*
*
- View.NOMINAL_SCREEN - allows an application to always have
* the virtual eyepoint appear at some "viewable" distance from a point
* of interest. This policy tells Java 3D to compute the
* physical-to-virtual-world correspondence in a way
* that ensures that the renderer moves the nominal virtual eyepoint
* away from the point of interest by the amount specified by the
* nominalEyeOffsetFromNominalScreen parameter found in the
* PhysicalBody object.
*
* Activation Radius
*
* The ViewPlatform's activation radius defines an activation
* volume surrounding the center of the ViewPlatform. This activation
* volume is a spherical region that intersects with the scheduling regions
* and application regions
* of other leaf node objects to determine which of those objects may
* affect rendering. Only active view platforms--that is, view platforms
* attached to a View--will be used to schedule or select other leaf nodes.
*
* Different leaf objects interact with the ViewPlatform's activation
* volume differently. The Background, Clip, and Soundscape leaf objects
* each define a set of attributes and an application region in which
* those attributes are applied. If more than one node of a given type
* (Background, Clip, or Soundscape) intersects an active ViewPlatform's
* activation volume, the "most appropriate" node is selected for that View.
* Sound leaf objects and Behavior objects become active when
* their scheduling region intersects an active ViewPlatform's activation
* volume.
*
* The activation radius is in view platform coordinates. For the
* default screen scale policy of SCALE_SCREEN_SIZE, the
* activationRadius parameter value is multiplied by half the
* monitor screen size to derive the actual activation radius. For example,
* for the default screen size of 0.35 meters, and the default activation
* radius value of 62, the actual activation radius would be 10.85
* meters.
*
*
* 62 * 0.35 / 2 = 10.85
*
*
*
* @see View
*/
public class ViewPlatform extends Leaf {
/**
* Specifies that the ViewPlatform allows read access to its view
* attach policy information at runtime.
*/
public static final int
ALLOW_POLICY_READ = CapabilityBits.VIEW_PLATFORM_ALLOW_POLICY_READ;
/**
* Specifies that the ViewPlatform allows write access to its view
* attach policy information at runtime.
*/
public static final int
ALLOW_POLICY_WRITE = CapabilityBits.VIEW_PLATFORM_ALLOW_POLICY_WRITE;
// Array for setting default read capabilities
private static final int[] readCapabilities = {
ALLOW_POLICY_READ
};
/**
* Constructs a ViewPlatform object with default parameters.
* The default values are as follows:
*
* view attach policy : View.NOMINAL_HEAD
* activation radius : 62
*
*/
public ViewPlatform() {
// set default read capabilities
setDefaultReadCapabilities(readCapabilities);
}
/**
* Creates the retained mode ViewPlatformRetained object that this
* ViewPlatform component object will point to.
*/
@Override
void createRetained() {
this.retained = new ViewPlatformRetained();
this.retained.setSource(this);
}
/**
* Sets the view attach policy that determines the coexistence center
* in the virtual world. This policy determines how Java 3D places the
* view platform relative to the position of the user's head, one of
* View.NOMINAL_SCREEN, View.NOMINAL_HEAD, or View.NOMINAL_FEET.
* The default policy is View.NOMINAL_HEAD.
* @param policy the new policy
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
* @see View#NOMINAL_SCREEN
* @see View#NOMINAL_HEAD
* @see View#NOMINAL_FEET
*/
public void setViewAttachPolicy(int policy) {
if (isLiveOrCompiled())
if(!this.getCapability(ALLOW_POLICY_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("ViewPlatform0"));
switch (policy) {
case View.NOMINAL_SCREEN:
case View.NOMINAL_HEAD:
case View.NOMINAL_FEET:
break;
default:
throw new IllegalArgumentException(J3dI18N.getString("ViewPlatform1"));
}
((ViewPlatformRetained)this.retained).setViewAttachPolicy(policy);
}
/**
* Returns the current coexistence center in virtual-world policy.
* @return one of: View.NOMINAL_SCREEN, View.NOMINAL_HEAD, or
* View.NOMINAL_FEET
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public int getViewAttachPolicy() {
if (isLiveOrCompiled())
if(!this.getCapability(ALLOW_POLICY_READ))
throw new CapabilityNotSetException(J3dI18N.getString("ViewPlatform2"));
return ((ViewPlatformRetained)this.retained).getViewAttachPolicy();
}
/**
* Set the ViewPlatform's activation radius which defines an activation
* volume around the view platform.
* @param activationRadius the new activation radius
*/
public void setActivationRadius(float activationRadius) {
((ViewPlatformRetained)this.retained).setActivationRadius(activationRadius);
}
/**
* Get the ViewPlatform's activation radius.
* @return the ViewPlatform activation radius
*/
public float getActivationRadius() {
return ((ViewPlatformRetained)this.retained).getActivationRadius();
}
/**
* Used to create a new instance of the node. This routine is called
* by cloneTree to duplicate the current node.
* cloneNode should be overridden by any user subclassed
* objects. All subclasses must have their cloneNode
* method consist of the following lines:
*
* public Node cloneNode(boolean forceDuplicate) {
* UserSubClass usc = new UserSubClass();
* usc.duplicateNode(this, forceDuplicate);
* return usc;
* }
*
* @param forceDuplicate when set to true, causes the
* duplicateOnCloneTree flag to be ignored. When
* false, the value of each node's
* duplicateOnCloneTree variable determines whether
* NodeComponent data is duplicated or copied.
*
* @see Node#cloneTree
* @see Node#duplicateNode
* @see NodeComponent#setDuplicateOnCloneTree
*/
@Override
public Node cloneNode(boolean forceDuplicate) {
ViewPlatform v = new ViewPlatform();
v.duplicateNode(this, forceDuplicate);
return v;
}
/**
* Copies all ViewPlatform information from originalNode into
* the current node. This method is called from the
* duplicateNode method. This routine does
* the actual duplication of all "local data" (any data defined in
* this object). It then will duplicate the retained side of the
* tree if this method was called from its own 2 parameter
* duplicateNode method. This is designate by setting the
* duplicateRetained flag to true.
* Without this flag a duplicateNode method would not
* whether or not to duplicate the retained side of the object.
*
* @param originalNode the original node to duplicate.
* @param forceDuplicate when set to true, causes the
* duplicateOnCloneTree flag to be ignored. When
* false, the value of each node's
* duplicateOnCloneTree variable determines whether
* NodeComponent data is duplicated or copied.
* @param duplicateRetained set to true when this
* method is should initiate the duplicateRetained call. This
* call walks up a nodes superclasses so it should only be called
* once from the class of the original node.
*
* @see Node#duplicateNode
* @see Node#cloneTree
* @see NodeComponent#setDuplicateOnCloneTree
*/
@Override
void duplicateAttributes(Node originalNode, boolean forceDuplicate) {
super.duplicateAttributes(originalNode, forceDuplicate);
ViewPlatformRetained attr =
(ViewPlatformRetained) originalNode.retained;
ViewPlatformRetained rt = (ViewPlatformRetained) retained;
rt.setActivationRadius(attr.getActivationRadius());
rt.setViewAttachPolicy(attr.getViewAttachPolicy());
}
}