config-syntax.html

JAVA多媒体开发类库说明

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>
<hr>

<h2>
<a NAME="ScreenProperty"></a>ScreenProperty<br>
<a NAME="WindowProperty"></a>WindowProperty</h2>
<b>Syntax:</b>
<br>(ScreenProperty <i>&lt;instance name&gt; &lt;property name&gt; 
&lt;property value></i>)
<br>(WindowProperty <i>&lt;instance name&gt; &lt;property name&gt; 
&lt;property value></i>)
<p>
The above two commands are equivalent.  The screen or window 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="PhysicalScreenWidth"></a>PhysicalScreenWidth</h4> 
A number specifying the screen's image area width in meters.  When using a
configuration file the default is 0.365.  For head mounted displays this should
be the <i>apparent</i> width of the display at the focal plane.

<h4>
<a NAME="PhysicalScreenHeight"></a>PhysicalScreenHeight</h4>
A number specifying the screen's image area height in meters.  When using a
configuration file the default is 0.292.  For head mounted displays this should
be the <i>apparent</i> height of the display at the focal plane.

<h4>
<a NAME="WindowSize"></a>WindowSize</h4> 
This property's value can be a 2D point to create a window with the specified
X width and Y height in pixels, or it can be either of the strings FullScreen
or NoBorderFullScreen to specify a full screen canvas with visible frame
borders or one with no frame borders.  A NoBorderFullScreen canvas uses the
entire physical display surface for its image.  The default value is 512 x 512
pixels.  For multiple screen virtual reality installations or head mounted
displays NoBorderFullScreen should be used.

<h4>
<a NAME="WindowPosition"></a>WindowPosition</h4> 
This property's value is a 2D point used to create a window with the specified
X and Y position.  These are offsets of the window's upper left corner from the
screen's upper left corner.

<h4>
<a NAME="TrackerBaseToImagePlate"></a>TrackerBaseToImagePlate</h4>
A 4D matrix which transforms points from tracker base coordinates to the image
plate coordinates for the specified screen.  This is only used when a
ViewPolicy of <code>SCREEN_VIEW</code> is in effect.  The matrix value is
identity by default.
<p>
Image plate dimensions are expressed in meters.  The origin of the image plate
is the lower left corner of the screen's image area, with X increasing to the
right, Y increasing to the top, and Z increasing away from the screen.</p>
<p>
The tracker base is somewhat abstract.  It is used as a local fixed frame of
reference for specifying the orientation and position of a screen <i>even when
tracking hardware is not being used</i>.  It is also the frame of reference for
defining coexistence coordinates with the 
<a href="#CoexistenceToTrackerBase">CoexistenceToTrackerBase</a> matrix.</p>
<p>
The <a href="#BuiltInCommandDetails">built-in commands</a> Translate,
Rotate, RotateTranslate, and TranslateRotate are available to make it easier
to create transforms of this type.

<h4>
<a NAME="HeadTrackerToLeftImagePlate"></a>HeadTrackerToLeftImagePlate<br>
<a NAME="HeadTrackerToRightImagePlate"></a>HeadTrackerToRightImagePlate</h4>
4D matrices which transform points in the head tracking sensor's local
coordinate system to a head mounted display's left and right image plates
respectively. The default value for each is the identity matrix.</p>
<p>
These are only used when a ViewPolicy of <code>HMD_VIEW</code> is in effect.
As with physical screen dimensions, these matrices should indicate the
<i>apparent</i> location and orientation of the screen images as viewed through
the head mounted display's optics.</p>
<p>
The HMD manufacturer's specifications in terms of angle of view, distance to
the focal plane, aspect ratio, and percentage of image overlap between the left
and right views can be used to derive the apparent screen positions with
respect to the head, and from there the positions with respect to the head
tracker mounted on the head.  In most cases there is 100% overlap between the
two stereo images, so the matrices for both the left and right screens should
be identical.</p>
<p>
Some HMD devices support field-sequential stereo and are driven as if they were
a single screen.  In that case, only a single screen should be defined, but
<i>both</i> the left and right head tracker to image plate transforms need to
be specified for that same screen.</p>

