config-syntax.html

JAVA多媒体开发类库说明

</table>
<p>
The sample configuration files are annotated to assist users in modifying them
to suit their particular viewing environments, but it can be helpful to know
some of the basics of the Java 3D view model that are relevant to writing a
configuration file.  This overview should only be considered an informal
adjunct to the detailed description in the Java 3D Specification.  Reading the
source code to the <a href="../ViewInfo.html">ViewInfo</a> utility (a public
implementation of the Java 3D view model) may also be helpful in understanding
the details of the view model.</p>

<table border="1" cellpadding="3" cellspacing="0" width="100%">
<tr bgcolor="#eeeeff">
<td>
<b>The Camera View Model</b></font></td>
</tr>
</table>
<p>
In the traditional camera model the camera or eyepoint is positioned and
oriented with respect to the virtual world via a view transform.  Objects
contained within the field of view are projected onto an image plane, which is
then mapped onto a display surface, usually a window on a desktop display
system.  While the view direction and camera position can be freely oriented
and placed anywhere in the virtual world, the projection is accomplished using
a static frustum defined by the field of view and a flat image plane centered
about and normal to the view direction.</p>
<p>
This model emulates a typical physical camera quite well, but there are many
viewing configurations that cannot be implemented using image planes that are
fixed with respect to the view direction.  In a multiple screen environment the
projection frustum for each screen is skewed with respect to the image plane,
based on the user's nominal viewing position.  Realistic stereo views on fixed
displays use skewed projection frustums derived from the offsets of the two
eyes from the center of the image plane, while head tracking with fixed
displays involves dynamically adjusting projection frustums in response to
varying eye positions relative to the image plane.</p>
<p>
In a low-level API such as OpenGL these situations are handled by concatenating
all defined model and viewing transforms into a single <i>modelview matrix</i>,
and for a fixed-screen environment explicitly computing the <i>projection
matrix</i> for each eye, each display surface, and each new head
position.  Every application handling such viewing configurations typically
reimplements the framework for computing those matrices itself.  In these cases
it would be useful to be able to separate the projection components out of the
view transform in some representation based on display and eye locations.</p>

<table border="1" cellpadding="3" cellspacing="0" width="100%">
<tr bgcolor="#eeeeff">
<td>
<b>The Java 3D View Model</b></font></td>
</tr>
</table>
<p>
Based on these requirements, a high-level view model should provide standard
mechanisms to 1) define a screen's position and orientation in relation to
other screens in the viewing environment; 2) specify the position of the user's
eyes or an HMD relative to the physical space in which the screens or nominal
user position are defined, and to have them updated automatically if tracking
hardware exists; and 3) describe where the whole physical space is placed and
oriented in the virtual world.  In such a model the appropriate images could
then be rendered without further computation in application code.</p>
<p>
In the Java 3D view model, screen <i>(image plate)</i> positions and
orientations are defined relative to a fixed frame of reference in the physical
world, the <i>tracker base</i>, through the
<a href="#TrackerBaseToImagePlate">TrackerBaseToImagePlate</a> property.  The
tracker base is somewhat abstract in that it is always used to define that
fixed frame of reference, even if no physical tracking hardware is being
used.  If the <a href="#ViewPolicy">ViewPolicy</a> is HMD_VIEW, then the left
and right image plates for head mounted displays are defined relative to the
head tracking sensor, which reports head orientation and position relative to
the tracker base.</p>
<p>
<i>Coexistence coordinates</i> are defined with the 
<a href="#CoexistenceToTrackerBase">CoexistenceToTrackerBase</a> property.  It
provides a frame of reference in the physical world which can be set up by the
user or application in whatever way is most convenient for positioning and
orienting screens, physical body attributes, and sensing devices in the virtual
world.  If tracking is enabled, then the eye positions in coexistence are
computed from the position and orientation of the head tracking sensor and the
<a href="#HeadToHeadTracker">HeadToHeadTracker</a> matrix; otherwise the eye
positions in coexistence are set according to the 
<a href="#CenterEyeInCoexistence">CenterEyeInCoexistence</a> property.  In HMD
mode the eye positions are fixed with respect to the image plates.</p>
<p>
The mapping of coexistence coordinates into the virtual world is accomplished
through the <a href="#ViewAttachPolicy">ViewAttachPolicy</a>, which specifies
the point in coexistence coordinates to which the origin of the <i>view
platform</i> should be mapped.  The view platform is positioned in the virtual
world by manipulating its <i>view transform</i>, the composite of all the
transforms from the view platform up to its Locale.  The basis vectors (X, Y,
and Z directions) of the view platform are always aligned with coexistence
coordinates, and the scaling between view platform coordinates and physical
coordinates is specified by the 
<a href="#ScreenScalePolicy">ScreenScalePolicy</a>, so this
establishes the complete mapping of the physical world into the virtual world.
The projection of the virtual world onto the physical display surfaces is then
performed automatically by the Java 3D renderer.</p>
<p>
By default Java 3D tries to emulate the familiar camera model as much as
possible to make it easy to run in a conventional windowed desktop display
environment.  It accomplishes this through the following default settings:</p>
<ul>
<li>
<a href="#WindowEyepointPolicy">WindowEyepointPolicy</a> is set to
<code>RELATIVE_TO_FIELD_OF_VIEW</code>.</li>
<li>
<a href="#WindowMovementPolicy">WindowMovementPolicy</a> is set to
<code>PHYSICAL_WORLD</code>.</li>
<li>
<a href="#WindowResizePolicy">WindowResizePolicy</a> is set to
<code>PHYSICAL_WORLD</code>.</li>
<li>
<a href="#ViewAttachPolicy">ViewAttachPolicy</a> is set to 
<code>NOMINAL_HEAD</code>.</li>
<li>
<a href="#CoexistenceCenteringEnable">CoexistenceCenteringEnable</a> is set to
true.</li>
</ul>

