config-syntax.html

JAVA多媒体开发类库说明

left and right eye positions; there is no actual method in PhysicalBody to set
stereo eye separation, but the results are exactly equivalent.</p>

<h4>
<a NAME="LeftEarPosition"></a>LeftEarPosition</h4>
A 3D point which sets the left ear position relative to head coordinates.
The default is (-0.08, -0.03, 0.09).

<h4>
<a NAME="RightEarPosition"></a>RightEarPosition</h4>
A 3D point which sets the right ear position relative to head coordinates.
The default is (0.08, -0.03, 0.09).

<h4>
<a NAME="HeadToHeadTracker"></a><b>HeadToHeadTracker</b></h4>
A 4D matrix which transforms points from head coordinates to the local
coordinate system of the head tracking sensor.  This allows the positions
of the eyes and ears to be determined from the position and orientation
of the head tracker.  The default is the identity matrix.

<h4>
<a NAME="NominalEyeOffsetFromNominalScreen"></a>
NominalEyeOffsetFromNominalScreen</h4>
A distance in meters used as a calibration parameter for 
<a href="#ViewAttachPolicy">ViewAttachPolicy</a>.  <i>It does not actually set
the position of the eyes</i>.  The property is ignored if ViewAttachPolicy is
NOMINAL_SCREEN.  The default value is 0.4572 meters.

<h4>
<a NAME="NominalEyeHeightFromGround"></a>NominalEyeHeightFromGround</h4>
A distance in meters used as a calibration parameter for 
<a href="#ViewAttachPolicy">ViewAttachPolicy</a>.
<i>It does not actually set the position of the eyes</i>.  This property is
ignored if ViewAttachPolicy is not NOMINAL_FEET.  The default value is 1.68
meters.
</blockquote>
<hr>

<h2>
<a NAME="NewView"></a>NewView</h2>
<b>Syntax:</b>
<br>(NewView <i>&lt;instance name&gt;</i>
[Alias <i>&lt;alias name&gt;</i>])
<p>
Creates a new view and binds it to the name given by <i>instance name.</i>
In the configuration file the term <i>view</i> refers to an instance of the
<a href="../Viewer.html">Viewer</a> utility class, which contains both an
instance of a core Java 3D View class and an array of Canvas3D instances into
which to render.</p>
<p>
The last two arguments are optional and define an alias for <i>instance
name</i>.  This is useful in providing a longer descriptive name for the
application to recognize, or conversely, to provide a shorter alias for a
longer instance name.  Either name may be used to identify the instance.</p>
<p>
ConfiguredUniverse requires that at least one view be defined.  If a view
platform is not provided, then ConfiguredUniverse will create a default one and
attach the view to that.  If multiple views are defined, then at least one view
platform must be explicitly provided by the configuration, and the 
ViewPlatform property must be used to attach each view to a view platform.</p>
<hr>

<h2>
<a NAME="ViewProperty"></a>ViewProperty</h2>
Syntax: <br>
(NewView <i>&lt;instance name&gt; &lt;property name&gt; 
&lt;property value&gt;</i>)
<p>
Sets a View property.  The view instance is specified by <i>instance name</i>,
the property to be set by <i>property name</i>, and the value to be set by
<i>property value</i>.  The following properties are configurable:</p>

<blockquote>
<h4>
<a NAME="Screen"></a>Screen<br>
<a NAME="Window"></a>Window</h4>
These two properties are equivalent.  They include a screen created by
<a href="#NewScreen">NewScreen</a> or a window created by 
<a href="#NewWindow">NewWindow</a> into
this view.  The screen or window name is specified by the <i>property value</i>
string.  Multiple-screen or multiple-window views are created by calling this
command with each window or screen to be used.  If no windows or screens are
defined for this view then an IllegalArgumentException will be thrown after the
configuration file has been processed.

<h4>
<a NAME="PhysicalEnvironment"></a>PhysicalEnvironment</h4>
Sets the PhysicalEnvironment to be used for this view.  The <i>property
value</i> string specifies the name of a PhysicalEnvironment instance created
by the <a href="#NewPhysicalEnvironment">NewPhysicalEnvironment</a> command.
If no PhysicalEnvironment is specified for this view then one with default
values will be created.

<h4>
<a NAME="PhysicalBody"></a>PhysicalBody</h4>
Sets the PhysicalBody to be used for this view.  The <i>property
value</i> string specifies the name of a PhysicalBody instance created
by the <a href="#NewPhysicalBody">NewPhysicalBody</a> command.  If
no PhysicalBody is specified for this view then one with default values
will be created.

<h4>
<a NAME="ViewPlatform"></a>ViewPlatform</h4>
The <i>property value</i> string is the name of a view platform defined by a
previous <a href="#NewViewPlatform">NewViewPlatform</a> command.  This
specifies that the view should be attached to the given view platform.
ConfiguredUniverse requires that a view platform be specified for every defined
view unless only a single view without a view platform is provided; in that
case a view platform is created by default and the view is attached to that.
If one or more view platforms are defined then the view attachments must be
made explicitly.

<h4>
<a NAME="ViewPolicy"></a>ViewPolicy</h4>
The <i>property value</i> string may be either <code>SCREEN_VIEW</code> or
<code>HMD_VIEW</code> to indicate whether fixed room-mounted screens are being
used or a head mounted display.  The default value is <code>SCREEN_VIEW</code>.

<h4>
<a NAME="CoexistenceCenteringEnable"></a>CoexistenceCenteringEnable</h4>
The <i>property value</i> is a boolean string.  If true, then the origin of the
coexistence coordinate system is set to either the middle of the canvas or the
middle of the screen depending upon whether the WindowMovementPolicy is
<code>PHYSICAL_WORLD</code> or <code>VIRTUAL_WORLD</code> respectively.  The X,
Y, and Z directions of coexistence coordinates will point in the same
directions as those of the screen's image plate.
<p>
This only works if a single screen is being used and if both the 
<a href="#TrackerBaseToImagePlate">TrackerBaseToImagePlate</a> and
<a href="#CoexistenceToTrackerBase">CoexistenceToTrackerBase</a> matrices are
identity.  If CoexistenceCenteringEnable is not explicitly set, and either the
CoexistenceToTrackerBase transform for the view has been set or
TrackerBaseToImagePlate has been set for any screen, then the centering enable
will be set to false by default; otherwise, the normal default is true.  This
property is also effectively false whenever the ViewPolicy is set to
<code>HMD_VIEW</code>.</p>

<h4>
<a NAME="WindowEyepointPolicy"></a>WindowEyepointPolicy</h4>
The string value for this property may be either <code>RELATIVE_TO_SCREEN,
RELATIVE_TO_COEXISTENCE, RELATIVE_TO_WINDOW</code>, or
<code>RELATIVE_TO_FIELD_OF_VIEW</code>.  The normal Java 3D default is
<code>RELATIVE_TO_FIELD_OF_VIEW</code>.  When using a configuration file the
default is <code>RELATIVE_TO_COEXISTENCE</code> if 
<a href="#CoexistenceCenteringEnable">CoexistenceCenteringEnable</a> is false,
otherwise the normal default applies.  See the
<a href="../../../../../../javax/media/j3d/View.html#setWindowEyepointPolicy(int)">setWindowEyepointPolicy</a> View method.
<p>
For the <code>RELATIVE_TO_SCREEN</code> and <code>RELATIVE_TO_WINDOW</code>
policies, the eyepoint is set by using the setLeftManualEyeInImagePlate() and
setRightManualEyeInImagePlate() methods of Canvas3D.  The configuration file
currently does not provide any mechanism for altering these properties from
their default values.  These default values are (0.142, 0.135, 0.4572) for the
left eye and (0.208, 0.135, 0.4572) for the right eye.</p>
<p>
These polices are ignored if head tracking is enabled.</p>

<h4>
<a NAME="WindowMovementPolicy"></a>WindowMovementPolicy<br>
<a NAME="WindowResizePolicy"></a>WindowResizePolicy</h4>

The string values for these properties may be either <code>VIRTUAL_WORLD</code>
or <code>PHYSICAL_WORLD</code>.  The normal Java 3D default value for both is
<code>PHYSICAL_WORLD</code>.  When using a configuration file the default
values are <code>VIRTUAL_WORLD</code> if 
<a href="#CoexistenceCenteringEnable">CoexistenceCenteringEnable</a> is false,
otherwise the normal defaults apply.  See the
<a href="../../../../../../javax/media/j3d/View.html#setWindowMovementPolicy(int)">setWindowMovementPolicy</a> and 
<a href="../../../../../../javax/media/j3d/View.html#setWindowResizePolicy(int)">setWindowResizePolicy</a> View methods.</p>

<h4>
<a NAME="CenterEyeInCoexistence"></a>CenterEyeInCoexistence</h4>
A 3D point which specifies the location of the center eye relative to
coexistence coordinates.  See 
<a href="#CoexistenceToTrackerBase">CoexistenceToTrackerBase</a>.  If stereo
viewing is enabled, then the left and right eye positions are set to offsets
from this position using the values specified by the PhysicalBody.  This
property is ignored if head tracking is enabled or if WindowEyepointPolicy is
not <code>RELATIVE_TO_COEXISTENCE</code>.  The default value is (0.0, 0.0,
0.4572).
<p>
This property is a simplified interface to setting the View's left
and right manual eyes in coexistence; there is no actual method in View
to set a center eye position.</p>

<h4>
<a NAME="ScreenScalePolicy"></a>ScreenScalePolicy</h4>
The <i>property value</i> string may be either <code>SCALE_SCREEN_SIZE</code>
or <code>SCALE_EXPLICIT</code> and determines the source of the <i>screen
scale</i>, a factor in the scaling of view platform coordinates to physical
world coordinates.
<p>
If the value is <code>SCALE_SCREEN_SIZE</code>, then the screen scale is half
the physical screen width in meters.  If WindowResizePolicy is
<code>PHYSICAL_WORLD</code>, then this scale is further multiplied by the ratio
of the window width to the width of the screen (the <i>window scale</i>) to
produce the scale from view platform coordinates to physical coordinates.  This
allows a virtual world which spans a normalized width of [-1.0 .. 1.0] in view
platform coordinates to map directly to the physical width of the window or
screen, depending upon the resize policy.</p>
<p>
<code>SCALE_EXPLICIT</code> uses the value of the ScreenScale property as the
screen scale.  It is also further multiplied by the window scale when using the
<code>PHYSICAL_WORLD</code> window resize policy to produce the scale from view
platform coordinates to physical coordinates.  Viewing configurations
incorporating multiple screens should generally set the policy to
<code>SCALE_EXPLICIT</code> and choose a screen scale based on the aggregate
display size, but the default value of <code>SCALE_SCREEN_SIZE</code> will
usually work if all the screens are the same size and arranged in a linear
array.</p>
<p>
The view platform is positioned in the virtual world through a chain of
transforms to the root of the scene graph; this composite transform is its
localToVWorld transform and must be congruent.  If we take the the inverse of
the scale factor in this transform and call it the <i>view platform scale</i>,
then the scale from virtual world units to physical world units can be computed
as the product of this view platform scale, the screen scale, and, when using a
resize policy of <code>PHYSICAL_WORLD</code>, the window scale.  In the usual
case the view platform scale is 1.0.</p>

<h4>
<a NAME="ScreenScale"></a>ScreenScale</h4>
The <i>property value </i>is a number specifying the explicit screen scale
factor.  It is only used if ScreenScalePolicy is <code>SCALE_EXPLICIT</code>;
otherwise, the screen scale is half the physical width of the screen in meters.
The default value for this property is 1.0.

<h4>
<a NAME="BackClipPolicy"></a>BackClipPolicy<br>
<a NAME="FrontClipPolicy"></a>FrontClipPolicy</h4>
The string values of these properties may be either <code>PHYSICAL_EYE,
PHYSICAL_SCREEN, VIRTUAL_EYE</code>, or <code>VIRTUAL_SCREEN</code>.  The
default policies are <code>PHYSICAL_EYE</code>.  See the
<a href="../../../../../../javax/media/j3d/View.html#setFrontClipPolicy(int)">setFrontClipPolicy</a> and 
<a href="../../../../../../javax/media/j3d/View.html#setBackClipPolicy(int)">setBackClipPolicy</a> View methods.

<h4>
<a NAME="FrontClipDistance"></a>FrontClipDistance<br>
<a NAME="BackClipDistance"></a>BackClipDistance</h4>
These property values are numbers.  The defaults are 0.1 and 10.0 
respectively. See the 
<a href="../../../../../../javax/media/j3d/View.html#setFrontClipDistance(double)">setFrontClipDistance</a> and 
<a href="../../../../../../javax/media/j3d/View.html#setBackClipDistance(double)">setBackClipDistance</a> View methods.</p>
<p>
With the default clip policies of <code>PHYSICAL_EYE</code> the clip distances
are measured relative to the eye in physical units, so the clip distances
specified must be scaled to virtual world units in order to determine the
distances in the virtual world where they would effectively be applied.  As
described in the discussion of 
<a href="#ScreenScalePolicy">ScreenScalePolicy</a> above, the scale from
virtual units to physical units is the product of the view platform scale
(usually 1.0), the screen scale, and the window scale (if the window resize
policy is <code>PHYSICAL_WORLD</code>), so normally the scale from physical
units to virtual units would be the inverse of that product.</p>
<p>
There is a quirk, however, with physical clip plane scaling when the
<code>PHYSICAL_EYE</code> or <code>PHYSICAL_SCREEN</code> clip policies are
used with the <code>PHYSICAL_WORLD</code> window resize policy.  The locations
of the clip planes in physical units are not actually set to the physical
distances as specified, but are in fact <i>scaled by the window scale</i>.
This means that when determining where the specified physical clip distances
are in virtual units the scaling to be used is the inverse of the product of
the screen scale and view platform scale only.</p>
<p>
This quirk applies only to scaling physical clip plane distances, and only with
the <code>PHYSICAL_WORLD</code> resize policy.  It was implemented in this
manner to prevent objects in the virtual world from getting clipped