📄 config-syntax.html
字号:
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"><!-- @(#)config-syntax.html 1.6 03/04/18 02:59:26 --><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></table><p>The sample configuration files are annotated to assist users in modifying themto suit their particular viewing environments, but it can be helpful to knowsome of the basics of the Java 3D view model that are relevant to writing aconfiguration file. This overview should only be considered an informaladjunct to the detailed description in the Java 3D Specification. Reading thesource code to the <a href="../ViewInfo.html">ViewInfo</a> utility (a publicimplementation of the Java 3D view model) may also be helpful in understandingthe 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 andoriented with respect to the virtual world via a view transform. Objectscontained within the field of view are projected onto an image plane, which isthen mapped onto a display surface, usually a window on a desktop displaysystem. While the view direction and camera position can be freely orientedand placed anywhere in the virtual world, the projection is accomplished usinga static frustum defined by the field of view and a flat image plane centeredabout and normal to the view direction.</p><p>This model emulates a typical physical camera quite well, but there are manyviewing configurations that cannot be implemented using image planes that arefixed with respect to the view direction. In a multiple screen environment theprojection frustum for each screen is skewed with respect to the image plane,based on the user's nominal viewing position. Realistic stereo views on fixeddisplays use skewed projection frustums derived from the offsets of the twoeyes from the center of the image plane, while head tracking with fixeddisplays involves dynamically adjusting projection frustums in response tovarying eye positions relative to the image plane.</p><p>In a low-level API such as OpenGL these situations are handled by concatenatingall defined model and viewing transforms into a single <i>modelview matrix</i>,and for a fixed-screen environment explicitly computing the <i>projectionmatrix</i> for each eye, each display surface, and each new headposition. Every application handling such viewing configurations typicallyreimplements the framework for computing those matrices itself. In these casesit would be useful to be able to separate the projection components out of theview transform in some representation based on display and eye locations.</p>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -