📄 config-syntax.html
字号:
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"><!--/* * $RCSfile: config-syntax.html,v $ * * Copyright (c) 2006 Sun Microsystems, Inc. All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * - Redistribution of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * - Redistribution in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in * the documentation and/or other materials provided with the * distribution. * * Neither the name of Sun Microsystems, Inc. or the names of * contributors may be used to endorse or promote products derived * from this software without specific prior written permission. * * This software is provided "AS IS," without a warranty of any * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY * EXCLUDED. SUN MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL * NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF * USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS * DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR * ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL, * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR * INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE * POSSIBILITY OF SUCH DAMAGES. * * You acknowledge that this software is not designed, licensed or * intended for use in the design, construction, operation or * maintenance of any nuclear facility. * * $Revision: 1.3 $ * $Date: 2006/01/05 04:12:00 $ * $State: Exp $ */ --><html><head> <title>The Java 3D Configuration File</title> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta name="Author" content="Mark Hood"></head><body bgcolor="#FFFFFF"><table border="1" cellpadding="3" cellspacing="0" width="100%"><tr bgcolor="#ccccff"><td><font size="+2"><b>The Java 3D Configuration File</b></font></td></tr></table><br><a href="#SyntaxDescription">Syntax Description</a><br><a href="#CommandOverview">Command Overview</a><br><a href="#OverviewOfRelevantViewModelParameters"> Overview of Relevant View Model Parameters</a><br><a href="#TopLevelCommandDetails">Top-Level Command Details</a><br><a href="#BuiltInCommandDetails">Built-In Command Details</a><br><a href="#Command_Index">Command Index</a><br><a href="#Property Index">Property Index</a><br><p>This document is an informal description of the syntax of the Java 3Dconfiguration file and a tutorial of the semantics of its various commands.Such a file is written by a user or site administrator to describe the physicalconfiguration of a local interactive viewing environment. Configurationproperties that can be described in the file include the sizes, positions, andorientations of displays in either fixed screen environments or head mounteddisplays (<i>HMD</i> devices), as well as the input devices and sensorsavailable for user interaction apart from the keyboard and mouse abstractionsprovided by the AWT.</p><p>A configuration file is used by passing its URL to either a ConfigContainer ora ConfiguredUniverse constructor. The method by which a user specifies thefile is up to the application, but the universe utilities do provide a fewmeans to easily enable an application to perform this task. These depend upona Java 3D property, <i>j3d.configURL</i>, that the user can set on the javacommand line with the <i>-D</i> option. Its value should be a URL stringindicating the location of the desired file. The application can then eithercall the static ConfigContainer methods <a href="../ConfigContainer.html#getConfigURL()">getConfigURL</a> to retrieve the value of the property, or<a href="../ConfigContainer.html#getConfigURL(java.lang.String)">getConfigURL(String)</a> to specify a default file to be used in case theproperty is not set. Applications are encouraged to devise their ownuser-friendly mechanisms to retrieve the configuration file, although thesetting of the <i>j3d.configURL</i> property should be honored if at allpossible.</p><p>If the attempt to open the resource indicated by the URL is successful, then aparser will be invoked to read and evaluate the commands it contains anddeposit the results in the ConfigContainer. The parser will detect syntaxerrors, invalid commands, and bad references, printing descriptive messages toSystem.out, including the line number and text of the offending command. Ingeneral the parser attempts to continue processing as much of the file as itcan when encountering an error. Some errors can only be detected after theentire file has been evaluated; in those cases an exception will be thrown.</p><p>An application may choose to override the settings of the configuration file byaccessing view-side scenegraph components directly from the ConfigContaineronce the file is evaluated. Applications should avoid this in general, as mostsettings are physical calibration constants specific to the local interactiveviewing environment. Nonetheless, application overrides are still sometimesappropriate; for example, the application may have knowledge of the contents ofthe scenegraph that enables it to make a better judgement of where the view'sclipping planes should be.</p><br><a name="SyntaxDescription"></a><table border="1" cellpadding="3" cellspacing="0" width="100%"><tr bgcolor="#ccccff"><td><font size="+2"><b>Syntax Description</b></font></td></tr></table><p>The configuration file syntax is very simple; scanning any of the <a href="config-examples.html">sample configuration files</a> should providethe general idea. At the broadest level there are two main types ofconstructs: <i>comments</i> and <i>commands.</i></p><p>Comments can be either <i>C </i>or <i>C++ style. </i>In a C-stylecomment all text between successive occurances of /* and */ is ignored.A C++ comment begins with // and continues to the end of the line.</p><p>A command begins with an opening parenthesis and ends with a closingparenthesis. The elements between the parentheses can be of four types:alphanumeric strings, numbers, quoted strings, or other commands. During theevaluation of a command, any nested command encountered is itself evaluated,and the result of that evaluation replaces the nested command within theoriginal outer command.</p><p>Strings that contain embedded white space, forward slashes, or invalidtokens must be enclosed in quotes (either single or double). Common cases areURL strings and Unix path names. Numbers are any non-quoted strings that canbe parsed as double-precision floating point numbers. The strings <i>true,True, false,</i> and <i>False</i> are converted to their corresponding booleanvalues. Strings, quoted strings, and numbers are delimited from each other bywhite space.</p><p>Commands in the configuration file have four special forms: <i>point,matrix, top-level</i>, and <i>built-in</i> commands.</p><blockquote><h4>Points</h4>A command that consists entirely of two, three, or four numbers is a 2D point,a 3D point, or a 4D point respectively. Any other command that starts with anumber is a syntax error.<p>Don't pass 2D, 3D, or 4D points to commands that expect two, three, or fournumbers instead. This will generate a syntax error indicating an invalidnumber of arguments.</p><h4>Matrices</h4>A 3D matrix is a command that consists entirely of three 3D points. A 4Dmatrix consists entirely of either three or four 4D points; if there are onlythree 4D points then the fourth is implicitly considered to be (0.0 0.0 0.01.0). The points define the row elements of each type of matrix. Any othercommand that starts with a point is a syntax error.<h4>Top-level and built-in commands</h4>All other commands start with an alphanumeric string, the <i>command name</i>which identifies it. The remaining elements of the command are its arguments.<p>Command names can either specify top-level or built-in commands. Top-levelcommands generally configure Java 3D core and utility classes and can onlyappear at the outermost level of parentheses. Built-in commands are providedby the parser itself to help construct the arguments to top-level commands.Points, matrices, and built-in commands can only be nested within othercommands.</p><p>An error will result if points, matrices, or built-in commands are invoked atthe outermost level of nesting. Sometimes this error is caused by prematurelyclosing the opening parenthesis of the current top-level command. Such anerror is usually preceded by an error from the command indicating an invalidnumber of arguments.</p><p>Similarly, errors will be generated if top-level commands are nested. Errorsto this effect are sometimes caused by failing to close all the openparentheses of the preceding top-level command.</p></blockquote><h4>Java property substitution syntax</h4>All strings are additionally scanned for text enclosed by a starting ${ and amatching }. Such text is looked up as a Java system property name and theresult is substituted back into the string after eliding the starting andending delimiters. For example, the command:<p>(Include "file:${user.home}/myBody.cfg")</p><p>would evaluate the contents of the file "myBody.cfg" in the user's homedirectory on Unix systems. An error is issued if no Java property exists withthe specified name.</p><p>Java property substitution happens early, after tokenization but before commandevaluation. Substitution can occur any number of times anywhere within anyquoted or non-quoted string, including command names, property names, andproperty values, as long as the property substitution syntax is not nested.</p><br><a name="CommandOverview"></a><table border="1" cellpadding="3" cellspacing="0" width="100%"><tr bgcolor="#ccccff"><td><font size="+2"><b>Command Overview</b></font></td></tr></table><p>Most top-level commands configure concrete Java 3D core and utility classes.These include PhysicalBody, PhysicalEnvironment, Screen, Sensor, View, andViewPlatform. The Screen, View, and ViewPlatform commands also implicitlyconfigure the Canvas3D core class and the Viewer and ViewingPlatform utilityclasses respectively.</p><p>These commands come in two forms: the <i>New<class name></i> and<i><class name>Property</i> commands. All <i>New</i> commands except <a href="#NewSensor">NewSensor</a> create new class instances and bind names tothem, while the <i>Property</i> commands refer to these names and configuretheir corresponding class instances with the parameters specified by thecommand arguments. All references must be to objects previously instantiatedin the file; forward referencing is not supported. Names must be unique withineach class.</p><p>Implementations of the Java 3D InputDevice interface and concrete subclasses ofthe abstract ViewPlatformBehavior utility class can also be instantiated andconfigured with the same command forms. The <i>New</i> commands for theseobjects accept class names as command arguments and instantiate the objectsthrough introspection. Since the details of the implementations are not known,configuration parameters are passed through methods which are invoked throughintrospection of the method names specified in the <i>Property</i> commandarguments.</p><p>A method invoked through introspection with a <i>Property</i> command gets itsarguments as a single array of Objects. Boolean strings get wrapped intoBoolean objects, and number strings get wrapped into Double. 2D, 3D, and 4Dpoints get wrapped into Point2d, Point3d, and Point4d objects respectively,while 3D and 4D matrices get wrapped into Matrix3d and Matrix4drespectively.</p><br><a name="OverviewOfRelevantViewModelParameters"></a><table border="1" cellpadding="3" cellspacing="0" width="100%"><tr bgcolor="#ccccff"><td><font size="+2"><b>Overview of Relevant View Model Parameters</b></font></td></tr>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -