<html>
<head>
<style type="text/css">
.fragment {
font-family: monospace
}
PRE.fragment {
border: 1px solid #CCCCCC;
background-color: #f5f5f5;
margin-top: 4px;
margin-bottom: 4px;
margin-left: 2px;
margin-right: 8px;
padding-left: 6px;
padding-right: 6px;
padding-top: 4px;
padding-bottom: 4px;
}
</style>
</head>
<body>
<h1>Scenery description in XML</h1>
<h2>0 About this document</h2>
<p>
This document describes version 3 of the CRRCsim scenery file format.
</p>
<p>
<b>Disclaimer:</b> This document is not complete yet. It may be inaccurate
or wrong, too.
</p>
<p>
This document does not provide complete examples. Please take a look at
the scenery files you got when downloading/installing CRRCsim. The file
<tt>simple.xml</tt> in CRRCsim's <tt>scenery</tt> folder demonstrates
many of the features discussed in this document.
</p>
<p>
You need to know basics about xml files: they are structured text. Whitespace
and line breaks do not matter in most places. Just take a look at the
examples and you will understand.
</p>
<p>
The files can be edited using a text editor. There are lots of them. Use
something like Notepad++, vi, emacs, joe... Even the standard Windows notepad
will do, but it is recommended to use an editor that features syntax
highlighting for XML files to spot any obvious formatting errors immediately.
</p>
<h3>0.1 Changes</h3>
<table border="1">
<tr><td>2010-01-01</td><td>J. Reucker</td>
<td>
First version of this document.
</td>
</tr>
<tr><td>2010-01-09</td><td>J. Reucker</td>
<td>
Added details about rotation axes in model based scenery.
</td>
</tr>
<tr><td>2010-05-16</td><td>J. Reucker</td>
<td>
Changed sky definition schema: Now multiple sky sections are allowed
in a single XML file.
</td>
</tr>
</table>
<h2>1 General information</h2>
<p>Like most other XML files used in CRRCsim, a scenery description starts with
the XML file header and a changelog.
Whenever you edit such a file, please add a new <tt>change</tt> section and fill
in what is needed. The example below shows a template.</p>
<div class="fragment"><pre class="fragment">
<?xml version="1.0"?>
<crrcsimSceneryFile version="4">
<!-- Some general information -->
<name>My scenery</name>
<categories>
<category>Field</category>
</categories>
<description>
<en>My first scenery file for CRRCsim.</en>
</description>
<changelog>
<change>
<date>2009-12-20</date>
<author>Jan Reucker (slowhand_47@gmx.de)</author>
<en>Created.</en>
</change>
</changelog>
</pre></div>
<p>Every text is written in english, so it is enclosed in <tt><en> </en></tt>.
If you want to add something in italian for example, you should enclose it in
<tt><it> </it></tt>. <i>Other languages than <tt>en</tt> are not
supported yet by CRRCsim, so at the time of writing information in other languages
is solely visible for those reading or editing your scenery file directly.</i></p>
<h2>2 Units</h2>
<p>
All numeric attribute values in a scenery file are written as plain numbers
without engineering units. All length or position values are assumed to
be in feet (ft).
</p>
<h2>3 Coordinate system</h2>
<p>
All positional values are specified using the following attributes:
<table border ="1">
<tr><th>Attribute</th>
<th>Axis (internal)</th>
<th>Direction</th></tr>
<tr><td>north</td><td>x</td><td>positive north, negative south</td></tr>
<tr><td>east</td><td>y</td><td>positive east, negative west</td></tr>
<tr><td>height</td><td>-z</td><td>positive up, negative down</td></tr>
</table>
</p>
<p>The attributes listed in the table above are used in all tags
specifying some kind of position. In earlier versions of CRRCsim, the
attributes <tt>x</tt>, <tt>y</tt> and <tt>z</tt> were used. This is
still possible for specifying object positions in a model-based
scenery (for compatibility reasons), but it's strongly discouraged and
may be removed in future versions of CRRCsim without further notice.</p>
<h2>4 Player positions: section <tt>views</tt></h2>
<p>This section defines possible viewpoints for the player. <i>Currently
CRRCsim will only use the first <tt>position</tt> that is found in the <tt>views</tt>
section.</i></p>
<div class="fragment"><pre class="fragment">
<views>
<position name="default" north="0" east="0" height="4" />
</views>
</pre></div>
<h2>5 Starting positions: section <tt>start</tt></h2>
<p>The starting position for the model. As with
the player position, you may specify more than one starting location. The
topmost position will be used as default.</p>
<div class="fragment"><pre class="fragment">
<start>
<position name="field" north="0" east="0" height="4" />
</start>
</pre></div>
<h2>6 Default values: section <tt>default</tt></h2>
<p>Some default values. Right now, you may only specify the default wind
parameters.</p>
<div class="fragment"><pre class="fragment">
<default>
<wind velocity="3" direction="180" />
</default>
</pre></div>
<h2>7 Appearance of the sky: section <tt>sky</tt></h2>
<p>
The appearance of the sky is determined by the <tt><sky></tt> tag.
There are two different types of sky available: a sky dome and a sky box.
A scenery file can contain an arbitrary number of sky definitions. This
allows for simulating different weather conditions or time of day, or
providing different texture resolutions to adapt textured skies to the
available GPU power.
</p>
<h3>7.1 General description</h3>
<p>
The sky section should contain a brief description, which is in turn
composed of a long and a short description. The short description is used
in menus or list boxes, while the long description may contain some more
information.
</p>
<div class="fragment"><pre class="fragment">
<descr_short>
<en>default</en>
</descr_short>
<descr_long>
<en>The default sky box with 512x512 pixel textures.</en>
</descr_long>
</pre></div>
<h3>7.2 Sky dome</h3>
<p>
The sky dome produces a sky like in the first CRRCsim version.
Think of it as a textured semi-sphere above your head. You can set the
texture and the radius of the semi-sphere.
</p>
<div class="fragment"><pre class="fragment">
<sky type="original" texture="textures/clouds.rgb" radius="10000">
<descr_short>
<en>original</en>
</descr_short>
<descr_long>
<en>The original CRRCsim textured sky dome.</en>
</descr_long>
</sky>
</pre></div>
<p>If you omit the texture name, CRRCsim will generate an untextured but
colored (from grey haze on the horizon to deep blue in the zenith)
semi-sphere. This may help those people with broken OpenGL implementations
that don't get the textured dome right.</p>
<div class="fragment"><pre class="fragment">
<sky type="original" />
</pre></div>
<h3>7.3 Sky box</h3>
<p>After CRRCsim version 0.9.6, a new sky rendering method was implemented:
The sky box. It's nothing but a cube with the viewer/player in the middle.
A texture can be projected onto each cube face. If the textures are
seamless and feature the right kind of distortion for the cubical
projection, this will give a very realistic impression of the sky.</p>
<div class="fragment"><pre class="fragment">
<sky type="box" size="10.0">
<descr_short>
<en>default</en>
</descr_short>
<descr_long>
<en>The default sky box with 512x512 pixel textures.</en>
</descr_long>
<textures>
<north filename="textures/skybox_n.rgb" />
<south filename="textures/skybox_s.rgb" />
<west filename="textures/skybox_w.rgb" />
<east filename="textures/skybox_e.rgb" />
<up filename="textures/skybox_u.rgb" />
<down filename="" />
</textures>
</sky>
</pre></div>
<p>Cube faces without a texture will not be rendered.</p>
<p>There are several tools available that deal with artificial landscape/sky
generation. Most of them should be able to generate a set of textures for the
sky box. TerraGen, for example, works like a charm. Just generate a flat
terrain (remember, we're interested in the sky, not the terrain!) and set up
the sky. Set up the camera with a 90 degrees field of vision (FOV) in the
center of the terrain at zero altitude, zero pitch, heading north. Render
a 512x512 pixel image (or any other power-of-two square format, like 256x256
or 1024x1024, if your graphics card can handle it). This is the "north"
texture. Now only change the camera heading to 90 deg. and render the
"east" texture, while 180 deg. and 270 deg. are the setups for
"south" and "west". Then point the camera back north and
pitch it up 90 degrees to render the "up" texture. If you also want
to add a "down" texture, pitch the camera down to -90 degrees while
looking north and render. Remember to save all textures after rendering! The
textures will be saved as ".bmp" (Windows bitmap) files, please
convert them to SGI format (".rgb", turning on RLE compression is
strongly recommended). Then fill in the texture names in the XML file, copy
the textures to the "textures" subdirectory and enjoy your new sky.
</p>
<h2>8 The scene description: section <tt>scene</tt></h2>
<p>The last tag in the current files tells CRRCsim what to render in addition
to the sky. This description starts with the <tt>scene</tt> tag. The
<tt>type</tt> attribute of this tag defines the semantics of the tags inside
the <tt>scene</tt> section.</p>
<p> The optional <tt>altitude</tt> attribute of this tag defines the altitude (in feets) of scenery. It is useful in scenery of mountain to take into account the variation of air density. The height parameters in the scenery description are values relative to this altitude.<p>
<h3>Built-in sceneries: <tt>type="built-in"</tt></h3>
<p>There are two built-in sceneries in CRRCsim: Davis field and the slope at
Cape Cod. To render these sceneries, specify either <tt>DAVIS</tt> or
<tt>CAPE_COD</tt> as the value of the <tt>variant</tt> attribute of the
<tt>scene</tt> tag.</p>
<p>Rendering the Davis field scenery:</p>
<div class="fragment"><pre class="fragment">
<scene type="built-in" variant="DAVIS" />
</pre></div>
<p>Rendering the Cape Cod scenery:</p>
<div class="fragment"><pre class="fragment">
<scene type="built-in" variant="CAPE_COD" />
</pre></div>
<p>There's nothing more to configure for these <tt>scene</tt> variants.</p>
<h3>Model-based sceneries: <tt>type="model-based"</tt></h3>
<h4>Adding objects to the scenery</h4>
<p>Everything between <scene> and </scene> describes graphical
objects. The order of the objects is not important.</p>
<p>The <tt>object</tt> tag loads a 3D model and adds it to the scenery.
A lot of different file formats are supported. AC3D files (.ac) and
(.3ds) should work quite well. In theory, the SSG library loads many more
formats (.x, .dxf, .ase, .atg, .mdl, .flt, .m, .md2, .obj, .tri, VRML), but
this is not yet tested with CRRCsim due to the lack of models. Other
SSG-based projects show that it works.</p>
<p>A <tt>terrain</tt> attribute declares the object to be part of the terrain
contour. This means that the object will add to the terrain height at this
point and therefore be included in wind calculations. Be careful, each
<tt>terrain</tt> object will also increase the CPU workload more than
non-terrain-objects! The default value for the <tt>terrain</tt> attribute
is "1", so <tt>terrain="0"</tt> must explicitely be
specified to exclude an object from terrain height calculations.</p>
<p>An object can be loaded once and then placed several times in the scenery.
This saves texture memory, because all textures are shared between the
instances of the object. Each instance must have position coordinates
(<tt>north</tt>|<tt>east</tt>|<tt>height</tt>) and optional orientation
parameters (<tt>h</tt>|<tt>p</tt>|<tt>r</tt> for heading, pitch and roll).
North, east and height coordinates must always be specified as absolute world
coordinates (remember, the unit is "ft."). Heading, pitch and roll
are related to local body coordinates of the object (in degrees). The
orientation of the heading/pitch/roll rotations is similar to the
coordinate system used for the airplane model: heading specifies a rotation
around the vertical (z) axis, pitch rotates around the horizontal lateral (y)
axis, and roll rotates around the longitudinal (x) axis.</p>
<p>Here's a simple example:</p>
<div class="fragment"><pre class="fragment">
<object filename="freqboard.ac" terrain="0">
<instance north="20.0" east="-160" height="0" h="90" p="0" r="0" />
</object>
</pre></div>
<p>This frequency board is located 20 feet north and 160 feet west of the
scene origin. It faces east (it is rotated 90 degrees around the vertical
axis). The board is excluded from height calculations. </p>
<h4>Collision boxes</h4>
<p>If you exclude complex models from being part of the terrain by setting
<tt>terrain="0"</tt>, the airplane can fly right through them.
The usual solution for this issue is to add a collision box to the scene.
A collision box is an object of very low complexity that is not rendered
(so it is not visible in the scenery). Instead it is only used for collision
detection and height calculation.</p>
<p>Although the term "collision box" is widely used for this kind
of object, their shape is not limited to boxes. In theory, arbitrary objects
can be loaded, but please bear in mind that the goal of using collision boxes
is to reduce the triangle count for collision detection, so using a box,
a pyramid or a similar low-poly shape is a good idea.</p>
<p>The objects can have arbitrary material properties, colours or textures.
CRRCsim will exclude them completely from the rendering stage, so the models
don't have to be transparent. But textures and materials will consume memory,
so the collision objects should be made from a single material without a
texture.</p>
<p>To add an object as a collision box, simply set the <tt>visible</tt>
attribute of an object to "0":</p>
<div class="fragment"><pre class="fragment">
<!-- A collision box for a static aircraft model -->
<object filename="aircraft_collbox.ac" visible="0">
<instance north="-70.0" east="60" height="0" h="45" />
</object>
</pre></div>
<h4>Embedded collision boxes</h4>
<p>Instead of adding two separate objects for the visible representation and
the collision box, you can combine both objects in a single 3D model file. To
tell CRRCsim which parts of the 3D model shall be visible and which parts belong
to the collision box, make use of the node naming feature of your 3D modelling
tool. CRRCsim will treat everything up to the first space character as the
part's real name, everything else is interpreted as an attribute. Each attribute
consists of a plus or minus sign followed directly by a keyword. The following
attributes are supported:</p>
<table border ="1">
<tr><th>Attribute</th>
<th>Effect</th></tr>
<tr><td>-visible</td><td>Exclude this part from rendering (make it invisible)</td></tr>
<tr><td>-terrain</td><td>Exclude this part from height-of-terrain calculations</td></tr>
</table>
<p>For example, in Blender, each part of a model is called an "object". You
can assign individual names to each object. Let's assume that you model a picnic
table to be placed in your scenery. Create a new object and call it "table -terrain"
(object panel, edit the datablock name field to read "OB:table -terrain").
Model your table. Then create a new object, call it "box -visible" and
model the collision box. Select table and box and export both to an AC3D model.
Then add this model to your scenery file in the usual way, but don't specify
any "terrain" or "visible" attributes in the XML file.
CRRCsim will automatically make the box invisible and ignore the table for
height calculations.</p>
<h2>9 End of file</h2>
<div class="fragment"><pre class="fragment">
</crrcsimSceneryFile>
</pre></div>
</body>
</html>
