fly/flightgear
1
0
Fork 0
Code Activity

From: John Check <j4strngs@bitless.net>

Browse source 
Subject: New panel doc
Date: Thu, 5 Oct 2000 19:44:02 -0500 (EST)

Hi Curt,
Here's the latest version panel doc. I'm also including the final
version joystick doc, the one in docs-mini is one behind.

I made some changes to my local sources to get a larger viewport
allowing for a shaped panel and still being able to see the runway
on takeoff. Should I send you the changes? David M is cool with it.

FWIW I've been playing with 3D renders for some textures and it's
looking pretty good. Theres a screenshot with the throttle and
mixture knobs done like that at http://rockfish.net/fg/

I'm going to post a tarball with what I have now to the above URL
but Dave is planning on making some changes to property manager over
the weekend and I figured I'd wait till I'm synched with any name changes
before making an official update.
This commit is contained in:
curt 2000-10-06 21:45:47 +00:00
parent f6fac40a11
commit ebb79b8c0c
2 changed files with 169 additions and 124 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

108
docs-mini/README.Joystick
View file

@ -1,5 +1,5 @@
Users Guide to Joystick Usage Under FlightGear Flight Simulator
version 0.2 9/23/2000
version 0.3 10/06/2000
Author John Check <j4strngs@rockfish.net>
This document is written with versions of FlightGear 0.7.5 and greater
@ -29,7 +29,8 @@ Among these was the ability to use a runtime configuration file (.fgfsrc)
to control the default operation. The .fgfsrc file is not created at runtime
and must be created manually. Fortunately, the format of the file is
straightforward. All one need do is place the commandline options one would
like in a plain ASCII text file in the users home directory.
like in a plain ASCII text file in the users home directory. System wide
defaults can be place in $FG_ROOT/system.fgfsrc.
With the advent of the property manager it became possible to add a number
of additional runtime options to the .fgfsrc file including joystick channel
@ -67,8 +68,10 @@ look like this: 0001. It should be noted that this is a hexadecimal (base16)
number +1. Hex numbers start at 0, so this number is incremented by one for
hopefully obvious reasons.
Default Joystick properties:
Axis 0 = Aileron
Axis 1 = Elevator
Axis 2 = Rudder
@ -82,51 +85,84 @@ Button 5 = Flaps (down)
Button 6 = Flaps (up)
In addition to the channel assignments there are other parameters
that can be passed to FGFS.
In addition to the channel assignments there are other properties
for tuning the joystick. These values work together in a particular order.
They should always be written as a 'float', or decimal number.
Axis properties
The full order of precedence for axis properties is
1. The raw axis value ...
2. is adjusted to dead-band, ...
3. then adjusted to offset, ...
4. then multiplied by factor, which ...
5. is assigned to the FlightGear control property.
Put another way....
cooked_value = (( raw_value > dead-band ) + offset) * factor
Axis properties:
dead-band
-1 0 1
.......................
-1 | | 1
^
dead-band
dead-band
This is an area where signals are ignored. It is used to compensate
for noise or potentiometers of dubious quality by creating a threshold
below which any signal is ignored. It it written as a decimal number or "float"
with a typical value of 0.1 for elevators and ailerons, 0.0 for throttle
below which any signal is ignored.
factor
The default of 0.1 for elevators and ailerons is very forgiving. A lower
number results in a tighter feel. Throttle defaults to 0.0
This number, also written as a float, will control sensitivity of an axis.
Negating the number will result in the control moving counter to the default.
A typical value is 1.0. In my case, throttle behaviour was inverted from what
I preferred. I set this value to -1.0 and everything was groovy.
offset
offset
-1 0 1
.......................
-1 ^ 1
offset
Also a float. Used to maximize a controls use of it's axis, as in the case of a
Used to maximize a controls use of it's axis, as in the case of a
throttle where zero would be a minimum and not a center point like in the case
of a rudder. Typical value -1.0.
factor
Controls sensitivity of an axis. If the factor is too low it results in
control not reaching its maximum possible limit. Negating the number will result in
the control moving counter to the default. The default value is 1.0, think unity gain.
In my case, throttle behaviour was inverted from what I preferred.
I set this value to -1.0 and everything was groovy.
Button properties
switch
switch
A button designated a switch is either on or off. While the button is
held in the switch is engaged. Brakes are described as a switch and take
additional parameters [ step, repeatable ]
adjust
adjust
A button designated adjust is for controls that have a range
of settings, for example elevator trim and flaps. These are found
in pairs having opposing values for the parameter 'step'.
The 'repeatable' parameter should be appropriate to the type of control.
step
step
This defines how much adjustment is applied when the button is activated
Default values are 1.0 for brakes (full on), 0.001 / -0.001 for
elevator trim and -0.34 / 0.34 for flaps
repeatable
repeatable
In this case repeatable means when the button is held down the value continues
to increment. repeatable is a true / false value. The default for brakes is
false. This is appropriate since by default brakes are a switch that are full
@ -203,42 +239,8 @@ In my case I had to make entries to put the throttle on axis2.
--prop:/input/js0/button6/step=0.34
--prop:/input/js0/button6/repeatable=false
Determining approriate values for axes:
FlightGear uses the PLIB library to handle the joystick input.
PLIB applies the values for deadband then hands the result over to FGFS,
where offset and factor are applied, the result is passed to the FG control
property.
It's important to understand how the dead-band, offset and factor properties
work together for axes in order to determine apropriate values.
The full order of precedence for axis properties is
1. The raw PLIB axis value ...
2. is adjusted to dead-band, then passed to FGFS, which ...
3. applies the offset, then the result...
4. is multiplied by factor, which ...
5. is assigned to the FlightGear control property.
Put another way....
PLIB lightly_toasted_value = ( raw_value > dead-band )
FGFS cooked_value = ( lightly_toasted_value + offset) * factor
Well, kind of. The dead-band value is applied +/- 0. Which is to say
when we assign it a value of 0.1 the effective value is -0.1 to 0.1
If the raw value is less than the dead-band then the raw_value is 0.
Here's a visual aid.
-1 0 1
.......................
-1 | | 1
^
deadband
This diagram represents a dead-band value of 0.1. Let's say we
have an el cheapo joystick with noisy pots. The noise level is +/-0.09.
With the raw signal our control would constantly be moving slightly.
A deadband value of 0.1 acts as a filter suppressing the noise.

