From: John Check <j4strngs@bitless.net>

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.

docs-mini/README.Joystick

@@ -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
+In addition to the channel assignments there are other properties
-that can be passed to FGFS.
+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   
 
+
 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"
+below which any signal is ignored. 
-with a typical value of 0.1 for elevators and ailerons, 0.0 for throttle
 
-        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
 
-Also a float. Used to maximize a controls use of it's axis, as in the case of a
+-1  0                  1
+ .......................
+-1  ^                  1
+ offset
+
+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.
 

docs-mini/README.xmlpanel

@@ -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
+This document is an attempt to describe the configuration of 
-XML of FlightGear flight simulator's aircraft panel display.
+FlightGear flight simulator's aircraft panel display via XML. 
 The information was culled from the fgfs-devel@flightgear.org 
-mailing list. I'd like to say thanks to all the developers who 
+mailing list and my experiences making alternate panels. I'd 
-make FGFS happen and forgive me for any errors with regards to 
+like  to say thanks to all the developers who  make FGFS happen.
-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.
 Corrections and additions are encouraged.
 
-History:
+Some History:
-Older versions of FGFS had a hardcoded display of instruments.
+
+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:
+The default panel location is $FG_ROOT/Panels/Default/default.xml.
->
+$FG_ROOT is the place on your filesystem where you installed FG
-> 1. All configuration files are XML-encoded property lists.  The root
+data files. Alternate panels can be specified on the command line 
-> element is always named <PropertyList>.  None of the properties is
+or set as the default in the $HOME/.fgfsrc or $FG_ROOT/system.fgfsrc 
-> mixed in with the main FlightGear properties (they're all separate
+using a property specification. The format is as follows:
-> lists).
+
->
+--prop:/sim/panel/path=Panels/Default/default.xml
-> 2. There is a single, top-level configuration file for each panel.
+
-> There is also a top-level configuration file for each instrument (I
+The path description shown is relative to $FG_ROOT. An absolute
-> may also add configuration files for cropped textures, to enabled
+path may also be used for locations outside $FG_ROOT. I would 
-> better reuse of common textures like needles and knobs).
+recommend copying Panels/Default to Panels/Custom as a starting point
->
+for experimentation. When editing a panel configuration, pressing
-> 3. A panel is composed of a background texture and zero or more
+Shift +F3 will reload the panel. If your changes don't seem to be taking 
-> instruments.  The panel sets the position of each instrument and may
+effect, check the console output. It will report the success or failure
-> also override the instrument's preferred size (the default panel does
+of the panel reload*. Editing textures requires restarting FGFS so the
-> not do so, but if you want an altimeter covering a quarter of the
+new textures can be loaded.
-> screen, go for it!).
+
->
+
-> 4. An instrument consists of a preferred width and height, one or more
+Panel Architecture:
-> stacked layers, and zero or more actions.  It is defined in a separate
+
-> file.
+All of the panel configuration files are XML-encoded* property lists. 
->
+The root element of each file is always named <PropertyList>. Tags are
-> 5. A layer can be a texture (with alpha areas so that lower textures
+always found in pairs, with the closing tag having a slash prefixing
-> show through), text (static, generated, or both), or a switch between
+the tag name, i.e </PropertyList>. The top level panel configuration 
-> two other layers based on a boolean property.  Each layer contains
+file is composed of a <name>, a <background> texture and zero or more 
-> zero or more transformations.  
+<instruments>. Instruments are used by including a <"unique_name">, a
->
+<path> to the instruments configuration file, <x> and <y> placement
-> NOTE: There is one built-in layer -- for the mag compass ribbon --
+coordinates, and optional <w> and <h> size specifications.
-> and all other layers are defined in the XML files.  In the future,
+Comments are bracketed with <!-- -->.
-> 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
+    Example Top Level Panel Config
-> text properties).
+
->
+<PropertyList>
-> 6. A transformation is a rotation, an x-shift, or a y-shift.
+ <name>Example Panel</name>
-> Transformations can be static (rotate 90 degrees) or they can be based
+ <background>Panels/Default/Textures/panel-bg.rgb</background>
-> on properties (rotate the number of degrees equal to the airspeed
+ <instruments>
-> times something plus something else, etc.).
+  <clock>         <!-- the "unique_name" -->
->
+   <path>Instruments/Default/clock.xml</path>
-> 7. An action is a hotspot on an instrument where something will happen
+   <x>110</x>
-> when the user clicks the left or centre mouse button.  Actions are
+   <y>320</y>
-> always tied to properties: they can toggle a boolean property, adjust
+   <w>72</w>      <!-- optional width specification -->
-> the value of a numeric property, or swap the values of two properties.
+   <h>72</h>      <!-- optional height specification -->
->
+  </clock>
-> 8. You can find panel configuration files under $FG_ROOT/Panels/ and
+ </instruments>
-> instrument configuration files under $FG_ROOT/Instruments/.
+</PropertyList>
->
+  
-> 9. If there are *any* XML parsing errors, the panel will fail to load
+The default location for instrument files is $FG_ROOT/Instruments/Default/.
-> (them's the XML rules), so it's worth downloading a parser like Expat
+Alternate locations may be specified in the panel configuration, paths
-> (http://www.jclark.com/xml/) so that you can check your XML.
+must be absolute to use files outside $FG_ROOT.
-> FlightGear will print the location of errors, but the messages are a
+
-> little cryptic right now.
+About Instrument Placement:
->
+
-> 10. You can set the relative location of the top-level XML panel file
+For the sake of simplicity the FGFS window is always considered to be 1024x768
-> (under $FG_ROOT) using the "/sim/panel" property.  The default is
+so all x/y values for instrument placement should fall within these bounds.
-> $FG_ROOT/Panels/Default/default.xml.
+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.