<h4>
<a NAME="MonoscopicViewPolicy"></a>MonoscopicViewPolicy</h4>
This property may have the following string values: <code>CYCLOPEAN_EYE_VIEW,
LEFT_EYE_VIEW</code>, or <code>RIGHT_EYE_VIEW</code>.  The default value is
<code>CYCLOPEAN_EYE_VIEW</code>.  This default works for non-stereo displays
and field-sequential stereo displays where the two stereo images are generated
on the same canvas.</p>
<p>
Some HMD devices can be driven as a single screen if the HMD supports
field-sequential stereo, so the default policy will work for them as well if a
stereo view is enabled. If stereo is not enabled, an IllegalStateException will
be thrown when the ViewPolicy is set to <code>HMD_VIEW</code> with the default
<code>CYCLOPEAN_EYE_VIEW</code> policy in effect.</p>
<p>
The <code>LEFT_EYE_VIEW</code> and <code>RIGHT_EYE_VIEW</code> monoscopic view
policies are used for generating stereo pairs on separate monoscopic canvases,
including the left and right canvases needed by HMD devices that are driven by
two video channels.  When using these policies, stereo should <i>not</i> be
enabled.</p>
</blockquote>
<hr>

<h2>
<a NAME="NewPhysicalEnvironment"></a>NewPhysicalEnvironment</h2>
<b>Syntax:</b>
<br>(NewPhysicalEnvironment <i>&lt;instance name&gt;</i>
[Alias <i>&lt;alias name&gt;</i>])
<p>
Creates a new PhysicalEnvironment and binds it to the name given by <i>instance
name.</i> This specifies the available input devices, which Sensor to use as
the head tracker, and defines the coexistence coordinate system.  Note that
aside from the head tracker, the configuration file does not provide a way to
place Sensors into the array maintained by the PhysicalEnvironment.  See the 
<a href="../ConfigContainer.html#getNamedSensors()">getNamedSensors</a>
method of ConfigContainer.</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>
<hr>

<h2>
<a NAME="PhysicalEnvironmentProperty"></a>PhysicalEnvironmentProperty</h2>
<b>Syntax:</b>
<br>(PhysicalEnvironmentProperty <i>&lt;instance name&gt;
&lt;property name&gt; &lt;property value&gt;</i>)
<p>
Sets a PhysicalEnvironment property.  The 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="InputDevice"></a>InputDevice</h4>
Register an InputDevice implementation instantiated by 
<a href="#NewDevice">NewDevice.</a> The InputDevice instance name is specified
by the <i>property value</i> string.  If an InputDevice is not registered then
it will not be scheduled to run.

<h4>
<a NAME="HeadTracker"></a>HeadTracker</h4>
Register the Sensor which will be used for head tracking.  It must provide 6
degree of freedom position and orientation reads relative to the tracker base.
The Sensor instance name is specified by the <i>property value</i> string.
Its corresponding input device must be registered with the InputDevice
property.
<p>
There is no actual method in the core PhysicalEnvironment class to set the head
tracker.  This property is a simplified interface for setting the
PhysicalEnvironment head index and assigning the head tracking sensor to that
index.  Direct access to the PhysicalEnvironment Sensor array is not supported
by the configuration file.</p>

<h4>
<a NAME="CoexistenceToTrackerBase"></a>CoexistenceToTrackerBase</h4>
A 4D matrix which transforms points in coexistence coordinates to tracker base
coordinates.  This defines the position and orientation of coexistence
coordinates relative to the tracker base.  Its default value is the identity
matrix, so if it is not set then coexistence coordinates will be the same as
tracker base coordinates.  See 
<a href="#TrackerBaseToImagePlate">TrackerBaseToImagePlate.</a>
<p>
The coexistence origin (<i>center of coexistence</i>) positions the physical
world with respect to the origin of the ViewPlatform in the virtual world.
This is established through the 
<a href="#ViewAttachPolicy">ViewAttachPolicy</a>, which attaches the view
platform to either the center of coexistence, the nominal head, or the nominal
feet.  Coexistence coordinates can essentially be thought of as physical
coordinates, but the real purpose is to define the space in which coordinates
systems in the physical world - such as tracker base, image plate, and physical
body - coexist and interact with the virtual world coordinate systems.</p>
<p>
The basis vectors (X, Y, and Z directions) of coexistence coordinates are
always aligned with the basis vectors of the ViewPlatform in the virtual world,
and the scale factor going from ViewPlatform coordinates to coexistence
coordinates is set by the <a href="#ScreenScalePolicy">ScreenScalePolicy</a>.
Together with the ViewPlatform's view attach policy and view transform this
establishes the complete mapping of the physical world into the virtual
world.</p>
<p>
The positioning and orientation of coexistence coordinates with respect to the
physical environment is up to the user or application.  In a fixed screen
environment it usually makes most sense to define it in a convenient
relationship to the primary screen or some intersection of the available
screens, such that the coexistence origin is in front of and aligned with the
user's nominal forward gaze direction.  This is because the -Z axis of
coexistence coordinates always points along the view direction defined by the
view platform's -Z axis.</p>
<p>
For example, when using a single screen, the most common mapping puts the
center of coexistence in the middle of the screen with its basis vectors
aligned with the screen's image plate coordinate system.  With a dual-screen
system it is usually most convenient to place the center of coexistence in the
middle of the edge shared by both screens, with its Z axis extending
perpendicular to the shared edge and maintaining an equal angle to both
screens.  For a 2x2 array of four screens putting the center of coexistence at
the center of the array is usually a good choice.  In a cave configuration
having the center of coexistence in the middle of the viewing environment can
facilitate the sense of immersion.</p>
<p>
In HMD mode the view attach policy is ignored and is always effectively
<code>NOMINAL_SCREEN</code>.  Coexistence coordinates and view platform
coordinates are then equivalent except for scale.  For HMD configurations
placing the coexistence coordinate system aligned with some nominal
front-facing user position works well.</p>
<p>
<b>Note:</b> the normal Java 3D default is to place the center of coexistence
in the middle of the screen or canvas by setting 
<a href="#CoexistenceCenteringEnable">CoexistenceCenteringEnable</a> true by
default.  This only works for a single screen and if both the
TrackerBaseToImagePlate and CoexistenceToTrackerBase matrices are identity.  If
either of these matrices are set from their default identity values in the
configuration file, and CoexistenceCenteringEnable has not been set, then the
centering property will be set false by default.<p>
</blockquote>
<hr>

<h2>
<a NAME="NewPhysicalBody"></a>NewPhysicalBody</h2>
<b>Syntax:</b>
<br>(NewPhysicalBody <i>&lt;instance name&gt;</i>
[Alias <i>&lt;alias name&gt;</i>])
<p>
Creates a new PhysicalBody and binds it to the name given by <i>instance
name</i>.  The PhysicalBody is essentiallly the users's head, with the origin
halfway between the eyes in the plane of the face.  Positive X extends to the
right eye, positive Y up, and positive Z extends into the skull opposite to the
forward gaze direction.  Dimensions are expressed in meters.</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>
<hr>

<h2>
<a NAME="PhysicalBodyProperty"></a>PhysicalBodyProperty</h2>
<b>Syntax:</b>
<br>(PhysicalBodyProperty <i>&lt;instance name&gt; &lt;property name&gt;
&lt;property value&gt;</i>)
<p>
Sets a PhysicalBody property.  The 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="StereoEyeSeparation"></a>StereoEyeSeparation</h4>
A number indicating the interpupilary distance in meters.  This will set the
left and right eye positions to offsets of half this distance from the head
origin along its X axis.  The default is 0.066 meters.
<p>
This property is a simplified interface to setting the PhysicalBody's separate