185
docs-mini/README.xmlpanel
View file

@ -1,22 +1,21 @@
Users Guide to FlightGear panel configuration
First Draft
Version 0.3, October 5 2000
Author: John Check <j4strngs@rockfish.net>
This document is an attempt to describe the configuration via
XML of FlightGear flight simulator's aircraft panel display.
The information was culled from the fgfs-devel@flightgear.org
mailing list. I'd like to say thanks to all the developers who
make FGFS happen and forgive me for any errors with regards to
who did what. I'd like to reguest that anybody who should be
mentioned give me a heads up so I can credit them properly.
This document is an attempt to describe the configuration of
FlightGear flight simulator's aircraft panel display via XML.
The information was culled from the fgfs-devel@flightgear.org
mailing list and my experiences making alternate panels. I'd
like to say thanks to all the developers who make FGFS happen.
Corrections and additions are encouraged.
History:
Older versions of FGFS had a hardcoded display of instruments.
Some History:
Older versions of FGFS had a hard coded display of instruments.
This was a less than ideal state of affairs due to FGFS ability
to use different aircraft models. Being primarily developed on
UNIX type systems, a modular approach is taken towards the
aircraft modeling. To date, most alternatatives to the default
aircraft modeling. To date, most alternatives to the default
Cessna 172 aircraft are the product of research institutions
interested in the flight characteristics and not cosmetics.
The result of this was that one could fly the X-15 or a Boeing 747
@ -26,67 +25,111 @@ A rewrite of the panel display code was done around v0.7.5 by
developer David Megginson allowing for configuration of the panel
via XML to address this limitation.
The Basics:
David Megginson wrote:
Using Custom Panels:
> To get started, here's a basic, mostly-architectural outline:
>
> 1. All configuration files are XML-encoded property lists. The root
> element is always named <PropertyList>. None of the properties is
> mixed in with the main FlightGear properties (they're all separate
> lists).
>
> 2. There is a single, top-level configuration file for each panel.
> There is also a top-level configuration file for each instrument (I
> may also add configuration files for cropped textures, to enabled
> better reuse of common textures like needles and knobs).
>
> 3. A panel is composed of a background texture and zero or more
> instruments. The panel sets the position of each instrument and may
> also override the instrument's preferred size (the default panel does
> not do so, but if you want an altimeter covering a quarter of the
> screen, go for it!).
>
> 4. An instrument consists of a preferred width and height, one or more
> stacked layers, and zero or more actions. It is defined in a separate
> file.
>
> 5. A layer can be a texture (with alpha areas so that lower textures
> show through), text (static, generated, or both), or a switch between
> two other layers based on a boolean property. Each layer contains
> zero or more transformations.
>
> NOTE: There is one built-in layer -- for the mag compass ribbon --
> and all other layers are defined in the XML files. In the future,
> there may also be built-in layers for special things like a
> weather-radar display or a GPS (though the GPS could be handled with
> text properties).
>
> 6. A transformation is a rotation, an x-shift, or a y-shift.
> Transformations can be static (rotate 90 degrees) or they can be based
> on properties (rotate the number of degrees equal to the airspeed
> times something plus something else, etc.).
>
> 7. An action is a hotspot on an instrument where something will happen
> when the user clicks the left or centre mouse button. Actions are
> always tied to properties: they can toggle a boolean property, adjust
> the value of a numeric property, or swap the values of two properties.
>
> 8. You can find panel configuration files under $FG_ROOT/Panels/ and
> instrument configuration files under $FG_ROOT/Instruments/.
>
> 9. If there are *any* XML parsing errors, the panel will fail to load
> (them's the XML rules), so it's worth downloading a parser like Expat
> (http://www.jclark.com/xml/) so that you can check your XML.
> FlightGear will print the location of errors, but the messages are a
> little cryptic right now.
>
> 10. You can set the relative location of the top-level XML panel file
> (under $FG_ROOT) using the "/sim/panel" property. The default is
> $FG_ROOT/Panels/Default/default.xml.
The default panel location is $FG_ROOT/Panels/Default/default.xml.
$FG_ROOT is the place on your filesystem where you installed FG
data files. Alternate panels can be specified on the command line
or set as the default in the $HOME/.fgfsrc or $FG_ROOT/system.fgfsrc
using a property specification. The format is as follows:
--prop:/sim/panel/path=Panels/Default/default.xml
The path description shown is relative to $FG_ROOT. An absolute
path may also be used for locations outside $FG_ROOT. I would
recommend copying Panels/Default to Panels/Custom as a starting point
for experimentation. When editing a panel configuration, pressing
Shift +F3 will reload the panel. If your changes don't seem to be taking
effect, check the console output. It will report the success or failure
of the panel reload*. Editing textures requires restarting FGFS so the
new textures can be loaded.
Panel Architecture:
All of the panel configuration files are XML-encoded* property lists.
The root element of each file is always named <PropertyList>. Tags are
always found in pairs, with the closing tag having a slash prefixing
the tag name, i.e </PropertyList>. The top level panel configuration
file is composed of a <name>, a <background> texture and zero or more
<instruments>. Instruments are used by including a <"unique_name">, a
<path> to the instruments configuration file, <x> and <y> placement
coordinates, and optional <w> and <h> size specifications.
Comments are bracketed with <!-- -->.
Example Top Level Panel Config
<PropertyList>
<name>Example Panel</name>
<background>Panels/Default/Textures/panel-bg.rgb</background>
<instruments>
<clock> <!-- the "unique_name" -->
<path>Instruments/Default/clock.xml</path>
<x>110</x>
<y>320</y>
<w>72</w> <!-- optional width specification -->
<h>72</h> <!-- optional height specification -->
</clock>
</instruments>
</PropertyList>
The default location for instrument files is $FG_ROOT/Instruments/Default/.
Alternate locations may be specified in the panel configuration, paths
must be absolute to use files outside $FG_ROOT.
About Instrument Placement:
For the sake of simplicity the FGFS window is always considered to be 1024x768
so all x/y values for instrument placement should fall within these bounds.
Being an OpenGL program, 0,0 represents the lower left hand corner of the
screen. It is possible to place items to overlap the 3D viewport.
Instrument Architecture:
Instruments are defined in separate configuration files. An instrument
consists of a preferred width and height, one or more stacked layers,
and zero or more actions.
A layer** can be a <texture>, or be of <type> text or switch. A text layer
may be static, as in a label, or generated (if it needs to be dynamic, as
in an LED display), or a combination of both.
A switch layer is composed of two or more nested layers and will display
one of the nested layers based on a boolean property. For a simple example
of a switch see $FG_ROOT/Instruments/Default/brake.xml. Textures used in a
switch context *must* have width and height specified to be visible.
Each layer may contain zero or more transformations.
A transformation is a rotation, an x-shift, or a y-shift. Transformations
can be static or they can be based on properties. Static rotations are
useful for flipping textures horizontally or vertically. Transformations
based on properties are useful for driving instrument needles. I.E. rotate the
number of degrees equal to the airspeed. X and y shifts are relative to the
center of the instrument. Each specified transformation type takes an <offset>
An action is a hotspot on an instrument where something will happen
when the user clicks the left or center mouse button. Actions are
always tied to properties: they can toggle a boolean property, adjust
the value of a numeric property, or swap the values of two properties.
About Textures:
The texture files used to create the panel instruments are maximum 256x256
pixels, red/green/blue/alpha format. When calling a section of a texture file
the 0,0 lower left convention is used. There is a pair of x /y coordinates
defining which section of the texture to use.
* If there are *any* XML parsing errors, the panel will fail to load,
so it's worth downloading a parser like Expat (http://www.jclark.com/xml/)
for checking your XML. FlightGear will print the location of errors, but
the messages are a little cryptic right now.
** NOTE: There is one built-in layer -- for the mag compass ribbon --
and all other layers are defined in the XML files. In the future,
there may also be built-in layers for special things like a
weather-radar display or a GPS (though the GPS could be handled with
text properties).
To do:
Add some examples.
Integrate additonal questions and answers from the list.