When a configuration file is being used the defaults are oriented towards
making the setup of multiple screen environments as easy as possible.  If the
coexistence centering enable has not been explicitly set, and either the
CoexistenceToTrackerBase transform for the view has been set or
TrackerBaseToImagePlate has been set for any screen, then the following
defaults are used instead:</p>
<ul>
<li>
<a href="#WindowEyepointPolicy">WindowEyepointPolicy</a> is set to
<code>RELATIVE_TO_COEXISTENCE</code>.</li>
<li>
<a href="#WindowMovementPolicy">WindowMovementPolicy</a> is set to
<code>VIRTUAL_WORLD</code>.</li>
<li>
<a href="#WindowResizePolicy">WindowResizePolicy</a> is set to
<code>VIRTUAL_WORLD</code>.</li>
<li>
<a href="#ViewAttachPolicy">ViewAttachPolicy</a> is set to
<code>NOMINAL_SCREEN</code>.</li>
<li>
<a href="#CoexistenceCenteringEnable">CoexistenceCenteringEnable</a> is set to
false.</li>
</ul>

The avove defaults are also used if coexistence centering enable has been
explictly set false.
<br><br><br>

<a name="TopLevelCommandDetails"></a>
<table border="1" cellpadding="3" cellspacing="0" width="100%">
<tr bgcolor="#ccccff">
<td><font size="+2">
<b>Top-Level Command Details</b></font></td>
</tr>
</table>
<p>
Top-level commands can only appear at the outermost command nesting level.</p>
<hr>

<h2>
<a NAME="NewDevice"></a>NewDevice</h2>
<b>Syntax:</b>
<br>(NewDevice <i>&lt;instance name&gt; &lt;class name&gt;</i>
[Alias <i>&lt;alias name&gt;</i>])
<p>
This command instantiates the InputDevice implementation specified by the fully
qualified <i>class name</i> and binds it to <i>instance name</i>.  The
InputDevice is instantiated through introspection of the class name.  The
implementation must provide a parameterless constructor; this can usually be
done by extending or wrapping available InputDevice implementations.</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>
At the conclusion of configuration file processing all InputDevice
implementations so defined will be initialized and registered with any
PhysicalEnvironments that reference them.<p>
<hr>

<h2>
<a NAME="DeviceProperty"></a>DeviceProperty</h2>
<b>Syntax:</b>
<br>(DeviceProperty <i>&lt;instance name&gt; &lt;method name&gt; &lt;arg0&gt; 
... &lt;argn&gt;</i>)
<p>
The details of the InputDevice implementation specified by <i>instance name</i>
are not known to ConfigContainer, so any parameters to be set through the
configuration file are passed to the InputDevice instance by invoking <i>method
name</i> through introspection.  The arguments following the method name are
evaluated and the results passed to the method as an array of Objects.</p>
<p>
The required methods can usually be provided by extending or wrapping existing
InputDevice implementations.</p>
<hr>

<h2>
<a NAME="NewSensor"></a>NewSensor</h2>
<b>Syntax:</b>
<br>(NewSensor <i>&lt;instance name&gt; &lt;device name&gt; 
&lt;sensor index&gt;</i> [Alias <i>&lt;alias name&gt;</i>])
<p>
Retrieves the Sensor at index <i>sensor index</i> in the InputDevice <i>device
name</i> and binds it to the name specified by <i>instance name</i>.  The
sensor index is a number truncated to its integer value.  The InputDevice
implementation is responsible for creating its own Sensor objects, so this
command does not create any new instances.</p>
<p>
<i>Instance name</i> is used by other commands to reference the indicated
Sensor.  In addition, the name and its associated Sensor instance is made
available to applications through a Map returned by the ConfigContainer
method 
<a href="../ConfigContainer.html#getNamedSensors()">getNamedSensors</a>.
</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>
If the Sensor is to be used for head tracking, or tracking the position and
orientation of other objects in the physical world, then it must generate 6
degree of freedom data relative to the tracker base.</p>
<hr>

<h2>
<a NAME="SensorProperty"></a>SensorProperty</h2>
<b>Syntax:</b>
<br>(SensorProperty <i>&lt;instance name&gt; &lt;property name&gt; 
&lt;property value&gt;</i>)
<p>
Sets a Sensor property.  The sensor 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 sole property may be
configured:</p>

<blockquote>
<h4>
<a NAME="Hotspot"></a>Hotspot</h4>
A 3D point in the sensor's local coordinate system.  The hotspot specifies the
"active" point which should interact with the virtual world, such as a point
used for picking or grabbing an object.  Its actual interpretation is up to the
sensor behavior which uses it.  Its value is ignored for head tracking sensors.
</blockquote>
<hr>

<h2>
<a NAME="NewScreen"></a>NewScreen<br>
<a NAME="NewWindow"></a>NewWindow</h2>
<b>Syntax:</b>
<br>(NewScreen <i>&lt;instance name&gt; &lt;device index&gt;</i>
[Alias <i>&lt;alias name&gt;</i>])
<br>(NewWindow <i>&lt;instance name&gt; &lt;device index&gt;</i>
[Alias <i>&lt;alias name&gt;</i>])
<p>
The above two commands are equivalent.  Both create new window resources and
associate them with the name specified by <i>instance name</i>.  The <i>device
index</i> is a number truncated to its integer value.  This integer is the
index at which the desired AWT GraphicsDevice appears in the array returned by
the static getScreenDevices() method of GraphicsEnvironment, and specifies the
physical screen upon which the window should be created.  The GraphicsDevice
order in the array is specific to the local viewing site and display
system.</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