FGFS-4.1/flightgear
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
Your Name
2022-10-20 20:29:11 +08:00
commit 4d531f8044
3238 changed files with 1387862 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

329
docs-mini/AptNavFAQ.FlightGear.html Normal file
View File

@@ -0,0 +1,329 @@
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-1252">
<META NAME="Generator" CONTENT="Microsoft Word 97">
<TITLE>Airport, navigation aid and intersection data in X-Plane (version 5</TITLE>
</HEAD>
<BODY LINK="#0000ff" VLINK="#800080">
<B><U><FONT FACE="Arial"><P ALIGN="CENTER">Airport, navigation aid and IFR intersection data in FlightGear </P>
</B></U></FONT><FONT>
<P>&nbsp;</P>
<P>By Robin Peel, June 17<SUP>th</SUP>, 2001</P>
<P>robin@cpwd.com</P>
<P>Version FG1.4</P>
<P>&nbsp;</P>
<P></FONT><A HREF="#_Toc493997498"><FONT>Purpose of this FAQ&#9;</FONT><A HREF="#_Toc493997498">*</A></A>
<FONT><P></FONT><A HREF="#_Toc493997499"><FONT>Who am I &amp; what do I do?&#9;</FONT><A HREF="#_Toc493997499">*</A></A></P>
<FONT><P></FONT><A HREF="#_Toc493997500"><FONT>What is the &quot;master database&quot;?&#9;</FONT><A HREF="#_Toc493997500">*</A></A></P>
<FONT><P></FONT><A HREF="#_Toc493997501"><FONT>How is the data created, updated and generated for FlightGear?&#9;</FONT><A HREF="#_Toc493997501">*</A></A></P>
<FONT><P></FONT><A HREF="#_Toc493997502"><FONT>How complete is the data?&#9;</FONT><A HREF="#_Toc493997502">*</A></A></P>
<FONT><P></FONT><A HREF="#_Toc493997503"><FONT>How can I correct errors or omissions I find in the data?&#9;</FONT><A HREF="#_Toc493997503">*</A></A></P>
<FONT><P></FONT><A HREF="#_Toc493997504"><FONT>Where is the data stored in FlightGear and what data does each file contain?&#9;</FONT><A HREF="#_Toc493997504">*</A></A></P>
<FONT><P></FONT><A HREF="#_Toc493997505"><FONT>General structure of default.apt, default.nav, default.ils and default.fix files&#9;</FONT><A HREF="#_Toc493997505">*</A></A></P>
<FONT><P></FONT><A HREF="#_Toc493997506"><FONT>Details <20> what do the entries in default.apt mean?&#9;</FONT><A HREF="#_Toc493997506">*</A></A></P>
<FONT><P></FONT><A HREF="#_Toc493997507"><FONT>Details <20> what do the entries in default.nav mean?&#9;</FONT><A HREF="#_Toc493997507">*</A></A></P>
<FONT><P></FONT><A HREF="#_Toc493997508"><FONT>Details <20> what do the entries in default.ils mean?&#9;</FONT><A HREF="#_Toc493997508">*</A></A></P>
<FONT><P></FONT><A HREF="#_Toc493997509"><FONT>Details <20> what do the entries in fix.dat mean?&#9;</FONT><A HREF="#_Toc493997509">*</A></A></P>
<FONT><P></FONT><A HREF="#_Toc493997510"><FONT>Where are the localiser and glideslope aerials positioned in the &quot;real world&quot;?&#9;</FONT><A HREF="#_Toc493997510">*</A></A></P>
<FONT><P></FONT><A HREF="#_Toc493997511"><FONT>How do I convert my data to decimal degrees?&#9;</FONT><A HREF="#_Toc493997511">*</A></A></P>
<FONT></P>
</FONT><B><U><FONT FACE="Arial"><P><A NAME="_Toc493997498">Purpose of this FAQ</A></P>
</B></U></FONT><FONT><P>This FAQ describes the contents and structure of the files that store airport, nav-aid (NDB, VOR, DME and ILS) and IFR intersection data within the Flight Gear flight simulator. </P>
</FONT><B><U><FONT FACE="Arial"><P><A NAME="_Toc493997499">Who am I &amp; what do I do?</A></P>
</B></U></FONT><FONT><P>Sometime in 1997, I volunteered to Austin Meyer (the owner/developer of the X-Plane simulator) to try and improve upon the very basic airport data included in X-Plane version 3.x. I built an application in Microsoft Access 97 (now converted to Access 2000) to store and manipulate the airport, nav-aid and intersection data. I have worked with Austin to add additional airport and nav-aid details to X-Plane (such as custom taxiways, airports outside the boundaries of the USA, more accurate runway markings, etc) and during this time the master database has grown to over 20MB in size. This database is also now used to generate data for the FlightGear simulator, using data files that are different in format (and more sophisticated) than the X-Plane data files.</P>
<P>I perform this task as a volunteer. The data is published as a free resource to the X-Plane and FlightGear communities.</P>
<P>At present, I have around 450hrs of &quot;real&quot; flying experience, gained since 1989. I have a UK Private Pilot<6F>s Licence (gained at White Waltham, EGLM), a US Private Certificate and a US Instrument Rating. I currently fly a rented new C-172 SP out of Albuquerque Double Eagle II (KAEG), or more elderly knackered C-172s out of Santa Fe (KSAF). I have just ordered a new Liberty XL-2 from Liberty Aerospace in Montrose, Colorado (www.libertyaircraft.com).</P>
</FONT><B><U><FONT FACE="Arial"><P><A NAME="_Toc493997500">What is the &quot;master database&quot;?</A></P>
</B></U></FONT><FONT><P>The master database is my Microsoft Access 2000 database that stores all the airport, nav-aid and intersection data. In database parlance, it is highly &quot;normalized&quot; and consists of over 35 Access tables accessed from a custom-designed Access 2000 application. The master database currently contains over 22,000 airports. I may &quot;upsize&quot; the database back-end to Microsoft SQLServer (7.0) in the very near future.</P>
</FONT><B><U><FONT FACE="Arial"><P><A NAME="_Toc493997501">How is the data created, updated and generated for FlightGear?</A></P>
</B></U></FONT><FONT><P>I regularly import updates and amendments to the master database using routines that will automatically read fragments of new data sent to me by other users, and save the new data into my Access tables. Similarly, I have routines that will generate the data required by FlightGear and X-Plane in the necessary form</P>
</FONT><B><U><FONT FACE="Arial"><P><A NAME="_Toc493997502">How complete is the data?</A></P>
</B></U></FONT><FONT><P>The data is pretty complete for the USA (based upon FAA data sources). Quality data for other countries is harder to obtain, but dedicated FlightGear and/or X-Plane users have sent me data for much of Canada, Western Europe (with some gaps), Japan and Australia. Some other random major airports also exist (eg. in Central and South America).</P>
</FONT><B><U><FONT FACE="Arial"><P><A NAME="_Toc493997503">How can I correct errors or omissions I find in the data?</A></P>
</B></U></FONT><FONT><P>First, you need to find a good source of information. An official chart of the airport (such as those published by Jeppesen) is a good starting point <20> they often have a helpful latitude/longitude scale around the edges that you can use to figure out the exact positions of runways and taxiways. Remember that these scales appear to be backwards for western longitudes and southern latitudes!</P>
<P>Then you need to get the data into the appropriate files (see below for file names and formats.</P>
<P>Finally, send errors, corrections and additions to me (robin@cpwd.com). The easiest way to send new or corrected data is to copy just the appropriate lines from your default.apt, default.nav, default.ils and/or default.fix files into a plain text file, and attach the text file to an e-mail. All of these files are just plain text files, and can be edited with any text editor (or a word processor operating in &quot;text-only&quot; mode). Note that in Windows, the Notepad editor sometimes balks at the size of these files (it seems to be a problem in Windows 95/98, but not in Windows 2000). </P>
<P>Please do <U>not</U> send me:</P>
<UL>
<LI>Your entire file (with your corrections embedded somewhere in its midst) <20> these are impossible for me to sort through!</LI>
<LI>Scanned copies of charts in the hope that I will spend several hours trying to plot the positions of runways and taxiways for you. Unless I have a personal interest in the particular airport, this takes just too much of my time. Sorry!</LI></UL>
</FONT><B><U><FONT FACE="Arial"><P><A NAME="_Toc493997504">Where is the data stored in FlightGear and what data does each file contain?</A></P>
</B></U></FONT><FONT><P>The following files contain airport, nav-aid and intersection data in FlightGear. They may be stored in the Airports and Navaid folders of your FlightGear installation as .gz archives:</P>
<DIR>
<DIR>
<DIR>
<DIR>
<B><P>default.apt</B> &#9;Airports, with their runways and taxiways (taxiways are not available yet <20> they will be added very soon).</P>
<B><P>default.nav</B> &#9;NDBs, VORs and DMEs.</P>
<B><P>default.ils</B>&#9;ILS elements.</P>
<B><P>default.fix</B> &#9;IFR intersections (often referred to as &quot;fixes&quot;).</P>
</DIR>
</DIR>
</DIR>
</DIR>
<P>When un-archived, they are all plain text files that can be viewed or edited with any text editor (such as Notepad on a Windows PC). </P>
</FONT><B><U><FONT FACE="Arial"><P><A NAME="_Toc493997505">General structure of default.apt, default.nav, default.ils and default.fix files</A></P>
</B></U></FONT><FONT><P>Features common to each file are:</P>
<UL>
<LI>Each data &quot;element&quot; occupies a single line of the file.</LI>
<LI>Any comments are preceded with a double slash (&quot;//&quot;). Typically, the first line of each file is a comment that includes a data version number and other descriptive information. Other comments may be added as required within the file.</LI>
<LI>The last line of a file is marked with &quot;[End]&quot;.</LI>
<LI>The first character of each line describes the type of data that the line contains (eg. &quot;A&quot; for airport data, &quot;R&quot; for runway data.</LI>
<LI>The order in which data is stored in the files is conceptually unimportant. BUT, airport data must be ordered so that the airport header data (prefixed by &quot;A&quot;) is followed by its runway and taxiway data (prefixed by &quot;R&quot; or &quot;T&quot;).</LI></UL>
<B><U><P>IMPORTANT</B></U>: <U>All</U> headings referenced in the files are <B><U>true</B></U> (<U>not</U> magnetic). FlightGear has an internal model of magnetic variation that will be used to properly align VORs, etc.</P>
<P>The meanings of these line &quot;prefix&quot; codes in default.apt are:</P>
<P>A &#9;Airport header data</P>
<P>R &#9;Runway at an airport</P>
<P>T&#9;Taxiway at an airport</P>
<P>The meanings of these line codes in default.nav are:</P>
<P>D&#9;DME</P>
<P>N &#9;NDB, including NDB element of LOMs (Locator Outer Markers or <20>Compass Locators<72>)</P>
<P>V &#9;VOR</P>
<P>The meanings of these line codes in default.ils are:</P>
<P>L&#9;Localiser-only</P>
<P>I&#9;ILS and LOC/DME</P>
<P>S&#9;SDF (Simplified Directional Facility)</P>
<P>D&#9;LDA (Localiser Directional Aid)</P>
<P>M&#9;MLS (Microwave Landing System)</P>
<P>Since the default.fix file contains only IFR intersections, no &quot;prefix&quot; codes are used to differentiate the data</P>
<P>Individual data elements on each line can be separated by any number of spaces or other <20>white space<63> <20> however, it is a good plan to keep them aligned in tidy columns (this is harder in default.apt, with its mixture of line types) <20> it is easier to spot silly errors and/or omissions in this way. </P>
</FONT><B><U><FONT FACE="Arial"><P><A NAME="_Toc493997506">Details <20> what do the entries in default.apt mean?</A></P>
</B></U></FONT><FONT><P>Each airport has a header line (code &quot;A&quot;) and one or more runway/taxiway lines (code &quot;R&quot; or &quot;T&quot;). The runways for each airport MUST follow the airport header line. Taxiways should follow the runways. A blank line can be used to separate different airports <20> this helps improve readability but is not required. </P>
<DIR>
<I><P>[If you do not understand the concepts referenced by these codes, please refer to the AIM (Airman<61>s Information Manual), or the equivalent publication for your jurisdiction These documents often contain a wealth of information, diagrams and explanations.]</P>
</I></DIR>
<P>Here is a simplified fragment for part of an airport in default.apt: </P>
</FONT><FONT FACE="Courier New"><P>A KABQ 35.040361 -106.609306 5352 CYN Albuquerque International Sunport</P>
<P>R 08 35.044209 -106.598560 090.43 13775 150 NCPHN YNVQ 991 0 NYVN 0 0 </P>
<P>R 03 35.032077 -106.618983 044.67 10000 150 NCPHN YNPO 0 0 NNPN 0 0 </P>
<P>R 12 35.039105 -106.614064 128.98 5142 150 NAVMN NNNN 0 0 NYPN 0 0 </P>
<P>R 17 35.044022 -106.611983 183.36 10000 150 NAVMN NYVN 890 0 NYVN 0 0</P>
<P>T A 35.044209 -106.588560 090.43 13775 100 GCB</P>
</FONT><FONT><P>&nbsp;</P>
<P>This shows one airport header line, four runways and a taxiway. The order of the data on the airport header line is (using the above example):</P>
<P>A &#9;&#9;This is an airport header line</P>
<P>KABQ &#9;&#9;ICAO code for the airport. All airports <U>must</U> have a <U>unique</U> ICAO code.</P>
<P>35.040361&#9;Airport Reference Point (ARP) latitude</P>
<P>-106.609306 &#9;Airport Reference Point (ARP) longitude</P>
<P>5352 &#9;&#9;Airport elevation in feet (above MSL).</P>
<P>C &#9;&#9;Airport usage (C=Civilian, M=Military) <20> determines airport beacon colours.</P>
<P>Y &#9;&#9;Control Tower (Y=Yes, N=No)</P>
<P>N &#9;&#9;Show default airport buildings (Y=Yes, N=No)</P>
<P>&quot;Albuquerque International Sunport&quot; &#9;Airport name - no limit to length.</P>
<P>The data on the runway lines is a little more complex. Using the first runway in the above example data:</P>
<P>R &#9;&#9;This is a data line for a runway.</P>
<P>35.044209 &#9;Latitude (in decimal degrees) of runway center.</P>
<P>-106.598560&#9;Longitude (in decimal degrees) of runway center.</P>
<P>08 &#9;&#9;Runway number (eg. &quot;08&quot; or &quot;27L&quot;) </P>
<P>90.43&#9;&#9;<B>True</B> (<U>not</U> magnetic) heading of the runway in degrees.</P>
<P>13775&#9;&#9;Runway length in feet.</P>
<P>150&#9;&#9;Runway width in feet.</P>
<P>The next data chunk describe data common to both ends of the runway:</P>
<P>N &#9;Runway centre-line lights (Y=Yes, N=No)</P>
<P>C &#9;Runway surface (A=Asphalt, C=Concrete, T=Turf, D=Dirt, G=Gravel, W=Water, X=Other)</P>
<P>P &#9;Runway markings (V=Visual, P=Precision, R=Non-Precision, B=Buoys - water)</P>
<P>H &#9;Edge Lights (N=None, H=High intensity, M=Medium, L=Low, B=Blue taxiway)</P>
<P>N &#9;Runway guard lights (Y=Yes, N=No) <20> the flashing orange &quot;wig-wags&quot; that protect runway entrances.</P>
<P>The next two data chunks describe data for each end of the runway, starting with the end defined by the runway number (08 in our example data):</P>
<P>Y &#9;Touchdown zone lights (Y=Yes, N=No)</P>
<P>N &#9;REIL (Y=Yes, N=No)</P>
<P>P&#9;Visual glide scope indicator (N=None, V=VASI, P=PAPI). [<I>I may make the codes more detailed soon</I>]</P>
<P>Q&#9;Approach lighting (<I>see code lists below</I>)</P>
<P>991&#9;Length of displaced threshold in feet</P>
<P>0 &#9;Length of stopway in feet</P>
<P>This data chunk format is then repeated for the other end of the runway (runway 26 in our example).</P>
<I><P>&nbsp;</P><DIR>
<P>Approach lighting codes:</P>
</I><P>A&#9;ALS &#9;Approach light system (assumed white lights)</P>
<P>B&#9;ALSF-I &#9;Approach light system with sequenced flashing lights</P>
<P>C&#9;ALSF-II &#9;Approach light system with sequenced flashing lights and red side bar lights the last 1000'</P>
<P>D&#9;CAL &#9;Calvert (British)</P>
<P>E&#9;CAL-II &#9;Calvert (British) - Cat II and II</P>
<P>F&#9;LDIN &#9;Sequenced flashing lead-in lights</P>
<P>G&#9;MALS &#9;Medium intensity approach light system</P>
<P>N&#9;None&#9;No approach lighting</P>
<P>H&#9;MALSF &#9;Medium intensity approach light system with sequenced flashing lights</P>
<P>I&#9;NSTD &#9;Non standard</P>
<P>J&#9;MALSR &#9;Medium intensity approach light system with runway alignment indicator lights</P>
<P>K&#9;MIL OVRN &#9;Something military</P>
<P>L&#9;ODALS &#9;Omni-directional approach light system</P>
<P>M&#9;RAIL &#9;Runway alignment indicator lights (icw other systems)</P>
<P>O&#9;SALS &#9;Short approach light system</P>
<P>P&#9;SALSF &#9;Short approach light system with sequenced flashing lights</P>
<P>Q&#9;SSALF &#9;Simplified short approach light system with sequenced flashing lights</P>
<P>R&#9;SSALR &#9;Simplified short approach light system with runway alignment indicator lights</P>
<P>S&#9;SSALS &#9;Simplified short approach light system</P>
</DIR>
<P>This data is then repeated (with appropriate values) for the opposite end of this runway (KABQ runway 26 in our example data).</P>
<P>Taxiway data is similar in structure to the runway data:</P>
<P>T &#9;&#9;This is a data line for a taxiway segement.</P>
<P>A&#9;&#9;Taxiway identifier, that may be repeated for multiple taxiway segments. Default is &quot;-&quot;.</P>
<P>35.044209 &#9;Latitude (in decimal degrees) of taxiway center.</P>
<P>-106.598560&#9;Longitude (in decimal degrees) of taxiway center.</P>
<P>90.43&#9;&#9;<B>True</B> (<U>not</U> magnetic) heading of the taxiway segement in degrees.</P>
<P>13775&#9;&#9;Taxiway segment length in feet.</P>
<P>150&#9;&#9;Taxiway segment width in feet.</P>
<P>N &#9;Taxiway segment centre-line lights (Y=Yes, N=No) <20> taxiway center-line lights are </FONT><B><FONT COLOR="#008000">green</B></FONT><FONT>.</P>
<P>C &#9;Taxiway segment surface (A=Asphalt, C=Concrete, T=Turf, D=Dirt, G=Gravel, W=Water, X=Other)</P>
<P>B &#9;Edge Lights (N=None, B=Blue taxiway, R=Red edge lights)</P>
</FONT><B><FONT COLOR="#ff0000"><P>[TAXIWAY DEFINITION IS STILL SUBJECT TO CHANGE]</P>
</FONT><U><FONT FACE="Arial"><P><A NAME="_Toc493997507">Details <20> what do the entries in default.nav mean?</A></P>
</B></U></FONT><FONT><P>Each nav-aid is on a separate line, usually sorted by the nav-aid name within each nav-aid type.</P>
<P>Here are some example lines, showing selected nav-aids in the Albuquerque area:</P>
</FONT><FONT FACE="Courier New"><P>V 35.043796 -106.816312 5740 113.20 130 Y ABQ XXX Albuquerque VORTAC</P>
<P>N 34.987022 -106.620384 5304 247.00 50 N ILT XXX Isleta NDB</P>
<P>D 51.346667 -000.563889 104 109.85 50 Y FRK 05W Fairoaks DME</P>
</FONT><FONT><P>The meaning of this data for the first row (ABQ VORTAC) is:</P>
<P>V&#9;&#9;Navaid type (D=DME, N=NDB and V=VOR).</P>
<P>35.043796&#9;Latitude of nav-aid in decimal degrees.</P>
<P>-106.620384&#9;Longitde of nav-aid in decimal degrees.</P>
<P>5740 &#9;&#9;Elevation (in feet) of nav-aid.</P>
<P>113.20 &#9;&#9;Frequency.</P>
<P>130 &#9;&#9;Range of nav-aid (in nautical miles).</P>
<P>Y &#9;&#9;Co-located DME (Y=Yes, N=No).</P>
<P>ABQ&#9;&#9;Nav-aid identifier (note <20> these are not unique).</P>
<P>XXX&#9;&#9;Magnetic variation, if known, in format 13E for 13 degrees east.</P>
<P>&quot;Albuquerque VORTAC&quot;&#9;Nav-aid name.</P>
</FONT><B><U><FONT FACE="Arial"><P><A NAME="_Toc493997508">Details <20> what do the entries in default.ils mean?</A></P>
</B></U></FONT><FONT><P>Each ILS installation is on a separate line. Here are some example lines, showing the ILS 08 for KABQ (Albuquerque, New Mexico). These lines are long <20> so they are wrapped onto multiple lines here (but are on a single long line in default.ils):</P>
</FONT><FONT FACE="Courier New"><P>I ILS KABQ 08 111.90 ISPT 090.43 35.044026 -106.570548 </P>
<P>5352 3.00 35.043212 -106.614641 35.044750 -106.570577 </P>
<P>35.046352 -106.742583 35.044686 -106.628247 00.000000 000.000000</P>
</FONT><FONT>
<P>This is not as bad as it looks! The meaning of this data is:</P>
<P>I&#9;ILS type (see code list below).</P>
<P>ILS&#9;ILS type description (used to aid file navigation). Other values are as in the list of ILS type codes below.</P>
<P>KABQ&#9;ICAO airport code for the runway this ILS serves.</P>
<P>08 &#9;Runway number that this ILS serves.</P>
<P>111.90&#9;ILS frequency (usually the localiser frequency).</P>
<P>ISPT&#9;ILS identifier.</P>
<P>090.43 &#9;<U>True</U> heading of the localiser.</P>
<P>35.044026&#9;Latitude of the localiser aerial.</P>
<P>-106.570548 &#9;Longitude of the localiser aerial.</P>
<P>5352 &#9;&#9;Elevation (in feet) of the glideslope aerial.</P>
<P>3.00 &#9;&#9;Gradient of the glideslope (typically 3.00 degrees).</P>
<P>35.043212&#9;Latitude of the glideslope aerial.</P>
<P>-106.614641 &#9;Longitude of the glideslope aerial.</P>
<P>35.044750 &#9;Latitude of the associated DME aerial.</P>
<P>-106.570577 &#9;Longitude of the associated DME aerial.</P>
<P>35.046352&#9;Latitude of the Outer Marker (OM).</P>
<P>-106.742583&#9;Longitude of the Outer Marker (OM).</P>
<P>35.044686&#9;Latitude of the Middle Marker (MM).</P>
<P>-106.628247 &#9;Longitude of the Middle Marker (MM).</P>
<P>00.000000 &#9;Latitude of the Inner Marker (IM).</P>
<P>000.000000&#9;Longitude of the Inner Marker (IM).</P>
<DIR>
<I><P>ILS type codes used above:</P>
</I><P>L&#9;Localiser-only</P>
<P>I&#9;ILS and LOC/DME</P>
<P>S&#9;SDF (Simplified Directional Facility)</P>
<P>D&#9;LDA (Localiser Directional Aid)</P>
<P>M&#9;MLS (Microwave Landing System)</P>
<DIR>
<U><P>Notes</U>&#9;</P></DIR>
</DIR>
<UL>
<LI>If an ILS component does not exist, its latitude/longitude will be set to zero (eg. the Inner Marker in the above example).</LI>
<LI>For a Locator Outer Marker (LOM), which is an NDB co-located with an OM, the NDB must be added to default.nav as a separate, stand-alone NDB (at the same location!). </LI></UL>
</FONT><B><U><FONT FACE="Arial"><P><A NAME="_Toc493997509">Details <20> what do the entries in fix.dat mean?</A></P>
</B></U></FONT><FONT><P>This is the easiest file to interpret! Each intersection is on a separate line. Here is an example line:</P>
</FONT><FONT FACE="Courier New"><P>WOBIN 35.162472 -106.646500 </P>
</FONT><FONT>
<P>The meaning of this data is:</P>
<P>WOBIN&#9;&#9;Intersection name (always five characters and must be unique).</P>
<P>35.162472&#9;Latitude in decimal degrees.</P>
<P>-106.646500&#9;Longitude in decimal degrees</P>
</FONT><B><U><FONT FACE="Arial"><P><A NAME="_Toc493997510">Where are the localiser and glideslope aerials positioned in the &quot;real world&quot;?</A></P>
</B></U></FONT><FONT><P>Flight simulator pilots often get confused about where the aerials that form the components of an ILS are positioned in relation to the runway. Here is a simple example for a fictitious ILS for runway 09.</P>
<P>The localiser aerial (which provides left-right guidance to the pilot) is usually positioned just beyond (500 <20> 1000 feet) the <B><U>far</B></U> end of the runway it serves (ie. beyond the eastern end of our example runway). The localiser<65>s beam points back down the runway (westward in our example) towards an approaching plane <20> the center of the beam passes through the runway<61>s touch down zone. You can see the localiser aerial at your nearest major airport <20> the aerial is a wide, flat thing, usually painted red, and hidden amongst the forest of approach lighting for the opposite runway (runway 27 in our example). It is usually the first valuable thing destroyed by an aeroplane that over-runs the end of a runway <20> or by an aeroplane the approaches the opposite end of the runway a little low. </P>
<P>Some localisers exist in isolation from other components of an ILS. These form part of Localiser (LOC), Localiser Directional Aid (LDA) or Simplified Directional Facility (SDF) approaches. Such aerials can be positioned wherever is most useful <20> an extreme example is the LOC on top of a mountain near Aspen, Colorado (KASE) that is used to provide guidance for departures, not arrivals! Washington National (KDCA) runway 18 is served by a localiser positioned on the opposite side of the Potomac River in Maryland <20> it points to the north-west along the Potomac to provide guidance to aeroplanes following the river towards KDCA runway 18 <20> this approach heading is significantly offset from the runway heading..</P>
<P>The glideslope (GS) aerial (which provides up-down guidance to the pilot) is usually positioned just to one side of the runway<61>s touch down zone (TDZ), which is about 1,000<30> along the runway from the threshold. Typically, a GS aerial might be 200 <20> 300 feet to the left (north in our example for runway 09) of the TDZ. Again, you can see this vertical aerial at your local airport <20> it often has a small shack close by housing the electrical gear. The shack is often painted in lurid red/white or orange <20> presumably in an attempt to stop errant from aeroplanes flying (or taxying) into it. The beam from the glideslope is typically angled up from the TDZ at 3 degrees, though this may vary. Steeper angles may not sound significant (say 5 degrees) but they are surprisingly disconcerting to nervous passengers.</P>
<P>The marker beacons (which provide information to a pilot about the distance from the runway) are placed on the ground at certain distances from the runway<61>s threshold. The Inner Marker (IM) is usually very close to (or at) the runway threshold. The Middle Marker (MM) is typically 3,500<30> out from the threshold (to the west in our example) and usually indicates a point at which an approaching aeroplane on the glideslope should be 200<30> above the TDZ elevation. The Outer Marker (OM) varies in location, but is usually 4 <20> 7 nautical miles for the runway. Not all ILS approaches have the full complement of marker beacons <20> inner markers are relatively rare.</P>
<P>Here is a summary for an ILS for our example runway 09:</P>
</FONT><FONT FACE="Courier New">
<P>OM MM IM #</P>
<P>() () ()09==========================27 @ </P>
<P>Where:</P>
<P># - Glideslope aerial</P>
<P>@ - Localiser aerial</P>
<P>= - Runway 09/27</P>
<P>() - Marker beacons</P>
</FONT><B><U><FONT FACE="Arial"><P><A NAME="_Toc493997511">How do I convert my data to decimal degrees?</A></P>
</B></U></FONT><FONT><P>The FlightGear data files define all positions as &quot;decimal degrees&quot; to six decimal places (eg. <20>123.456789). This makes mathematical calculations faster. </P>
<P>But remember from your basic school geometry that a degree is <I>traditionally</I> subdivided into 60 minutes, and that a minute can be further subdivided in 60 seconds. Some aviation data sources choose not to use the &quot;seconds&quot; <20> instead they use decimal parts of a minute. Other sources use data defined in degrees and the decimal part of degrees, just as in FlightGear. Here are some example data formats (all refer to the same position):</P>
</FONT><FONT FACE="Courier New">
<P>N35.5000 W106.5000 (Decimal degrees, or dd.dddd)</P>
<P>35 30.00N 106 30.00W (Decimal minutes, or dd mm.mm)</P>
<P>35 30 00N 106 30 00W (Degrees, minutes and seconds, or dd mm ss)</P>
</FONT><FONT>
<P>A common convention is that that western longitudes and southern latitudes are negative numbers when converted to decimal degrees. So data for the USA will have positive latitudes and negative longitudes (see all the example data quoted above).</P>
<P>So, to convert a dd mm.mm format (eg. 35 30.00N) to decimal degrees), you need to:</P>
<UL>
<LI>Divide the minutes by 60 (in our example: 30.00/60 = 0.5).</LI>
<LI>Add this result to the degrees (in our example: 35 + 0.5 = 35.5).</LI>
<LI>Check the sign <20> south or west is negative (in our example, north is positive).</LI>
<LI>And so the converted answer is: 35.50.How do I calculate the position of somewhere in relation to somewhere else?</LI></UL>
<P>[From JJ Brennan] For those who don't like to do the math, there is a very useful little program called LLCALC that will do latitude/longitude calculations. It's also very useful if you wish to locate a point in some relation to another point (like placing an ILS GS transmitter alongside a runway, or finding the end points of a runway from its center point).</P>
<P>A copy can be found at:</P>
<P>ftp://ftp.kingmont.com/pub/kingmont/x-plane/llcalc.zip</P>
<P>&nbsp;</P>
<P>[End]</P></FONT></BODY>
</HTML>

884
docs-mini/FlightGear-FAQ.html Normal file
View File

@@ -0,0 +1,884 @@
<html lang="en">
<!-- $Id$ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>FlightGear FAQ</title>
<style type="text/css">
.indent { margin-left: 2em; margin-right: 1em; }
</style>
</head>
<body>
<h1 align="center">FlightGear FAQ</h1>
<hr noshade>
<h2>Introduction</h2>
<p>Welcome to the FlightGear FAQ. Here you will find the answers to
some questions that are frequently asked on our mailing lists. If
you have a question that is not answered here, feel free to ask
us on our mailing lists. Enjoy</p>
<hr noshade>
<h2>
<a name="toc">Table of Contents</a>
</h2>
<h4>1 -
<a href="#1">The FAQ</a>
</h4>
<div class="indent">1.1 -
<a href="#1.1">Where can I get the latest version of this FAQ?</a>
</div>
<div class="indent">1.2 -
<a href="#1.2">Who do I contact if I have comments about this FAQ?</a>
</div>
<div class="indent">1.3 -
<a href="#1.3">How old is this document?</a>
</div>
<div class="indent">1.4 -
<a href="#1.4">What other important documentation should I read?</a>
</div>
<br>
<h4>2 -
<a href="#2">Distribution</a>
</h4>
<div class="indent">2.1 -
<a href="#2.1">Where can I get FlightGear?</a>
</div>
<div class="indent">2.2 -
<a href="#2.2">What is the password for the FTP server?</a>
</div>
<div class="indent">2.3 -
<a href="#2.3">Why won't the FTP server let me in with the right login info?</a>
</div>
<div class="indent">2.4 -
<a href="#2.4">Where can I find the latest development source code?</a>
</div>
<div class="indent">2.5 -
<a href="#2.5">What is SimGear, and why do I need it?</a>
</div>
<div class="indent">2.6 -
<a href="#2.6">Where can I fly and where do I get the scenery?</a>
</div>
<div class="indent">2.7 -
<a href="#2.7">Where can I get different 3D models for my plane?</a>
</div>
<div class="indent">2.8 -
<a href="#2.8">How current is the data in FlightGear compared to the real world?</a>
</div>
<div class="indent">2.9 -
<a href="#2.9">Where is the moving map?</a>
</div>
<div class="indent">2.10 -
<a href="#2.10">Why don't you charge money for this?</a>
</div>
<br>
<h4>3 -
<a href="#3">Compiling</a>
</h4>
<div class="indent">3.1 -
<a href="#3.1">Why won't FlightGear compile?</a>
</div>
<div class="indent">3.2 -
<a href="#3.2">I'm using RedHat 7, and ...?</a>
</div>
<br>
<h4>4 -
<a href="#4">Configuring</a>
</h4>
<div class="indent">4.1 -
<a href="#4.1">How do I install new scenery?</a>
</div>
<div class="indent">4.2 -
<a href="#4.2">How do I setup my joystick(s)?</a>
</div>
<div class="indent">4.3 -
<a href="#4.3">What format should my personal .fgfsrc file be in?</a>
</div>
<br>
<h4>5 -
<a href="#5">Running</a>
</h4>
<div class="indent">5.1 -
<a href="#5.1">Why do I get an error loading libopenal.so.0?</a>
</div>
<div class="indent">5.2 -
<a href="#5.2">Why do I get "ssgInit called without a valid OpenGL context"?</a>
</div>
<div class="indent">5.3 -
<a href="#5.3">What happened to the panel, keyboard, etc?</a>
</div>
<div class="indent">5.4 -
<a href="#5.4">Why doesn't audio work properly under Irix?</a>
</div>
<div class="indent">5.5 -
<a href="#5.5">Why is FlightGear so slow?</a>
</div>
<div class="indent">5.7 -
<a href="#5.7">How do I see the frame rate?</a>
</div>
<div class="indent">5.8 -
<a href="#5.8">Stuck upside down after "crash"?</a>
</div>
<div class="indent">5.9 -
<a href="#5.9">Why does FlightGear die on startup saying "time zone reading failed"?</a>
</div>
<br>
<h4>6 -
<a href="#6">Hacking</a>
</h4>
<div class="indent">6.1 -
<a href="#6.1">What language is FlightGear written in?</a>
</div>
<div class="indent">6.2 -
<a href="#6.2">How do I design a flight dynamics model for a new aircraft?</a>
</div>
<div class="indent">6.3 -
<a href="#6.3">How do I import planes from Microsoft Flight Simulator?</a>
</div>
<div class="indent">6.4 -
<a href="#6.4">How do I import BGL scenery from Microsoft Flight Simulator?</a>
</div>
<div class="indent">6.5 -
<a href="#6.5">How do I design or modify a panel?</a>
</div>
<div class="indent">6.6 -
<a href="#6.6">How do I place objects, like buildings, into FlightGear?</a>
</div>
<div class="indent">6.7 -
<a href="#6.7">Where can I learn 3D programming and how do I get involved?</a>
</div>
<div class="indent">6.8 -
<a href="#6.8">How do I add an airport?</a>
</div>
<div class="indent">6.9 -
<a href="#6.9">How do I generate my own scenery?</a>
</div>
<br>
<h4>7 -
<a href="#7">Flying</a>
</h4>
<div class="indent">7.1 -
<a href="#7.1">Where can I learn about instrument flying and navigation?</a>
</div>
<div class="indent">7.2 -
<a href="#7.2">What is the difference between Aileron and Rudder?</a>
</div>
<div class="indent">7.3 -
<a href="#7.3">Is there support for multi-player flying?</a>
</div>
<div class="indent">7.4 -
<a href="#7.4">Is there support for any military scenarios like dog fighting or bomb dropping?</a>
</div>
<br>
<h4>8 -
<a href="#8">FlightGear v0.7.6</a>
</h4>
<div class="indent">8.1 -
<a href="#8.1">Why do I get an error in viewer.cxx about `exit' being undeclared?</a>
</div>
<br>
<hr>
<h2>
<a name="1">1 -
The FAQ</a>
</h2>
<b>
<a name="1.1">1.1 -
<u>Where can I get the latest version of this FAQ?</u>
</a>
</b>
<div class="indent">
<p>
<a href="http://flightgear.org/Docs/FlightGear-FAQ.html">http://flightgear.org/Docs/FlightGear-FAQ.html</a>
</p>
</div>
<b>
<a name="1.2">1.2 -
<u>Who do I contact if I have comments about this FAQ?</u>
</a>
</b>
<div class="indent">
<p>First contact the author. If you get no response, send your
comments to the FlightGear-Users mailing list.</p>
</div>
<b>
<a name="1.3">1.3 -
<u>How old is this document?</u>
</a>
</b>
<div class="indent">
<p>See the <i>About This Document</i> section at the end of the FAQ.</p>
</div>
<b>
<a name="1.4">1.4 -
<u>What other important documentation should I read?</u>
</a>
</b>
<div class="indent">
<p>Most FlightGear documentation is linked to from
<a href="http://flightgear.org/Docs/">http://flightgear.org/Docs/</a>.
Definitely check out the <i>FlightGear Installation and Getting
Started</i> document available from the aforementioned location.</p>
<p>Also see the <code>FlightGear/docs-mini/</code> directory in the
source distribution for various other helpful documents.</p>
</div>
<hr>
<h2>
<a name="2">2 -
Distribution</a>
</h2>
<b>
<a name="2.1">2.1 -
<u>Where can I get FlightGear?</u>
</a>
</b>
<div class="indent">
<p>The official download page is
<a href="http://flightgear.org/Downloads/">http://flightgear.org/Downloads/</a>.
Source code is our primary form of distribution, but precompiled
binaries are available for Windows and SGI IRIX.</p>
<p>Alternatively, FlightGear is packaged for Linux by SuSE, Debian
(sid), and Mandrake (Cooker) and can be directly installed through
those distributions.</p>
</div>
<b>
<a name="2.2">2.2 -
<u>What is the password for the FTP server?</u>
</a>
</b>
<div class="indent">
<p>The FTP server uses standard anonymous login procedures. Login
with the username "anonymous" and use your email address as the
password. Most FTP clients and web browsers will do this
automatically for you.</p>
</div>
<b>
<a name="2.3">2.3 -
<u>Why won't the FTP server let me in with the right login info?</u>
</a>
</b>
<div class="indent">
<p>This generally means that the server is at it's capacity. You
should receive a message saying such, but your FTP client may be
hiding it from you. Your options are to keep trying until a slot
opens up or try connecting to one of our <i>FTP</i> mirrors listed at
<a href="http://flightgear.org/mirrors.html">http://flightgear.org/mirrors.html</a>.</p>
</div>
<b>
<a name="2.4">2.4 -
<u>Where can I find the latest development source code?</u>
</a>
</b>
<div class="indent">
<p>The latest development code is available for everyone through our
git repository. See
<a href="http://wiki.flightgear.org/FlightGear_and_Git">http://wiki.flightgear.org/FlightGear_and_Git</a> for details.
</p>
<p>Otherwise, you can get relatively up-to-date snapshots of the
development tree at
<a href="http://flightgear.simpits.org:8080/">http://flightgear.simpits.org:8080/</a>, which are recompiled at every git commit.
</p>
</div>
<b>
<a name="2.5">2.5 -
<u>What is SimGear, and why do I need it?</u>
</a>
</b>
<div class="indent">
<p>SimGear is a library of supporting code. SimGear is only needed
if you plan on compiling FlightGear -- it is not needed to run
precompiled binaries. For more information see
<a href="http://www.simgear.org/">http://www.simgear.org/</a>.</p>
</div>
<b>
<a name="2.6">2.6 -
<u>Where can I fly and where do I get the scenery?</u>
</a>
</b>
<div class="indent">
<p>While the base package only comes with scenery for the San Francisco
Bay area, you can currently fly just about anywhere in the world.
See the <i>"Additional Scenery"</i> section of
<a href="http://flightgear.org/Downloads/">http://flightgear.org/Downloads/</a>
for more information or go directly to our graphical downloader at
<a href="http://flightgear.org/Downloads/world-scenery.html">http://flightgear.org/Downloads/world-scenery.html</a>.
</p>
<p>Also visit our <i>"Places to Fly"</i> section of the website
(<a href="http://flightgear.org/Places/">http://flightgear.org/Places/</a>)
for some help navigating to some awesome locations.</p>
</div>
<b>
<a name="2.7">2.7 -
<u>Where can I get different 3D models for my plane?</u>
</a>
</b>
<div class="indent">
<p>While we are working toward building our own 3D models, we have
been given permission by several people to convert their models (which
where originally intended for use with <i>Microsoft Flight
Simulator</i>) to use with FlightGear.</p>
</div>
<b>
<a name="2.8">2.8 -
<u>How current is the data in FlightGear compared to the real world?</u>
</a>
</b>
<div class="indent">
<p>We use the same navaid and airport dataset that <i>X-Plane</i> uses. The
current dataset can be found in the <code>$FGROOT/Navaids/</code> and
<code>$FGROOT/Airports/</code> directories. If you have updates or
corrections to the dataset, see
<a href="http://flightgear.org/Docs/AirNav/AptNavFAQ.FlightGear.html">http://flightgear.org/Docs/AirNav/AptNavFAQ.FlightGear.html</a>
for instructions on contacting the database maintainer.</p>
</div>
<b>
<a name="2.9">2.9 -
<u>Where is the moving map?</u>
</a>
</b>
<div class="indent">
<p>A popular moving map display is avaliable under a separate
project called <i>Atlas</i>. See
<a href="http://atlas.sf.net/">http://atlas.sf.net/</a>.</p>
</div>
<b>
<a name="2.10">2.10 -
<u>Why don't you charge money for this?</u>
</a>
</b>
<div class="indent">
<p>We could do that, since the initial download is about 25
megabytes. Especially for people who have to pay per-minute charges
for internet access, buying a CD is a convenient and possibly
cheaper option. Although we offer that service (see the website), we
encourage other groups to redistribute it for their users, especially
within an operating system distribution which makes installation even
faster and easier for new users.</p>
</div>
<hr>
<h2>
<a name="3">3 -
Compiling</a>
</h2>
<b>
<a name="3.1">3.1 -
<u>Why won't FlightGear compile?</u>
</a>
</b>
<div class="indent">
<p>Well, that depends. First make sure you are using the appropriate
versions of FlightGear, SimGear, plib, zlib. If any of
the packages are out of sync with the others, compilation may fail.</p>
<p>The FlightGear <i>Downloads</i> page
(<a href="http://flightgear.org/Downloads/">http://flightgear.org/Downloads/</a>)
should tell you what versions you need if you are trying to compile
the latest stable release. If you are using a development snapshot,
make sure all three packages are up-to-date.</p>
<p>Also ensure that you have some implementation of OpenGL with glut
support with the appropriate header files. Linux users with nVidia
cards should make sure you have the latest drivers from nVidia. Other
Linux users make sure you have Mesa3D
(<a href="http://mesa3d.org/">http://mesa3d.org/</a>)
and your X server installed correctly. Windows users see
<a href="http://www.x-plane.com/SYSREQ/v5ibm.html">http://www.x-plane.com/SYSREQ/v5ibm.html</a>,
and Mac users see
<a href="http://www.x-plane.com/SYSREQ/v5mac.html">http://www.x-plane.com/SYSREQ/v5mac.html</a>.
</p>
<p>If your problems persist, subscribe to our FlightGear-Users mailing
list and let us know what problem you're having. See
<a href="http://flightgear.org/mail.html">http://flightgear.org/mail.html</a> for help with this.
</p>
</div>
<b>
<a name="3.2">3.2 -
<u>I'm using RedHat 7, and ...?</u>
</a>
</b>
<div class="indent">
<p>Update your gcc packages. See
<a href="http://redhat.com/errata/">http://redhat.com/errata/</a>
to fix it and
<a href="http://www.gnu.org/software/gcc/gcc-2.96.html">http://www.gnu.org/software/gcc/gcc-2.96.html</a>
for an explanation why.</p>
</div>
<hr>
<h2>
<a name="4">4 -
Configuring</a>
</h2>
<b>
<a name="4.1">4.1 -
<u>How do I install new scenery?</u>
</a>
</b>
<div class="indent">
<p>The scenery archive files (ie. w100n30.tar.gz) should be untarred
into the <code>Scenery/Terrain</code> directory in your
<code>$FG_ROOT</code>.</p>
</div>
<b>
<a name="4.2">4.2 -
<u>How do I setup my joystick(s)?</u>
</a>
</b>
<div class="indent">
<p>FlightGear should come with a helpful program called <i>`fgjs`</i>
that can help configure your joystick. Run <i>`fgjs`</i> and then
copy the dot file it created into your home directory or add its
contents to your existing rc file.</p>
<p>Also, see the README.Joystick file located in the
<code>FlightGear/docs-mini/</code> directory of the source
distribution. This document is mirrored at
<a href="http://rockfish.net/fg/README.Joystick">http://rockfish.net/fg/README.Joystick</a>.
</p>
</div>
<b>
<a name="4.3">4.3 -
<u>What format should my personal .fgfsrc file be in?</u>
</a>
</b>
<div class="indent">
<p>Your <code>.fgfsrc</code> file should simply be a list of
command-line options with one option per line. The file is <b>not</b>
an XML file.</p>
<p>If you would rather use an XML configuration file, you can add
something like the following in your <code>.fgfsrc</code>
</p>
<p>
<code>--config=/path/to/my/config.xml</code>
</p>
<p>Almost every option corresponds to a property, so you can choose
to use whichever method best suits your needs.</p>
</div>
<hr>
<h2>
<a name="5">5 -
Running</a>
</h2>
<b>
<a name="5.1">5.1 -
<u>Why do I get an error loading libopenal.so.0?</u>
</a>
</b>
<div class="indent">
<p>With the default installation, libopenal.so.0 is installed into
<code>/usr/local/lib</code>. You need to ensure that that path is
listed in <code>/etc/ld.so.conf</code>, then run <i>`ldconfig`</i>as
root.</p>
</div>
<b>
<a name="5.2">5.2 -
<u>Why do I get "ssgInit called without a valid OpenGL context"?</u>
</a>
</b>
<div class="indent">
<p>In short, your GL libraries are broken. So far only Red Hat 7.x
users have experienced this (see
<a href="http://www.redhat.com/bugzilla/show_bug.cgi?id=18867">http://www.redhat.com/bugzilla/show_bug.cgi?id=18867</a>).
The only solutions are possibly complicated ones: you can either
change distributions (most of us prefer Debian) or upgrade/downgrade
your Mesa libs.</p>
<p>
<i>
<u>Why do some other GL applications work though?</u>
</i> Well,
Steve Baker (Mr. PLIB) has explained this on the plib-users list
(<a href="http://www.geocrawler.com/lists/3/SourceForge/1867/0/6470648/">http://www.geocrawler.com/lists/3/SourceForge/1867/0/6470648/</a>).
</p>
</div>
<b>
<a name="5.3">5.3 -
<u>What happened to the panel, keyboard, etc?</u>
</a>
</b>
<div class="indent">
<p>The problem is almost certainly that your base package is out of
sync with FlightGear. Many configurable parts of FlightGear are
defined in XML files contained in the base package.</p>
</div>
<b>
<a name="5.4">5.4 -
<u>Why doesn't audio work properly under Irix?</u>
</a>
</b>
<div class="indent">
<p>FlightGear (as of June 2001) uses the Portable Libraries (PLIB)
for playing audio. The audio queue implementation of PLIB is far from
optimal (in fact it's just wrong). This seems to work on other
platforms quite well, but Irix expects things to be programmed
properly.</p>
<p>There has been discussion about using OpenAL
(<a href="http://www.openal.org/">http://www.openal.org/</a>)
for the next release of both PLIB and FlightGear. Tests show that
the OpenAL audio implementation does the job right, meaning that
these audio problems should be gone by then. In the mean time it is
best to disable audio on Irix completely (by adding --disable-sound
either on the command line or to your <code>$HOME/.fgfsrc</code>
file).</p>
</div>
<b>
<a name="5.5">5.5 -
<u>Why is FlightGear so slow?</u>
</a>
</b>
<div class="indent">
<p>FlightGear supports hardware acceleration, but it seems not to be
activated. Make sure you have OpenGL libraries installed and
configured properly and make sure you have the latest drivers for your
video card.</p>
<p>
<b>Linux users</b>: If you are an nVidia user, follow their
directions on getting your card working. For most other users, make
sure Mesa is installed property and ensure that you have the
appropriate kernel device drivers for your card. Most people (and
distributions) use modules for their video card device drivers; run
<i>`lsmod`</i> as root to see what modules are loaded. You should also
make sure that you are loading the appropriate modules in your
XF86Config and that your video device section is correct. Now try
running an OpenGL application (other than FlightGear) to see how it
performs. You can try the <i>gears</i> demo from Mesa or something
like <i>Quake3</i>.</p>
</div>
<b>
<a name="5.7">5.7 -
<u>How do I see the frame rate?</u>
</a>
</b>
<div class="indent">
<p>There are two ways. One way is to hide the panel without the HUD
showing. To hide the panel, use <i>Shift+P</i>; To make the HUD
disappear, use <i>H</i>. The second way is to use the alternative
HUD by <i>Shift+I</i> (Use <i>I</i> to switch back).</p>
</div>
<b>
<a name="5.8">5.8 -
<u>Stuck upside down after "crash"?</u>
</a>
</b>
<div class="indent">
<p>In his infinite wisdom the FlightGear Grand Master decided that
planes were to valuable to allow them to be destroyed by novice pilots
who seemed to crash a lot. The fact that nobody has bothered to model
crashes may have something to do with it too. :-)</p>
<p>The result of this as you have noticed is that with a little
practice an ingenuity you can trim the ship to fly inverted along the
ground.</p>
<p>The quick answer is to hit Ctrl+U (with the default key bindings)
to warp the plane up 1000ft.</p>
<p>For the stubborn people out there: The trick to learn is to roll
back to normal (non inverted) do this by nursing the elevator to get
to about 500 feet or so and use the ailerons to snap roll 180*.
This is all good avionics except for the plane not destroying
itself. Remember the controls work in reverse when you are inverted
and keep that airspeed up!!!</p>
</div>
<b>
<a name="5.9">5.9 -
<u>Why does FlightGear die on startup saying "time zone reading failed"?</u>
</a>
</b>
<div class="indent">
<p>This is probably caused by a line-ending problem in the timezone
files. Win32 users can resolve the problem by downloading a DOS to
UNIX conversion utility available at
<a href="http://www.nottingham.ac.uk/~eazdluf/d2u.zip">http://www.nottingham.ac.uk/~eazdluf/d2u.zip</a>.
Run as `<i>d2u *.tab</i>` from within the timezone directory to fix
your timezone files.</p>
</div>
<hr>
<h2>
<a name="6">6 -
Hacking</a>
</h2>
<b>
<a name="6.1">6.1 -
<u>What language is FlightGear written in?</u>
</a>
</b>
<div class="indent">
<p>Mostly C++ with some supporting C code that's primary contained
within SimGear.</p>
</div>
<b>
<a name="6.2">6.2 -
<u>How do I design a flight dynamics model for a new aircraft?</u>
</a>
</b>
<div class="indent">
<p>To define an aircraft for FlightGear's primary FDM (JSBSIM),
see <a href="http://jsbsim.sf.net/">http://jsbsim.sf.net/</a>.</p>
<p>If you want a simpler FDM to work with, try your hand at YASim,
an alternative FDM. For an guide on creating a YASim aircraft,
look in the FlightGear base package for
<code>Aircraft-yasim/README.yasim</code>.</p>
</div>
<b>
<a name="6.3">6.3 -
<u>How do I import planes from Microsoft Flight Simulator?</u>
</a>
</b>
<div class="indent">
<p>You can import the 3D model and textures, but the flight dynamics
(the .AIR file) must be completely redone for FlightGear. </p>
<p>If you wish to import a model made with gmax, you will need to
convert it to .MDL format using <i>Microsoft's MakeMDL SDK</i> which
is available at
<a href="http://zone.msn.com/flightsim/FS02DevDeskSDK08.asp">http://zone.msn.com/flightsim/FS02DevDeskSDK08.asp</a>.
</p>
</div>
<b>
<a name="6.4">6.4 -
<u>How do I import BGL scenery from Microsoft Flight Simulator?</u>
</a>
</b>
<div class="indent">
<p>See
<a href="http://chiangt.virtualave.net/BGL/bgl_index.html">http://chiangt.virtualave.net/BGL/bgl_index.html</a>.
</p>
</div>
<b>
<a name="6.5">6.5 -
<u>How do I design or modify a panel?</u>
</a>
</b>
<div class="indent">
<p>See the README.xmlpanel file located in the
<code>FlightGear/docs-mini/</code> directory of the source
distribution. This document is mirrored at
<a href="http://rockfish.net/fg/README.xmlpanel">http://rockfish.net/fg/README.xmlpanel</a>.
</p>
</div>
<b>
<a name="6.6">6.6 -
<u>How do I place objects, like buildings, into FlightGear?</u>
</a>
</b>
<div class="indent">
<p>First, ensure that you have v0.7.7 or later, the scenery files
where you plan to place the object, the actual model, and the
longitude and latitude where you plan to place the object.</p>
<p>Now get the altitude for your point. If you don't want to
calculate this yourself, start FlightGear at your location and take
note of the altitude. Here's an example command:</p>
<p>
<code>fgfs --lat=45.50 --lon=-75.73 2&gt;&amp;1 | tee fgfs.log</code>
</p>
<p>The altitude is probably in feet, so divide the starting altitude
by 3.28.</p>
<p>Search the output log file for the first occurrence of the string
"Loading tile" and take note of the filename. In the above example,
the output line looks like:</p>
<p>
<code>Loading tile /usr/local/Scenery/w080n40/w076n45/1712601</code>
</p>
<p>Copy a 3D model in a format that Plib understands to the same
directory as the tile file. Edit the text file in that directory
consisting of the tile name with the extension ".stg". The file will
already exist if there is an airport on the tile; otherwise, you can
create it from scratch. In our example, the filename is:</p>
<p>
<code>/usr/local/Scenery/w080n40/w076n45/1712601.stg</code>
</p>
<p>At the end of the file, add a new entry for your object,
consisting of the word "OBJECT_STATIC" followed by the model name,
the longitude in degrees, the latitude in degrees, the altitude in
meters, and the heading in degrees. In our example the line looks
like:</p>
<p>
<code>OBJECT_STATIC Towerax.ac -75.73 45.40 60 0</code>
</p>
<p>Save the changes to the .stg file, restart FlightGear, and
enjoy.</p>
<p>NOTE: The above information was taken from the following mailing
list post:
<a href="http://www.geocrawler.com/archives/3/11854/2001/6/0/5991409/">http://www.geocrawler.com/archives/3/11854/2001/6/0/5991409/</a>.
See that page if this one doesn't make sense.</p>
<p>An alternative approach using PPE is described at
<a href="http://mail.flightgear.org/pipermail/flightgear-devel/2001-December/002239.html">http://mail.flightgear.org/pipermail/flightgear-devel/2001-December/002239.html</a>
by Norman Vine.</p>
</div>
<b>
<a name="6.7">6.7 -
<u>Where can I learn 3D programming and how do I get involved?</u>
</a>
</b>
<div class="indent">
<p>Contributing to the 2D panel doesn't require any coding at all,
just a minimal knowledge of XML syntax (i.e. five minutes' worth)
and good skills with drawing and/or paint programs. Every instrument
on the current panel, with the partial exception of the magnetic
compass, is defined entirely in XML with no custom C++ code. If
you want to get started, take a look at John Check's excellent intro
(<a href="http://rockfish.net/fg/README.xmlpanel">http://rockfish.net/fg/README.xmlpanel</a>).
</p>
<p>Likewise, if you want to create a 3D cockpit for FlightGear, or to
create buildings, external aircraft models, etc., your help is
*desperately* needed. The only rule is to go easy on the triangles
-- a model with 50,000 triangles probably won't be usable in
FlightGear, and one with 5,000 triangles, only marginally. If you
can design a nice 3D cockpit interior for a Cessna 172 (for example)
in a 3D design program such as ac3D or ppe, we have coders who will
be happy to add the support code in the C++.</p>
<p>If, on the other hand, you really want to get your hands dirty
with C++ coding, you'll have to buy a good OpenGL book eventually.
However, FlightGear uses a high-level library, plib, that hides most
of the details of OpenGL. To get started with 3D C++ coding, you
can take a look at the plib documentation and learn only as much
OpenGL as you need, when you need it.</p>
</div>
<b>
<a name="6.8">6.8 -
<u>How do I add an airport?</u>
</a>
</b>
<div class="indent">
<p>You can add your airport to the
<code>$FGROOT/Airports/default.apt.gz</code> file, but to get the
airport to show up visually, you will have to rebuild the scenery
around the airport. The format of the default.apt file is
documented at
<a href="http://flightgear.org/Docs/AirNav/AptNavFAQ.FlightGear.html">http://flightgear.org/Docs/AirNav/AptNavFAQ.FlightGear.html</a>.</p>
</div>
<b>
<a name="6.9">6.9 -
<u>How do I generate my own scenery?</u>
</a>
</b>
<div class="indent">
<p>Yes, though it can be a difficult task. FlightGear's scenery
generation is handled by a sister project, TerraGear. For more
details, see
<a href="http://terragear.org/">http://terragear.org/</a>.</p>
</div>
<hr>
<h2>
<a name="7">7 -
Flying</a>
</h2>
<b>
<a name="7.1">7.1 -
<u>Where can I learn about instrument flying and navigation?</u>
</a>
</b>
<div class="indent">
<p>
<a href="http://www.navfltsm.addr.com/">http://www.navfltsm.addr.com/</a>
is a very good site for learning techniques for navigation. Also see
<a href="http://www.monmouth.com/~jsd/how/">http://www.monmouth.com/~jsd/how/</a>.
</p>
</div>
<b>
<a name="7.2">7.2 -
<u>What is the difference between Aileron and Rudder?</u>
</a>
</b>
<div class="indent">
<p>There is a bit of info on aileron vs. rudder here:
<a href="http://www.monmouth.com/~jsd/how/">http://www.monmouth.com/~jsd/how/</a>.
</p>
</div>
<b>
<a name="7.3">7.3 -
<u>Is there support for multi-player flying?</u>
</a>
</b>
<div class="indent">
<p>We have an initial stab at this that is incomplete and only seems
to work under Linux. We'd love to find someone to pick up the
slack here and develop this further. Specifically, plib now has
some low level networking support for mult-player games. It would
also be nice to develop support for the DIS protocol.</p>
</div>
<b>
<a name="7.4">7.4 -
<u>Is there support for any military scenarios like dog fighting or bomb dropping?</u>
</a>
</b>
<div class="indent">
<p>No, not at this time. Most of our developers are primarily
interested and focused on civilian aviation. We aren't explicitly
excluding these features -- we just haven't had anyone who seriously
wanted to develop these areas.</p>
</div>
<hr>
<h2>
<a name="8">8 -
FlightGear v0.7.6</a>
</h2>
<b>
<a name="8.1">8.1 -
<u>Why do I get an error in viewer.cxx about `exit' being undeclared?</u>
</a>
</b>
<div class="indent">
<p>This error cropped up after the release of v0.7.6. To fix the
problem, add "<code>#include &lt;stdlib.h&gt;</code>" to the top of viewer.cxx.</p>
</div>
<hr noshade>
<a name="about">
<h2>About This Document</h2>
</a>
<b>FlightGear FAQ</b>
<br>$Revision$<br>$Date$<br>
<p>
<small>
This document generated from XML using
<a href="http://gingerall.com/charlie/ga/xml/p_sab.xml">Sablotron</a>.
</small>
</p>
</body>
<!-- vim: set ts=2 et nowrap: -->
</html>

488
docs-mini/Nasal.html Normal file
View File

@@ -0,0 +1,488 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Using Nasal with FlightGear</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<link rel="stylesheet" href="nasal.css">
</head>
<body>
<h1>Using Nasal with FlightGear</h1>
<p>This document is a tutorial on how to interface Nasal scripts
with FlightGear. It is not an introduction to the Nasal language
itself. For that, see Andy's <a
href="http://www.plausible.org/nasal/">Nasal website</a> at <a
href="http://www.plausible.org/nasal/">http://www.plausible.org/nasal</a>.
The information there is sparse, but you should have it ready for
reference while reading this document.
<h2>Basic Nasal/FlightGear Integration</h2>
<h3>Calling Nasal from Configuration File Bindings</h3>
Nasal scripts can be used as FGBinding objects, and can therefore
appear anywhere in a configuration file (keyboard, mouse and joystick
bindings, etc...) that accepts a <code>&lt;binding&gt;</code> tag.
The relevant command type is "nasal", and you place your Nasal code
inside of the <code>&lt;script&gt;</code> tag:
<pre>
&lt;binding&gt;
&lt;command&gt;nasal&lt;/command&gt;
&lt;script&gt;
print("Binding Invoked!");
&lt;/script&gt;
&lt;/binding&gt;
</pre>
<p>The code above invokes the <code>print()</code> function. This is
a simple extension function that simply prints out its arguments, in
order, to the FlightGear console as a single-line log entry. It is
useful for debugging, but little else.
<p>Some command have SGPropertyNode arguments. This argument is
available as a <code>props.Node</code> object and is returned from the
built-in <code>cmdarg()</code> function. See below for full
documentation, but as an example the following "joystick axis" binding
will print the current axis value to the console:
<pre>
&lt;binding&gt;
&lt;command&gt;nasal&lt;/command&gt;
&lt;script&gt;print(cmdarg().getNode("value").getValue());&lt;/script&gt;
&lt;/binding&gt;
</pre>
<p>Note that the current implementation parses the Nasal code inside
the <code>&lt;script&gt;</code> tag each time it is run. This means
that you should avoid placing large code blocks inside a
<code>&lt;script&gt;</code> tag for performance reasons. It also
means that any local variables you set inside the script will be lost
the next time it is run. See the discussion about namespaces and
Nasal source files below for more information.
<h3>Setting and Inspecting FlightGear Properties</h3>
<h4>getprop() and setprop()</h4>
<p>You can use <code>getprop()</code> and <code>setprop()</code>
functions to interact with the global property tree. They work as you
would expect. For example, the following Nasal code copies the value
of the "/sim/foo" property to the "/sim/bar" property:
<pre>setprop("/sim/bar", getprop("/sim/foo"));</pre>
<p>Note that Nasal's notion of "type" is coarser than that of the
SGPropertyNode class. Numers and strings come out of
<code>getprop()</code> as Nasal scalars, of course, and boolean
properties are converted to a numeric 1 or 0 by
<code>getprop()</code>. But <b>all</b> non-string values passed to
<code>setprop()</code> become doubles in the property tree. The
props.Node interface (see below) provides the ability to set explicit
types in the property tree.
<p>A useful feature of getprop and setprop that you should be aware of
is that they both accept variable numbers of arguments. These are
concatenated together to form a property tree path internally within
the function. This avoids the need for extensive string concatenation
in the script for the common case where you are acting on a variable
property root. That is, you can do:
<pre>
ThisAircraft = "/sim/my/aircraft/properties";
setprop(ThisAircraft, "crashed", 0);
</pre>
to set the property "/sim/my/aircraft/properties/crashed" to false.
This feature is useful for writing Nasal functions that will work on
parameterized property trees.
<h4>The props module</h4>
<p>Think of the <code>getprop()</code> and <code>setprop()</code>
functions as equivalents of the <code>fgGet*()</code> and
<code>fgSet*()</code> C++ functions. They provide simple and easy
access to the global property tree.
<p>For some situations, however, you need finer control over the
property nodes. For these situations you can use the props module,
which provides a <code>Node</code> class similar to the SimGear
<code>SGPropertyNode</code> class. The global tree is available as a
<code>Node</code> object named <code>props.globals</code>. You can
use the <code>getNode()</code> method on it to retrieve an arbitrary
sub-node. The children of any given node can be inspected with
<code>getChild()</code> and <code>getChildren()</code> methods. And
of course its name, index, and value can be accessed with appropriate
methods. See the reference below for complete documentation.
<p>As seen above in the discussion on <code>fgcommand()</code>, you
can also create new, "rootless" <code>Node</code> objects using
<code>props.Node.new()</code>.
<p>The most powerful method on a Node object is
<code>setValues()</code>. This takes a Nasal hash table as its only
argument, and initializes properties under the node using the
key/value pairs in the hash. This works with vectors (i.e. indexed
properties) and recursively, essentially making a deep copy of a Nasal
object in the property tree.
<p>For debugging (and amusement) purposes, the <code>props</code>
modules also defines a <code>dump()</code> function which recursively
prints the state of a property node to the console. Try
<code>props.dump(props.globals)</code> to see it walk the entire tree.
<h3>Invoking FlightGear Commands from Nasal</h3>
<p>Just as Nasal code can be run as a command binding from the
property tree, existing FlightGear commands can be invoked by Nasal
code using the <code>fgcommand()</code> function. The first argument
to this function is a string, equivalent to what you would place
inside the <code>&lt;command&gt;</code> tag in a property binding.
The second argument specifies the property tree that will be passed as
the "arguments" to the command. It can be a either a string
specifying a path in the global property tree or a props.Node object.
Example:
<pre>
# Use a temporary property in the global tree
ShowDialog = func {
setprop("/nasal/tmp/dialog-args/dialog-name", arg[0];
fgcommand("dialog-show", "/nasal/tmp/dialog-args");
}
# Does the same thing, but with a rootless Node object
ShowDialog = func {
fgcommand("dialog-show", props.Node.new({dialog-name : arg[0]});
}
</pre>
These both define a <code>ShowDialog()</code> function, which pops up
a named dialog from the <fgroot>/gui/dialogs directory. Calling
<code>ShowDialog("autopilot")</code> will therefore pop up the
autopilot dialog just as if it had been bound to a key.
<p>The first variant uses a "temporary" property tree in the global
property space to hold the arguments. The second creates a new
<code>props.Node</code> object instead. Note that
<code>props.Node.new()</code> accepts a hash table as its argument and
uses that to initialize the returned property tree.
<h3>Writing extended Nasal code in source files</h3>
<p>Nasal is a "real" language, with real namespaces and modules. What
"really" happens when you run a script binding is that the script is
treated as a function body and bound (lexically, in the functional
programming sense) to a single global namespace. It is as if it were
enclosed in a <code>func { ... }</code> expression and executed inside
a "file" containing all the global symbols.
<p>Some symbols in the global namespace are built-in extension
functions, like the print/getprop/setprop we have already seen.
Others are objects (or hash tables -- they are the same thing in
Nasal). These objects act as namespaces and can contain code of their
own. One such example is the math library. The built-in math
functions live in their own namespace and are accessible as
<code>math.sin()</code>, <code>math.cos()</code>, etc...
<p>The global namespace itself is available as a module named
"globals". This allows you to create new symbols in the global
namespace if you desire (be careful!) and to otherwise inspect its
contents. It's just a hash table, after all. The following code will
print all the symbols found in the global namespace:
<pre>
print("These are the symbols found in the global namespace:");
foreach(i; keys(globals)) { print(" ", i); }
</pre>
<p>You can write your own modules, too. The mechanism is very simple:
merely create a file with a ".nas" extension in the Nasal directory of
your FlightGear base package. FlightGear will read, parse and execute
these files during initialization, and create a module of the same
name for use by your scripts. So you can write, say, a "mouse.nas"
script. Functions defined therein are available to your script
bindings (and any other nasal code on the system) as members of the
global "mouse" object. So you can define bindings that do things like
<code>mouse.handleXAxis(offset)</code> to call functions defined in
the mouse.nas file (remember that "offset" is an automatically
initialized variable containing the binding's offset argument).
<h3>Including Nasal Code from Configuration Files</h3>
<p>Nasal modules can also be imported from the property tree at
initialization. This is useful for applications like
aircraft-specific scripts that need to be loaded only when that
aircraft is active. The usage is simple: the Nasal interpreter
creates a module for every property node child of "/nasal" that it
finds at initialization time. Example:
<pre>
&lt;nasal&gt;
&lt;c172&gt;
&lt;file&gt;Aircraft/c172/c172.nas&lt;/file&gt;
&lt;/c172&gt;
&lt;/nasal&gt;
</pre>
This creates a module named "c172" and loads the contents of the
Aircraft/c172/c172.nas file into it. The module name is, by default,
the same as the property node. But this can be overridden with the
<code>&lt;module&gt;</code> tag. This trick can be useful if you need
to load extra script source into a previously-initialized module.
<p>You can also write literal Nasal scripts inside the property files
by including it in a <code>&lt;script&gt;</code> tag. This sample
uses the <code>&lt;module&gt;</code> tag to add an extra function to
the math library.
<pre>
&lt;nasal&gt;
&lt;c172-tmp1&gt; &lt;!-- Use a unique, dummy name --&gt;
&lt;module&gt;math&lt;/module&gt;
&lt;script&gt;&lt;[CDATA[
# The math library doesn't include this, because Andy is a pedant
# and thinks it's dangerous. But the c172 code just *has* to have
# it.
atan = func { return atan2(arg[0], 1) }
]]&gt;&lt;/script&gt;
&lt;/c172-tmp1&gt;
&lt;/nasal&gt;
</pre>
Note the use of a CDATA declaration. This is required to properly
escape XML special characters like "<code>&lt;</code>". As it
happens, this code doesn't use them. But the CDATA is good practice
nonetheless.
<h3>Function Reference</h3>
<p>These are the built-in extension functions available to all Nasal
code in FlightGear. Be sure to examine the <a
href="http://www.plausible.org/nasal/doc.html">core Nasal
documentation</a> at the <a
href="http://www.plausible.org/nasal">Nasal site</a> as well. Only
FlightGear-specific library code is documented here:
<h4>Global Functions</h4>
<dl>
<dt>rand()
<dd>Returns a random number in the range [0:1) (that is, 0.0 is a
possible return value, but 1.0 is not).
<dt>getprop()
<dd>The arguments are concatenated to form a path to a global
property node. Returns the value of that node, or nil if it does
not exist.
<dt>setprop()
<dd>The final argument specifies a value to set. The remaining
arguments are concatenated to form a property path as in
getprop().
<dt>print()
<dd>The arguments are printed, in order, to the FlightGear console.
A newline is appended by the logging code, none is
required.
<dt>fgcommand()
<dd>The first argument is a string specifying a FlightGear command to
execute (e.g. "show-dialog"). The second is a property sub-tree
(either a global path string or a props.Node object) which will be
passed to the command as arguments.
<dt>settimer()
<dd>The first argument is a Nasal expression which evaluates to a
Nasal function object (it can be either a symbol name for a
function or a literal <code>func&nbsp;{&nbsp;...&nbsp;}</code>
expression. The second argument is a (floating point) number
specifying a delta time in seconds. Some time after that delta
time has elapsed, the specified function will be invoked. Exact
timing will depend on the frame rate of the simulator.
<dt>interpolate()
<dd>The first argument specifies a property. It can be either a
string representing a global property name or a
<code>props.Node</code> object. The remaining arguments specify
pairs of value/delta-time numbers. The property is interpolated
smoothly from its current value to the new value over the
specified time delta, in seconds. Multiple value pairs can be
used to indicate successive values or to acheive a piecewise
linear approximation to a non-linear function. This function
cancels any preexisting interpolation for that property, so
<code>interpolate("/sim/countdown",&nbsp;0,&nbsp;0)</code> has the
effect of cancelling interpolation of "/sim/countdown" and setting
its value to zero.
</dl>
<h4>Property Module</h4>
<dl>
<dt>Node
<dd>The <code>props.Node</code> class wraps a SGPropertyNode object,
either in or outside of the global property tree. It supports the
following methods:
<dl>
<dt>getType()
<dd>Returns the "type" of the SGPropertyNode object. The return value
is a string; one of: NONE, ALIAS, BOOL, INT, LONG, FLOAT, DOUBLE,
STRING or UNSPECIFIED.
<dt>getName()
<dd>Returns the name of the property node.
<dt>getIndex()
<dd>Returns the child index of the property node.
<dt>getValue()
<dd>Returns the current value of the node, or nil if it has none.
<dt>setValue()
<dd>Sets the current value as either a string or a double, depending
on the internal type of the argument.
<dt>setIntValue()
<dd>Sets the current value, forcing the type to INT
<dt>setBoolValue()
<dd>Sets the current value, forcing the type to BOOL
<dt>setDoubleValue()
<dd>Sets the current value, forcing the type to DOUBLE
<dt>getParent()
<dd>Returns a Node object representing this node's parent, or nil if
it has none.
<dt>getChild()
<dd>Returns a named child, or nil if it does not exist. If multiple
children with that name exist, returns the one with an index of zero.
<dt>getChildren()
<dd>Returns a vector containing all the node's children.
<dt>removeChild()
<dd>Removes a child by name (first argument) and index (second argument).
<dt>getNode()
<dd>Returns a Node specified by its "relative path" to this node, or
nil if none exists. The optional second argument, if true, causes the
node to be created if it does not exist.
<dt>setValues()
<dd>Takes a hash as argument, and sets all the key/value pairs in the
hash as property subnodes of the object. This works recursively, with
sub-hashes and vectors; thus making a deep copy of the Nasal hash in
the property tree.
</dl>
<dt>props.Node.new()
<dd>Static "constructor" function returning a new, rootless
<code>Node</code> object. Takes a hash argument to initialize the
new node via setValues().
<dt>props.globals
<dd>This is a <code>Node</code> object representing the root of the
global property tree; the Nasal equivalent of
<code>globals->get_props()</code>
<dt>props.dump()
<dd>This method prints out a "dump" of the state of a single
<code>Node</code> object and all of its children to the console.
Very useful for debugging and exploration.
</dl>
<h2>Integrating C++ code and Nasal</h2>
<h3>Calling Nasal from C++</h3>
<p>The FGNasalSys object has a <code>parseAndRun()</code> method to
which you can pass arbitrary Nasal source code for immediate
execution:
<pre>
FGNasalSys n = (FGNasalSys*)globals->get_subsystem("nasal");
if(! n->parseAndRun("print('This script was called from C++!')"))
SG_LOG(SG_GENERAL, SG_ALERT, "My Nasal code failed :(");
</pre>
<p>You can also use <code>parseScript()</code> to get a pointer to a
<code>FGNasalScript</code> object. This object supports a
<code>call()</code> method which you can use to invoke the script
later on, at a time of your choosing. If you will be invoking the
script multiple times, this mechanism can be more efficient because it
avoids the parsing and code generation overhead for the successive
calls.
<pre>
FGNasalSys n = (FGNasalSys*)globals->get_subsystem("nasal");
FGNasalScript* script = n->parseScript("print('Spam!')"))
if(!script) SG_LOG(SG_GENERAL, SG_ALERT, "My Nasal code failed :(");
...
for(int i=0; i<1000; i++)
script->call(); // Spam the console
</pre>
<p>Note that there is no way to inspect the return value of the
function that you called. It simply returns a boolean indicating
successful execution. Handling of "native" Nasal data structures has
to be done via the Nasal extension API. See below.
<h3>Calling C++ from Nasal</h3>
<p>You have three options for invoking C++ code from Nasal. The first
two take advantage of pre-existing FlightGear mechanisms for
registering "callback" handlers for specific events.
<p>If your task is sufficiently general, you should consider defining
it as a new FGCommand using the existing interface. This can be
invoked efficiently from both Nasal code (using the fgcommand()
function) and existing property bindings, and is very easy to do.
Simply define a handler function which takes a property tree as an
argument and returns a bool (to indicate successful execution), and
register it during initialization with the global command manager:
<pre>
// Define your handler function:
bool my_new_command(SGPropertyNode* arg) { ... }
...
// And register it in your initialization code:
globals->get_commands()->addCommand("my-new-command", my_new_command);
...
</pre>
<p>This mechanism works well when your C++ code is a "global" function
that you will want to call from many locations with potentially
differing data. For some applications, however, you want to register
a handler that will be called only by code involved with computations
on a single data set.
<p>For this, there is the property listener interface. You can create
a subclass of SGPropertyChangeListener which implements the
valueChange, childAdded and/or childRemoved methods and associate it
with a specific property node in the global tree. You can then
"invoke" this handler from Nasal code (or from anywhere else) by
simply setting the property value.
<p>I haven't tested the property listener interface, and it requires
somewhat more typing to implement; so I will include no example here.
It is also rather rarely used by existing FlightGear code (the
property picker GUI is the only significant application I could find).
<h3>Extending Nasal</h3>
<p>This is the third mechanism for invoking C++ (strictly C, in this
case) code from Nasal. This is the API you must use if you want to
inspect and/or modify Nasal data structures, or create a function
object that will be visible to Nasal scripts as a callable function.
Unfortunately, there really isn't space here to document this API
fully. For now, examin the <code>nasal.h</code> header which defines
it, and the <code>lib.c</code> and <code>mathlib.c</code> source files
which implement the existing built-in library functions. The
FlightGear-specific extension functions in <code>NasalSys.cxx</code>
and <code>nasal-props.cxx</code> are also good examples.
<p>But for most purposes, consider the first two mechanisms instead.
FlightGear's general inter-module communication mechanism is the
property tree, which is exposed from both Nasal and C++ code already.
A Nasal extension function, by definition, is useful only to Nasal
code. Even worse, data structures definied by a Nasal interface are
completely invisible to the C++ world.
</body>
</html>

64
docs-mini/README-cmake.md Normal file
View File

@@ -0,0 +1,64 @@
# CMake in FlightGear overview
CMake has evolved considerably in the past decade; if you're reading external tutorials abput it, ensure
they mention 'modern CMake', or the information will be incorrect.
The top-level `CMakeLists.txt` handles configuration options, finding dependencies, and scanning
the rest of the source tree. Across the source tree we add executables, including the main FGFS
binary but also other helpers and utilities. We also define targets for helper libraries, for
various reasons; for example to build some code with different include paths or flags.
Due to the historical code structure, we use some helper functions to collect most of the
application sources into two global CMake variables, which are then read and added to the
main executable target, in `src/Main/CMakeList.txt`. Therefore, many subdirectories have
a trivial `CMakeLists.txt` which simply calls the helper functions to add its sources:
```
include(FlightGearComponent)
set(SOURCES
foo.cxx
bar.cxx
)
set(HEADERS
foo.hxx
bar.hxx
)
flightgear_component(MyComp "${SOURCES}" "${HEADERS}")
```
The global properties used are `FG_SOURCES` and `FG_HEADERS`.
## Configurations
Official release builds are built with `RelWithDebInfo`; this is also the most useful configuration for
development, since on Windows, `Debug` is unusably slow. If trying to optimise performance,
keep in mind that compiler flags must be manually set for `RelWithDebInfo`; they are _not_
automatically inherited from `Release`.
Adding additional configurations is possible: for example for profiling. CMake also picks up
the `CXXFLAGS` environment variable to pass ad-hoc compiler options, without modifying the
build systen.
## Dependencies
All dependencies should be handled via an `IMPORTED` target: this ensures that include paths,
link options, etc specific to the dependency are handled correctly across different platforms.
For some dependencies, there may be a zFoo-Config.cmakez which defines such a target for
you automatically. Or there may be an existing `FindFoo.cmake` which does the same. If neither
of these situations exist, create a custom finder file in `CMakeModules`, following the existing
examples.
CMake tracks transitive dependencies precisely, so for example if your new dependency is used
in SimGear, it will automatically be added to the include / link paths for FlightGear based on
the SimGear build type.
If you encounter a case where a downstream target is missing an include path or flag for a
dependency, it typically indicates a bug in your dependency graph. Do _not_ fix it by maanually
modifying the downstream target's include path or flags. Rather, fix your dependency graph
and/or `INTERFACE` exports from your dependency, so that CMake can see the required transitive
dependencies correctly.

26
docs-mini/README-mp-carriers.md Normal file
View File

@@ -0,0 +1,26 @@
# MP carriers
[TOC]
## Overview
There are two settings properties that improve the behaviour of MP carriers.
Both appear in the "Multiplayer Settings" dialogue, from menu "Multiplayer/Multiplayer Settings".
* `/sim/mp-carriers/auto-attach`
This is true by default.
When an MP carriers appear, we automatically enable the matching AI scenerio so that it will
be visible to the user.
* `/sim/mp-carriers/latch-always`
This is not enabled by default.
When enabled we force an AI carrier to exactly follow the position and orientation of the MP carrier; this is done by C++ in each frame (otherwise Flightgear uses Nasal to periodically change the AI carrier's velocity to make it approximately follow the MP carrier).
This works better as long as multiplayer motion is smooth (e.g. with simple-time).
And it also improves behaviour when replaying recordings because the carrier position is replayed exactly the same as when recorded.

152
docs-mini/README-recordings.md Normal file
View File

@@ -0,0 +1,152 @@
# Flightgear recordings
[TOC]
## Overview
Recording files generally have a `.fgtape` suffix.
As of 2020-12-22, there are three kinds of recordings:
* Normal
* Continuous
* Recovery
Normal recordings are compressed and contain frames at varying intervals with more recent frames being closer together in time. They are generated from the in-memory recording that Flightgear always maintains. They may contain multiplayer information.
Continuous recordings are written directly to a file while Flightgear runs, giving high resolution with near unlimited recording time. They may contain multiplayer information. As of 2020-12-23 they may contain information about extra properties, allowing replay of views and main window position/size. As of 2021-06-26 each frame's data can be compressed.
Recovery recordings are essentially single-frame Continuous recordings. When enabled, Flightgear creates them periodically to allow recovery of a session if Flightgear crashes.
## Properties that control recording and replay
* `/sim/replay/tape-directory` - where to save recordings.
* `/sim/replay/record-multiplayer` - if true, we include multiplayer information in Normal and Continuous recordings.
* Normal recordings:
* `/sim/replay/buffer/high-res-time` - period for high resolution recording.
* `/sim/replay/buffer/medium-res-time` - period for medium resolution.
* `/sim/replay/buffer/low-res-time` - period for low resolution.
* `/sim/replay/buffer/medium-res-sample-dt` - sample period for medium resolution.
* `/sim/replay/buffer/low-res-sample-dt` - sample period for low resolution.
* Continuous recordings:
* `/sim/replay/record-continuous` - if true, do continuous record to file.
* `/sim/replay/record-signals` - if true (the default), include signals for user aircraft - these are the core values used to replay the user aircraft.
* `/sim/replay/record-extra-properties` - if true, we include selected properties in recordings.
* `/sim/replay/record-continuous-compression` - if 1, we compress each frame's data.
* `/sim/replay/record-main-window` - if 1, we record main window position and size.
* `/sim/replay/record-main-view` - if 1, we record main window view details.
* `/sim/replay/replay-main-window-position` - if 1, we replay main window position.
* `/sim/replay/replay-main-window-size` - if 1, we replay main window size.
* `sim/replay/replay-main-view` - if 1, we replay main window view (view type, orientation, zoom etc).
* Recovery recordings:
* `/sim/replay/record-recovery-period` - if non-zero, we update recovery recording in specified interval.
## Code
The code that creates recordings is not particularly clean or easy to work with.
It consists mainly of two source files:
* `src/Aircraft/flightrecorder.cxx`
* `src/Aircraft/replay.cxx`
Despite their names these files are both involved with record and replay. `src/Aircraft/flightrecorder.cxx` is lower-level; it takes care of setting up data for each frame when recording (see `FGFlightRecorder::capture()`) and reading data when replaying (see `FGFlightRecorder::replay()`).
`src/Aircraft/replay.cxx` is complicated and does various things. It maintains 3 in-memory buffers containing recording information at different temporal resolutions so that Flightgear can store any session in memory. For example only the most recent 60s is recorded at full frame rate.
## File formats
### Normal recordings
Normal recordings are written as a compressed gzip stream using `simgear::gzContainerWriter`.
* Header:
* A zero-terminated magic string: `FlightGear Flight Recorder Tape` (variable `FlightRecorderFileMagic`).
* A Meta property tree containing a `meta` node with various child nodes.
* A Config property tree containing information about what signals will be contained in each frame.
Each signal is a property; signals are used for the main recorded information such as position and orientation of the user's aircraft, and positions of flight surfaces, gear up/down etc. Aircraft may define their own customised set of signals.
The Meta and Config property trees are each written as `<length:64><text>` where `<text>` is a text representation of the properties. `<text>` is terminated with a zero which is included in the `<length:64>` field.
* A series of frames, each containg the data in a `FGReplayData` instance, looking like:
* Frame time as a binary double.
* Signals information as described in the header's `Config` property tree, represented as a 64-bit length followed by binary data.
### Continuous recordings
* Header:
* A zero-terminated magic string: `FlightGear Flight Recorder Tape` (variable `FlightRecorderFileMagic`).
* A property tree represented as a `uint32` length followed by zero-terminated text. This contains:
* A `meta` node with various child nodes. If this contains `continuous-compression` with value `1`, then each frame's data is compressed..
* `data[]` nodes describing the data items in each frame in the order in which they occur. Supported values are:
* `signals` - core information about the user's aircraft.
* `multiplayer` - information about multiplayer aircraft.
* `extra-properties` - information about extra properties.
* A `signals` node containing layout information for signals, in the same format as for Normal recordings.
The header is written by `FGReplay::continuousWriteHeader()`.
* A series of frames, each containg the data in a `FGReplayData` instance, looking like:
* Frame time as a binary double.
* If compression is used:
* uint8_t flags.
* Bit 0: this frame has signals.
* Bit 1: this frame has multiplayer information.
* Bit 2: this frame has extra properties.
* uint32_t compressed-size.
* Frame data (can be compressed): a list of ordered `<length:32><data>` items as described by the `data[]` nodes in the header. This format allows Flightgear to skip data items that it doesn't understand if loading a recording that was created by a newer version.
* For `signals`, `<data>` is binary data for the core aircraft properties.
* For `multiplayer`, `<data>` is a list of `<length:16><packet>` items where `<packet>` is a multiplayer packet as received from the network.
* For `extra-properties`, `<data>` is a list of property changes, each one being:
* `<length:16><path><length:16><value>` - property `<path>` has changed to `<value>`.
Removal of a property is encoded as `<0:16><length:16><path>`.
## Replay of Continuous recordings
When a Continuous recording is loaded, `FGReplay::loadTape()` first steps through the entire file, building up an index in memory that maps from frame times to a struct containing the offset of the frame in the file plus information on whether the frame has multiplayer and/or extra-properties information. This allows us to support the user jumping forwards and backwards in the recording.
If the recording uses compression, indexing uses the uint8_t flags and uint32_t compressed-size fields and does not need to decompress each frame's data.
If we are replaying from a URL, indexing takes place in the background (by requesting callbacks from the download's `simgear::HTTP::FileRequest`) and replay starts immediately. Thus we avoid having to wait until the entire recording has been downloaded before starting replay.
## Multiplayer
### Recording while replaying:
If the user replays part of their history while we are saving to a Continuous recording, and the Continuous recording includes multiplayer information, then we carry on receiving multiplayer information from the network and writing it to the Continuous recording. The user's aircraft is recorded as being stationary for the period when the user was replaying.
### Replaying
When replaying a recording that contains multiplayer information, the recorded multiplayer information is displayed to the user, and any live multiplayer information is ignored.
As of 2021-03-06 the code attempts to hide recorded chat messages and let through live chat messages when replaying. Unfortunately this doesn't work because it assumes that chat messages are sent as `CHAT_MSG_ID` packets, but actually they are sent as part of generic `POS_DATA_ID` packets (where they set the `/sim/multiplay/chat` property).
### Details
The way that Multiplayer data is handled is a little complex. When recording, we build up a buffer of multiplayer packets that we have received since the last time that we wrote out a frame of data, then write them all out in the next frame we write.
When replaying, `FGFlightRecorder::replay()` sends replayed multiplayer messages into the low-level multiplayer packet-receiving code by calling `FGMultiplayMgr::pushMessageHistory()`.

63
docs-mini/README-sentry.md Normal file
View File

@@ -0,0 +1,63 @@
# Sentry.io Cash Reporting
FlightGear can optionally report crashes and serious errors to Sentry.io. We have a sponsored
account provided gratis by Sentry; for access to this, ask on the developer list.
## Error conditions
If FlightGear crahses, Sentry will automatically submit a report. For non-crash errors,
we manually submit an exception report. At present this is done whenever we trigger the
`fatalMessageBox`, and in other serious situations. Deciding where is appropriate (or not)
to report the error to Sentry is a key challenge of the system, since we don't want to
report user misconfiguration problems, but we do want to detect recurring and
systematic failures, eg broken aircraft.
In general since we have (almost) unlimited event limits on our sponsored plan, it's
better to send errors and filter them on the server side, but this needs to be done
with some intelligence; for example we do not (at present) report Nasal runtime
errors, since this might overload the system.
## Data Protection
We explicitly do not include any personal information in the reports, and disable IP address
collection. This avoids any GPDR obligations for us.
Since this makes it hard to cluster reports by user, we instead generate a UUID
corresponding to a FlightGear installation. This gives us a way to anonymously cluster reports
by computer, without any personal data disclosure. (So we can determine if a hundred reports of a
crash come from fifty discrete users, or just one)
## Supplementatal Data
We record various pieces of configuration state as 'tags': such as the OS, graphics card,
major settings (eg, is multi-player enabled, which aircraft is being flown) as _tags_ in
Sentry terminology. This allows grouping of reports by similar tags; for example we can
identify that a particular crash only occurs with Intel Graphics, or when flying the
C172.
Additionally we record 'breadcrumbs'; these are included with an error report if one
is sent, and give an idea of the path of the user through the application, prior to the
crash. We have breadcrumbs for key events such as the splash-screen completing, the
user changing position, or scenery being reloaded.
`WARN` and `ALERT` level `SG_LOG` messages are currently included as breadcrumbs automatically;
this means it's important not to casually add messages at the levels for non-serious conditions.
The integration code has a list of commonly ocurring but non-useful messages which are
skipped from sending; especially some OSG ones related to PNG and AC3D data issues.
Adding new tags or breadcrumbs should be done with care, but is generally useful, and
suggestions in this area are appreciated.
## API
All the API is contained in `sentryIntegration.hxx`, inside the `flightgear` namespace.
The methods are no-ops if the Sentry SDK was not available at CMake time, and are also
no-ops if the user has disabled sentry reporting.
## Building
The API requires the injection of a private API key to report to our account; this
must be kept private of course, so it's injected into official builds at CMake time
on Jenkins, via the environment variable `FLIGHTGEAR_SENTRY_API_KEY`.
The build must be configured to produce debug symbols, which are uploaded to Sentry
via the `sentry-cli` tool as part of our build scripts.

39
docs-mini/README-simple-time.md Normal file
View File

@@ -0,0 +1,39 @@
# Simple-time
[TOC]
## Overview
Simple-time allows Flightgear multiplayer sessions to see a consistent and smoothly varying view of each other, regardless of framerates or network delays.
For example in multiplayer refueling, each pilot will see the same relative position of the two aircraft.
## Using simple-time
Simple-time is enabled in the "Time Mode" dialogue (from menu "File/Time Mode"), or from the command line with: `--prop:bool:/sim/time/simple-time/enabled=true`.
There are no configuration settings.
## How it works
When simple-time is being used, Flightgear always sends its computer's UTC time in multiplayer packets. Received packets' time stamps will always be slightly in the past due to network delays, so multiplayer aircraft are positioned using extrapolation - by predicting where they would be now based on where they were a small time ago, using the velocity information in the MP packet.
So with multiple instances of Flightgear running, as long as their clocks are synchronised to within a few tenths of a second (typically via NTP, Network Time Protocol, the standard way for computers to set their clocks to the global standard) and network delays are similarly not more than a few tenths of a second, each pilot will see a consistent view of all aircraft.
## Coping with MP packets from Flightgear instances that are not using simple-time.
If we are running with simple-time but a particular MP aircraft's MP packet times are not within a second or two of our UTC time, we assume that they are not using simple-time, and we use a smoothed version of the time difference as compensation (basically assuming zero network delay). Thus the MP aircraft will appear to move smoothly to us, but the two pilots will probably not see the same relative positions of the aircraft.
## Recordings
If simple-time is being used, recordings will also contain the UTC time, for both the user aircraft and any multiplayer aircraft if they are included in the recording (see "File/Flight Recorder Control"). Thus replaying a recording could replicate the original position of the sun etc.
## Testing
The script `flightgear/scripts/python/recordreplay.py` includes checks of simple-time behaviour.

147
docs-mini/README.IO Normal file
View File

@@ -0,0 +1,147 @@
This document describes how to invoke FlightGear's generic IO subsystem.
FlightGear has a fairly flexible generic IO subsystem that allows you
to "speak" any supported protocol over any supported medium. The IO
options are configured at runtime via command line options. You can
specify multiple entries if you like, one per command line option.
The general form of the command line option is as follows:
--protocol=medium,direction,hz,medium_options,...
protocol = { native, nmea, garmin, fgfs, rul, pve, ray, etc. }
medium = { serial, socket, file, etc. }
direction = { in, out, bi }
hz = number of times to process channel per second (floating
point values are ok.
Generic Communication:
--generic=params
With this option it is possible to output a pre-configured
ASCII string or binary sequence using a predefined separator.
The configuration is defined in an XML file located in the
Protocol directory of the base package.
params can be:
serial port communication: serial,dir,hz,device,baud,protocol
socket communication: socket,dir,hz,machine,port,style,protocol
i/o to a file: file,dir,hz,filename,protocol
See README.protocol for how to define a generic protocol.
Serial Port Communication:
--nmea=serial,dir,hz,device,baud
device = OS device name of serial line to be open()'ed
baud = {300, 1200, 2400, ..., 230400}
example to pretend we are a real gps and output to a moving map application:
--nmea=serial,out,0.5,COM1,4800
Note that for unix variants you might use a device name like "/dev/ttyS0"
Socket Communication:
--native=socket,dir,hz,machine,port,style
machine = machine name or ip address if client (leave empty if server)
port = port, leave empty to let system choose
style = tcp or udp
example to slave one copy of fgfs to another
fgfs1: --native=socket,out,30,fgfs2,5500,udp
fgfs2: --native=socket,in,30,,5500,udp --fdm=external
This instructs the first copy of fgfs to send UDP packets in the
native format to a machine called fgfs2 on port 5500.
The second copy of fgfs will accept UDP packets (from anywhere) on
port 5500. Note the additional --fdm=external option. This tells
the second copy of fgfs to not run the normal flight model, but
instead set the FDM values based on an external source (the
network in this case.)
File I/O:
--garmin=file,dir,hz,filename
filename = file system file name
example to record a flight path at 10 hz:
--native=file,out,10,flight1.fgfs
example to replay your flight
--native=file,in,10,flight1.fgfs --fdm=external
You can make the replay from a file loop back to the beginning
when it reaches the end of the file with the "repeat" flag:
--generic=file,in,20,flight.out,playback,repeat
With a numeric argument, FlightGear will exit after that number of repeats.
--generic=file,in,20,flight.out,playback,repeat,5
Moving Map Example:
Per Liedman has developed a moving map program called Atlas
(atlas.sourceforge.net) The initial inspiration and much code came
from Alexei Novikov.
The moving map supports NMEA format input either via network or
via serial port. Either way will work, but this example
demonstrates the use of a socket connection.
Start up fgfs with:
fgfs --nmea=socket,out,0.5,atas-host-name,5500,udp
Start up the Atlas program with:
Atlas --udp=5500 --fgroot=path-to-fg-root --glutfonts
Once both programs are running, the Atlas program should display
your current location. Atlas is a really nifty program with many
neat options such as the ability to generate and use background
bitmaps that show the terrain, cities, lakes, oceans, rivers, etc.
HTTP Server Example
You can now interact with a running copy of FlightGear using your
web browser. You can view all the key internal variables and even
change the ones that are writable. If you have support in your
favorite [scripting] language for interacting with an http server,
you should be able to use this as a mechanism to interface your
script with FlightGear.
Start up fgfs with the --httpd=<port#> option:
For example:
fgfs --httpd=5500
Now point your web browser to:
http://host.domain.name:5500/
When a value is displayed, you can click on it to bring up a form
to assign it a new value.
ACMS flight data recorder playback
fgfs --fdm=acms --generic=file,in,1,<path_to_replay_file>,acms

53
docs-mini/README.JSBSim Normal file
View File

@@ -0,0 +1,53 @@
JSBSim
JSBSim is an ongoing attempt at producing an OO Flight Dynamics Model
(FDM) to replace LaRCsim as the default FDM for FlightGear. It can
also be used standalone.
JSBSim uses config files to represent aircraft, engines, propellers,
etc. Also, the flight control system is described in the config
file. Normally, for use with FlightGear, the config files are named
this way [case is significant]:
<FG_ROOT>/Aircraft/<aircraft name>/<aircraft name>.xml
Engines are named like this:
<FG_ROOT>/Engines/<engine name>.xml
Aircraft and engine config files are present in the FGFS Base package
which must be downloaded. See the FlightGear web site for more
information.
How to run FGFS using JSBSim
All the various FDMs are currently compiled into FGFS. You can specify
which FDM you want at run time. You can also specify which aircraft
you want. Currently, for JSBSim only the X-15 and C-172 aircraft are
available. Here is an example command line used to start up FlightGear
using JSBSim as the FDM:
fgfs --fdm=jsb --aircraft=X15 --units-feet --altitude=60000 --uBody=2000 --wBody=120
or,
fgfs --fdm=jsb --aircraft=c172
[Note: uBody is the forward velocity of the aircraft, wBody is the
downward velocity - from the aircraft point of view. This essentially
means that the aircraft is going forward fast and has an angle of
attack of about 4 degrees or so]
The first command line sets up the initial velocity and altitude to
allow the X15 to glide down. Note that if you fire up the engine, it
will burn for only about two minutes and then run out of fuel - but
you will go very, very fast! The second command line example will
start up the C172 on the end of the runway.
Check out the JSBSim home page at http://jsbsim.sf.net. Please report
any bugs to jsb@hal-pc.org, or apeden@earthlink.net, or post on the
jsbsim web site using the SourceForge bug tracking system for the
project.
JSBSim is written by Jon S. Berndt and Tony Peden with contributions
by other FlightGear programmers, as well.

1
docs-mini/README.Joystick Normal file
View File

@@ -0,0 +1 @@
Replaced by Docs/README.Joystick.html in the base package.

26
docs-mini/README.Linux Normal file
View File

@@ -0,0 +1,26 @@
Installing FlightGear on Linux
==============================
Binary packages
---------------
Several major Linux distributions offer FlightGear binary packages in their
official repositories; this is usually the quickest and easiest way to
install FlightGear, but may not be the latest version.
There are also a number of unofficial repositories offering more frequently
updated binary packages (some including development versions, which have
the very latest features but are also more likely to have major bugs);
see http://www.flightgear.org/download/main-program/ for details.
Compiling from source
---------------------
See the general instructions (README.cmake in the directory above this).
You will need the -dev version of all the prerequisites,
e.g. libopenscenegraph-dev, libplib-dev.
Graphics drivers
----------------
If you experience unusably low frame rates (~1/sec), this may mean that your
graphics drivers do not support 3D acceleration, or that it is not enabled.
To check for this problem run:
glxinfo | grep render

24
docs-mini/README.SimGear Normal file
View File

@@ -0,0 +1,24 @@
21 February 2001 - CLO
As of version 0.7.2, FlightGear now requires the SimGear supporting
libraries to be installed before configuring and building FlightGear.
You must also have SimGear installed if you build the TerraGear
scenery creating tools (TerraGear is not required to run the
simulator).
You can get a copy of SimGear from the simgear web page:
http://www.simgear.org
SimGear build notes:
You should be able to just run the standard "./configure; make; make
install" to configure, build, and install SimGear. By default,
SimGear is installed in /usr/local/lib/libsg*.a and
/usr/local/include/simgear/.
You may specify an alternate prefix for building and installing
SimGear. If you do this, you may have to point the FlightGear
configure script to the correct location of SimGear. For instance, if
you installed SimGear in /usr/site/include and /usr/site/lib, you
could configure FlightGear with "./configure --with-simgear=/usr/site"

57
docs-mini/README.Unix Normal file
View File

@@ -0,0 +1,57 @@
If you are reading this in hopes that you will find the answer to a
specific question, please send the question to http://www.flightgear.org/~curt and
suggest that I include the answer here.
I. Compilers and Portability
============================
FlightGear is known to build with egcs-1.1 and higher, as well as
gcc-2.8 and higher. Your mileage may vary with earlier versions of
these compilers although support for gcc-2.7.x is mostly there.
For other platforms where you may have access to native compilers,
again your mileage may vary. We would like to support as many
different compilers and platforms as possible. Please relay any
changes you make (or problems you encounter) back to
http://www.flightgear.org/~curt, so that in the future we can better support your
platform and your compiler. I have access to a few different
platforms, but I must depend on others to make sure their favorite
platform and compiler is well supported.
II. OpenGL
==========
FlightGear requires accelerated OpenGL drivers to be properly
installed and configured on your system.
III. GLUT
=========
FlightGear requires GLUT version 3.7 or later (aka GameGLUT._ GLUT
needs to be installed on your system before you can build FlightGear.
GLUT can be found at:
http://reality.sgi.com/opengl/glut3/glut3.html
GLUT (pronounced like the glut in gluttony) is the OpenGL Utility
Toolkit, a window system independent toolkit for writing OpenGL
programs. It implements a simple windowing application programming
interface (API) for OpenGL. GLUT makes it considerably easier to learn
about and explore OpenGL programming. GLUT provides a portable API so
you can write a single OpenGL program that works on both Win32 PCs and
X11 workstations.
IV. Joystick Support
=====================
We use the plib joystick library for joystick support.
To make sure joystick support is included when building under Linux:
- make sure you have the proper joystick module installed.
- make sure the proper devices are created in /dev.
- /usr/include/linux/joystick.h must exist on your system.

169
docs-mini/README.canvas Normal file
View File

@@ -0,0 +1,169 @@
Canvas - A 2D Drawing API
=========================
Author: Thomas Geymayer <admin@tomprogs.at>
Revision: 2012/05/18
Introduction
------------
With the increasing complexity of (glass) cockpits the need for a simple API to
draw on a 2D surface without modifying the C++ core increased heavily in the
last time. The 2D canvas is an effort to satisfy this needs. It is now possible
to create offscreen rendertargets only by using the property tree and placing
them on any 3D object on the aircraft by using certain filter criteria.
Currently it is only possible to place text on the canvas but 2d shapes (using
OpenVG) are going to follow.
Creating a canvas
-----------------
A new canvas can be instantiated by creating a node /canvas/texture[<INDEX>]
with at least the following children:
<size n="0" type="int"> The width of the underlying texture
<size n="1" type="int"> The height of the underlying texture
<view n="0" type="int"> The width of the canvas
<view n="1" type="int"> The height of the canvas
The dimensions of the canvas are needed to be able to use textures with
different resolutions but use the same units for rendering to the canvas.
Therefore you can choose any texture size with the same canvas size and always
get the same results (apart from resolution dependent artifacts).
* Filtering:
Optionally you can enable mipmapping and/or multisampling (Coverage Sampling
Antialiasing):
<mipmapping type="bool"> Use mipmapping (default: false)
<coverage-samples type="int"> Coverage Samples (default: 0)
<color-samples type="int"> Color Samples (default: 0, always
have to be <= coverage-samples)
Drawing
-------
Drawing to the canvas is accomplished by creating nodes as childs of the
canvas root node. Every shape has to be a child of a <group> node. Currently
only drawing Text is possible:
* General:
The following parameters are used by multiple elements:
Color:
A color can be specified by the following subtree (NAME is replaced by
another name depending on the usage of the color)
<NAME>
<red type="float">
<green type="float">
<blue type="float">
<alpha type="float">
</NAME>
* Text:
Create a <text> node and configure with the following properties:
<text type="string"> The text to be displayed
<font type="string"> The font to be used (Searched in
1. aircraft-dir/Fonts
2. aircraft-dir
3. $FG_DATA/Fonts
4. Default osg font paths
<character-size type="float"> The font size (default: 32)
<character-aspect-ratio type="float"> Ratio between character height and width
(default: 1)
<tf> A 3x3 transformation matrix specified by 6 values
(child elements <m n="0">, ..., <m n="5"> which equal to a,
...,f used in the SVG standard) See
http://www.w3.org/TR/SVG/coords.html#TransformMatrixDefined
for details.
You can also use shortcuts and use an alternative to
specifying six values:
- Translation: <t n="0">, <t n="1"> (both default to 0)
- Rotation: <rot>
- Scale: <s n="0">, <s n="1"> (s[0] is required, s[1]
defaults to s[0])
<alginment type="string"> Text alignment (default: "left-baseline") One of:
"left-top"
"left-center"
"left-bottom"
"center-top"
"center-center"
"center-bottom"
"right-top"
"right-center"
"right-bottom"
"left-baseline"
"center-baseline"
"right-baseline"
"left-bottom-baseline"
"center-bottom-baseline"
"right-bottom-baseline"
<draw-mode type="int"> A bitwise combination of the following values
1 (Text - default)
2 (Boundingbox)
4 (Filled boundingbox)
8 (Alignment -> Draw a cross at the position
of the text)
<padding type="float"> Padding between for the boundingbox (default: 0)
<color> Text color
<color-fill> Fill color (for the bounding box)
Placement
---------
To place the canvas into the scene one ore more <placement> elements can be
added to the texture node. By setting at least on of the following nodes
the objects where the canvas texture should be placed on are selected:
<texture type="string"> Match objects with the given texture assigned
<node type="string"> Match objects with the given name
<parent type="string"> Match objects with a parent matching the given name
(Not necessarily the direct parent)
Example
-------
<canvas>
<texture>
<size n="0" type="int">384</size-x>
<size n="1" type="int">512</size-y>
<view n="0" type="int">768</view-width>
<view n="1" type="int">1024</view-height>
<mipmapping type="bool">false</mipmapping>
<coverage-samples type="int">0</coverage-samples>
<color-samples type="int">0</color-samples>
<color-background>
<red type="float">0</red>
<green type="float">0.02</green>
<blue type="float">0</blue>
<alpha type="float">1</alpha>
</color-background>
<group>
<text>
<text type="string">TEST MESSAGE</text>
<font type="string">helvetica_bold.txf</font>
<character-size type="float">40</character-size>
<tf>
<!-- Translate (18|50) -->
<tx>18</tx>
<ty>50</ty>
</tf>
</text>
</group>
<placement>
<!-- Place on objects with the texture EICAS.png
and a parent called HDD 1 -->
<texture type="string">EICAS.png</texture>
<parent type="string">HDD 1</parent>
</placement>
</texture>
</canvas>

317
docs-mini/README.commands Normal file
View File

@@ -0,0 +1,317 @@
FlightGear Commands Mini-HOWTO
David Megginson
Started: 2002-10-25
Last revised: 2007-12-01
In FlightGear, a *command* represents an action, while a *property*
represents a state. The trigger for a command can be any kind of user
input, including the keyboard, mouse, joystick, GUI, instrument panel,
or a remote network client.
XML Command Binding Markup
--------------------------
Most of the command-binding in FlightGear is handled through static
XML configuration files such as $FG_ROOT/keyboard.xml for the
keyboard, $FG_ROOT/mice.xml for the mouse, and
$FG_ROOT/gui/menubar.xml for the menubar. In all of these files, you
reference a command through a binding. This binding advances the
first throttle by 1%, up to a maximum value of 1.0:
<binding>
<command>property-adjust</command>
<property>/controls/throttle[0]</property>
<step type="double">0.01</step>
<max>1.0</max>
</binding>
A command binding always consists of the XML 'binding' element, with
one subelement named 'command' containing the command name (such as
'property-adjust'). All other subelements are named parameters to the
command: in this case, the parameters are 'property', 'step', and
'max'. Here is a simpler binding, with no parameters:
<binding>
<command>exit</command>
</binding>
Bindings always appear inside some other kind of markup, depending on
the input type. For example, here is the binding from keyboard.xml
that links the ESC key to the 'exit' command:
<key n="27">
<name>ESC</name>
<desc>Prompt and quit FlightGear.</desc>
<binding>
<command>exit</command>
</binding>
</key>
Usually, more than one binding is allowed for a single input trigger,
and bindings are executed in order from first to last. Bindings support
conditions (see README.conditions):
<key n="113">
<name>q</name>
<desc>Test</desc>
<binding>
<condition>
<property>/devices/status/mice/mouse/button[0]</property>
</condition>
<command>nasal</command>
<script>print("mouse button 0 pressed")</script>
</binding>
</key>
Keyboard definitions can embed bindings in tags <mod-up> (key released),
<mod-shift>, <mod-ctrl>, <mod-alt>, <mod-meta>, <mod-super>, and <mod-hyper>.
Nesting is supported. Meta, Super, and Hyper modifier tags are for local
use only, and must be supported by the operating system to work.
<key n="113">
<name>q</name>
<desc>Test</desc>
<binding>
<command>nasal</command>
<script>print("q pressed")</script>
</binding>
<mod-alt>
<binding>
<command>nasal</command>
<script>print("Alt-q pressed")</script>
</binding>
<mod-super>
<binding>
<command>nasal</command>
<script>print("Alt-Super-q pressed")</script>
</binding>
<mod-meta>
<binding>
<command>nasal</command>
<script>print("Alt-Super-Meta-q pressed")</script>
</binding>
</mod-meta>
</mod-super>
</mod-alt>
</key>
Built-in Commands
-----------------
As of the last revision date, the following commands were available
from inside FlightGear; the most commonly-used ones are the commands
that operate on property values (FlightGear's internal state):
null - do nothing
script - execute a PSL script
script: the PSL script to execute
exit - prompt and quit FlightGear
load - load properties from an XML file
file: the name of the file to load, relative to the current
directory (defaults to "fgfs.sav")
save - save properties to an XML file
file: the name of the file to save, relative to the current
directory (defaults to "fgfs.sav").
loadxml - load XML file into property tree
filename: the path & filename of the file to load
targetnode: the target node within the property tree where to store the XML
file's structure. If targetnode isn't defined, then the data will be stored
in a node "data" under the argument branch.
savexml - save property tree node to XML file
filename: the path & filename for the file to be saved
sourcenode: the source node within the property tree where the XML file's
structure is assembled from. If sourcenode isn't defined, then savexml will
try to save data stored in a node "data" in the argument branch.
panel-load - (re)load the 2D instrument panel
path: the path of the XML panel file, relative to $FG_ROOT (defaults
to the value of /sim/panel/path if specified, or
"Panels/Default/default.xml" as a last resort.
panel-mouse-click - pass a mouse click to the instrument panel
button: the number of the mouse button (0-based)
is-down: true if the button is down, false if it is up
x-pos: the x position of the mouse click
y-pos: the y position of the mouse click
preferences-load - (re)load preferences
path: the file name to load preferences from, relative to $FG_ROOT.
Defaults to "preferences.xml".
view-cycle - cycle to the next viewpoint
screen-capture - capture the screen to a file
tile-cache-reload - reload the scenery tile cache
lighting-update - update FlightGear's lighting
property-toggle - swap a property value between true and false
property: the name of the property to toggle
property-assign - assign a value to a property
property[0]: the name of the property that will get the new value.
value: the new value for the property; or
property[1]: the name of the property holding the new value.
property-adjust - adjust the value of a property
property: the name of the property to increment or decrement
step: the amount of the increment or decrement (defaults to 0)
offset: input offset distance (used for the mouse; multiplied by
factor)
factor: factor for multiplying offset distance (used for the mouse;
defaults to 1)
min: the minimum allowed value (default: no minimum)
max: the maximum allowed value (default: no maximum)
mask: 'integer' to apply only to the left of the decimal point;
'decimal' to apply only to the right of the decimal point; 'all'
to apply to the full value (defaults to 'all')
wrap: true if the value should be wrapped when it passes min or max;
both min and max must be specified (defaults to false)
property-multiply - multiply the value of a property
property: the name of the property to multiply
factor: the amount by which to multiply (defaults to 1.0)
min: the minimum allowed value (default: no minimum)
max: the maximum allowed value (default: no maximum)
mask: 'integer' to apply only to the left of the decimal point;
'decimal' to apply only to the right of the decimal point; 'all'
to apply to the full value (defaults to 'all')
wrap: true if the value should be wrapped when it passes min or max;
both min and max must be specified (defaults to false)
property-swap - swap the values of two properties
property[0]: the name of the first property
property[1]: the name of the second property
property-scale - set the value of a property based on an axis
property: the name of the property to set
setting: the current input setting (usually a joystick axis from -1
or 0 to 1)
offset: the offset to shift by, before applying the factor (defaults
to 0)
factor: the factor to multiply by (use negative to reverse; defaults
to 1.0)
squared: if true will square the resulting value (same as power=2)
power: the resulting value will be taken to the power of this integer
value (overrides squared; default=1)
property-cycle - cycle a property through a set of values
property: the name of the property to cycle
value[*]: all of the allowed values
dialog-new - create new dialog from the argument branch
dialog-show - show an XML-configured dialog box
dialog-name - the name of the dialog to show
dialog-close - close the active dialog box
dialog-update - copy values from FlightGear to the active dialog box
object-name: the name of the GUI object to update (defaults to all
objects)
dialog-apply - copy values from the active dialog box to FlightGear
object-name: the name of the GUI object to apply (defaults to all
objects)
presets-commit - commit preset values from /sim/presets
The following commands are temporary, and will soon disappear or be
renamed; do NOT rely on them:
old-save-dialog - offer to save a flight
old-load-dialog - offer to load a flight
old-reinit-dialog - offer to reinit FlightGear
old-hires-snapshot-dialog - save a hires screen shot
old-snapshot-dialog - save a screenshot
old-print-dialog - print the screen (Windows only)
old-pilot-offset-dialog - set pilot offsets graphically
old-hud-alpha-dialog - set the alpha value for the HUD
old-properties-dialog - display the property browser
old-preset-airport-dialog - set the default airport
old-preset-runway-dialog - set the default runway
old-preset-offset-distance-dialog - set the default offset distance
old-preset-altitude-dialog - set the default altitude
old-preset-glidescope-dialog - set the default glidescope
old-preset-airspeed-dialog - set the default airspeed
old-preset-commit-dialog - commit preset values
old-ap-add-waypoint-dialog - add a waypoint to the current route
old-ap-pop-waypoint-dialog - remove a waypoint from the current route
old-ap-clear-dialog - clear the current route
old-ap-adjust-dialog - adjust the autopilot settings
old-lat-lon-format-dialog - toggle the lat/lon format in the HUD
old-help-dialog - offer online help
Adding New Commands in C++
--------------------------
To add a new command to FlightGear, you first need to create a
function that takes a single SGPropertyNode const pointer as an
argument:
void
do_something (SGPropertyNode * arg)
{
something();
}
Next, you need to register it with the command manager:
globals->get_commands()->addCommand("something", do_something);
Now, the command "something" is available to any mouse, joystick,
panel, or keyboard bindings. If the bindings pass any arguments, they
will be children of the SGPropertyNode passed in:
void
do_something (const SGPropertyNode * arg)
{
something(arg->getStringValue("foo"), arg->getDoubleValue("bar"));
}
That's pretty-much it. Apologies in advance for not making things any
more complicated.

206
docs-mini/README.conditions Normal file
View File

@@ -0,0 +1,206 @@
CONDITIONS IN FLIGHTGEAR PROPERTY FILES
Written by David Megginson, david@megginson.com
Last modified: $Date$
This document is in the Public Domain and comes with NO WARRANTY!
1. Introduction
---------------
Some FlightGear property files contain conditions, affecting whether
bindings or animations are applied. For example, the following
binding will apply only when the /sim/input/selected/engine[0]
property is true:
<binding>
<condition>
<property>/sim/input/selected/engine[0]</property>
</condition>
<command>property-assign</command>
<property>/controls/starter[0]</property>
<value type="bool">true</value>
</binding>
Conditions always occur within a property subtree named "condition",
which is equivalent to an "and" condition.
2. Comparison Operators
-----------------------
The simplest condition is "property". It resolves as true when the
specified property has a boolean value of true (i.e. non-zero, etc.)
and false otherwise. Here is an example:
<condition>
<property>/sim/input/selected/engine[0]</property>
</condition>
For more sophisticated tests, you can use the "less-than",
"less-than-equals", "greater-than", "greater-than-equals", "equals",
and "not-equals" comparison operators. These all take two operands,
either two "property" operands or one "property" and one "value"
operand, and return true or false depending on the result of the
comparison. The value of the second operand is always forced to the
type of the first; for example, if you compare a string and a double,
the double will be forced to a string and lexically compared. If one
of the operands is a property, it is always assumed to be first. Here
is an example of a comparison that is true only if the RPM of the
engine is less than 1500:
<condition>
<less-than>
<property>/engines/engine[0]/rpm</property>
<value>1500</value>
</less-than>
</condition>
3. Boolean Operators
--------------------
Finally, there are the regular boolean operators "and", "or", and
"not". Each one surrounds a group of other conditions, and these can
be nested to arbitrary depths. Here is an example:
<condition>
<and>
<or>
<less-than>
<property>/engines/engine[0]/rpm</property>
<value>1500</value>
</less-than>
<greater-than>
<property>/engines/engine[0]/rpm</property>
<value>2500</value>
</greater-than>
<or>
<property>/engines/engine[0]/running</property>
</and>
</condition>
The top-level "condition" is an implicit "and".
4. Approximating if...else
--------------------------
There is no equivalent to the regular programming 'else' statement in
FlightGear conditions; instead, each condition separately must take
the others into account. For example, the equivalent of
if (x == 3) ... else if (y == 5) ... else ...
in FlightGear conditions is
<condition>
<equals>
<property>/x</property>
<value>3</value>
</equals>
<not>
<equals>
<property>/y</property>
<value>5</value>
</not>
</condition>
and then
<condition>
<equals>
<property>/y</property>
<value>5</value>
</equals>
<not>
<equals>
<property>/x</property>
<value>3</value>
</not>
</condition>
and then
<condition>
<not>
<equals>
<property>/x</property>
<value>3</value>
</equals>
</not>
<not>
<equals>
<property>/y</property>
<value>5</value>
</not>
</condition>
It's verbose, but it works nicely within existing property-based
formats and provides a lot of flexiblity.
5. Syntax Summary
-----------------
Here's a quick syntax summary:
* <and>...</and>
Contains one or more subconditions, all of which must be true.
* <condition>...</condition>
The top-level container for conditions, equivalent to an "and" group
* <equals>...</equals>
Contains two properties or a property and value, and is true if the
properties have equivalent values.
* <greater-than>...</greater-than>
Contains two properties or a property and a value, and is true if
the second property or the value has a value greater than the first
property.
* <greater-than-equals>...</greater-than-equals>
Contains two properties or a property and a value, and is true if
the second property or the value has a value greater than or equal
to the first property.
* <less-than>...</less-than>
Contains two properties or a property and a value, and is true if
the second property or the value has a value less than the first
property.
* <less-than-equals>...</less-than-equals>
Contains two properties or a property and a value, and is true if
the second property or the value has a value less than or equal
to the first property.
* <not>...</not>
Contains one subcondition, which must not be true.
* <not-equals>...</not-equals>
Contains two properties or a property and value, and is true if the
properties do not have equivalent values.
* <or>...</or>
Contains one or more subconditions, at least one of which must be
true.
* <property>...</property>
The name of a property to test.
* <value>...</value>
A literal value in a comparison.

449
docs-mini/README.digitalfilters Normal file
View File

@@ -0,0 +1,449 @@
NOTE:
This manual may contain outdated information. For documentation of the most recent features
refer to
http://wiki.flightgear.org/index.php/Howto:_Design_an_autopilot
http://wiki.flightgear.org/index.php/Autopilot_Configuration_Reference
COMMON SETTINGS
==============================================================================
Currently four types of digital filter implementations are supported. They all serve an
individual purpose or are individual implementations of a specific filter type.
Each filter implementation uses the same set of basic configuration tags and individual
configuration elements. These individual elements are described in the section of the
filter.
The InputValue
==============================================================================
Each filter has several driving values, like the input value itself, sometimes a reference
value, a gain value and others. Most of these input values can bei either a constant value
or the value of a property. They all use the same syntax and will be referred to as InputValue
in the remaining document.
The complete XML syntax for a InputValue is
<some-element>
<condition>
<!-- any condition as defined in README.conditions -->
</condition>
<property>/some/property/name</property>
<value>0.0</value>
<scale>1.0</value>
<offset>0.0</offset>
<max>infinity</max>
<min>-infinity<min>
<abs>false</abs>
<period>
<min>-180.0</min>
<max>-180.0</max>
</period>
</some-element>
The enclosing element <some-element> is the element defined in each filter, like <input>, <u_min>,
<reference> etc. These elements will be described later.
The value of the input is calculated based on the given value, scale and offset as
value * scale + offset
and the result is clipped to min/max, if given.
With the full set of given elements, the InputValue will initialize the named property to the value
given, reduced by the given offset and reverse scaled by the given scale.
Example:
<input>
<property>/controls/flight/rudder</property>
<value>0.0</value>
<scale>0.5</scale>
<offset>0.5</offset>
</input>
Will use the property /controls/flight/rudder as the input of the filter. The property will be initialized
at a value of zero and since the property usually is in the range [-1..+1], the the value of <input> will
be in the range (-1)*0.5+0.5 to (+1)*0.5+0.5 which is [0..1].
The default values for elements not given are:
<value/> : 0.0
<scale/> : 1.0
<offset/>: 0.0
<property/> : none
<min/> : unclipped
<max/> : unclipped
<abs/> : false
Some examples:
<input>
<property>/position/altitude-ft</property>
<scale>0.3048</scale>
</input>
Gives the altitude in meters. No initialization of the property is performed, no offset applied.
<reference>
<value>0.0</value>
</reference>
A constant reference of zero.
A abbreviated method of defining values exist for using a just constant or a property. The above
example may be written as
<reference>0.0</reference>
Or if the reference is defined in a property
<reference>/some/property/name</reference>
No initialization, scaling or offsetting is performed here.
The logic behind this is: If the text node in the element (the text between the opening and closing tag)
can be converted to a double value, it will be interpreted as a double value. Otherwise the text will
be interpreted as a property name.
Examples:
<reference>3.1415927</reference> - The constant of PI (roughly)
<reference>/position/altitude-ft</reference> - The property /position/altitude-ft
<reference>3kings</reference> - The constant 3. The word kings is ignored
<reference>food4less</reference> - The property food4less
The <property> element may also be written as <prop> for backward compatibility.
There may be one or more InputValues for the same input of a filter which may be bound to conditions.
Each InputValue will have its condition checked in the order of InputValues given in the configuration
file. The first InputValue that returns true for its condition will be evaluated. Chaining a number
of InputValues with conditions and an unconditioned InputValue works like the C language equivalent
if( condition ) {
// compute value of first element
} else if( condition2 ) {
// compute value of second element
} else if( condition3 ) {
// compute value of third element
} else {
// compute value of last element
}
Example: Set the gain to 3.0 if /autopilot/locks/heading equals dg-heading-hold or 2.0 otherwise.
<digital-filter>
<gain>
<condition>
<equals>
<property>/autopilot/locks/heading</property>
<value>dg-heading-hold</value>
</equals>
</condition>
<value>3.0</value>
<gain>
<!-- Hint: omit a condition here as a fallthru else condition -->
</gain>
<value>2.0</value>
<gain>
<digital-filter>
If the element <abs> is used and set to the value "true", only the absolute value of the input
(the positive part) is used for further computations. The abs function is applied after all
other computations are completed.
OutputValue
==============================================================================
Each filter drives one to many output properties. No scaling or offsetting is implemented
for the output value, these should be done in the filter itself.
The output properties are defined in the <output/> element by adding <property/> elements
within the <output/> element. For just a single output property, the <property/> element
may be ommited. For backward compatibility, <property/> may be replaced by <prop/>.
Nonexisting properties will be created with type double.
Example: (Multiple output properties)
<output>
<property>/some/output/property</property>
<property>/some/other/output/property</property>
<property>/and/another/output/property</property>
</output>
Example: a single output property
<output>/just/a/single/property</output>
Other Common Settings
==============================================================================
<name> String The name of the filter. Used for debug purpose.
Example:
<name>pressure rate filter</name>
<debug> Boolean If true, this filter puts out debug information when updated.
Example:
<debug>false</debug>
<input> InputValue The input property driving the filter.
Refer to InputValue for details.
<reference> InputValue The reference property for filter that need one.
Refer to InputValue for details.
<output> Complex Each filter can drive one to many output properties.
Refer to OutputValue for details.
<u_min> InputValue This defines the optional minimum and maximum value the output
<u_max> is clamped to. If neither <u_min> nor <u_max> exists, the output
is only limited by the internal limit of double precision float computation.
If either <u_min> or <u_max> is given, clamping is activated. A missing
min or max value defaults to 0 (zero).
Note: <u_min> and <u_max> may also occour within a <config> element.
<min> and <max> may be used as a substitude for the corresponding u_xxx element.
<period> Complex Define a periodical input or output value. The phase width is defined by the
child elements <min> and <max> which are of type InputValue
Example: Limit the pilot's body temperature to a constant minimum of 36 and a maximum defined in
/pilots/max-body-temperature-degc, initialized to 40.0
<u_max>
<prop>/pilots/max-body-temperature-degc</prop>
<value>40.0</
</u_max>
<min>
<value>36.0</value>
</min
Implicit definition of the minimum value of 0 (zero) and defining a maximum of 100.0
<config>
<u_max>100.0</u_max>
</config>
This defines the input or output as a periodic value with a phase width of 360, like
the compass rose. Any value reaching the filter's input or leaving the filter at the
output will be transformed to fit into the given range by adding or substracting one phase
width of 360. Values of -270, 90 or 450 applied to this periodical element will allways
result in +90. A value of 630, 270 or -90 will be normalized to -90 in the given example.
<period>
<min>-180.0</min>
<max>180.0</max>
</period>
<enable> Complex Define a condition to enable or disable the filter. For disabled
filters, no output computations are performed. Only enabled
filters fill the output properties. The default for undefined
conditions is enabled.
Several way exist to define a condition. The most simple case
is checking a boolean property. For this, just a <prop> element
naming this boolean property is needed. The boolean value of the
named property defines the enabled state of the filter.
To compare the value of a property with a constant, a <prop> and
a <value> element define the property name and the value to be
compared. The filter is enabled, if the value of the property
equals the given value. A case sensitive string compare is
performed here.
To define more complex conditions, a <condition> element may be
used to define any condition described in README.conditions.
If a <condition> element is present and if it contains a valid
condition, this conditions has precedence over a given <prop>/
<value> condition.
The child element <honor-passive>, a boolean flag, may be present
within the <enable> element. If this element is true, the property
/autopilot/locks/passive-mode is checked and if it is true, the
filter output is computed, but the output properties are not set.
The default for honor-passive is false
Example: Check a boolean property, only compute this filter if gear-down is true and
/autopilot/locks/passive-mode is false
<enable>
<prop>/gear/gear-down</prop>
<honor-passive>true</honor-passive>
</enable>
Check a property for equality, only compute this filter if the autopilot is locked in heading mode.
<enable>
<prop>/autopilot/locks/heading</prop>
<value>dg-heading-hold</value>
</enable>
Use a complex condition, only compute this filter if the autopilot is serviceable and the lock
is either dg-heading-hold or nav1-heading-hold
<enable>
<condition>
<property>/autopilo/serviceable</property>
<or>
<equals>
<property>/autopilot/locks/heading</property>
<value>dg-heading-hold</value>
</equals>
<equals>
<property>/autopilot/locks/heading</property>
<value>nav1-heading-hold</value>
</equals>
</or>
</condition>
</enable>
INDIVIDUAL FILTER CONFIGURATION
==============================================================================
Digital Filter
Six different types of digital filter can be configured inside the autopilot
configuration file. There are four low-pass filter types and two gain filter
types.
The low-pass filter types are:
* Exponential
* Double exponential
* Moving average
* Noise spike filter
The gain filter types are:
* gain
* reciprocal
To add a digital filter, place a <filter> element under the root element. Next to
the global configuration elements described above, the following elements configure
the digital filter:
<filter-time> InputValue This tag is only applicable for the exponential and
double-exponential filter types. It controls the bandwidth
of the filter. The bandwidth in Hz of the filter is:
1/filter-time. So a low-pass filter with a bandwidth of
10Hz would have a filter time of 1/10 = 0.1
<samples> InputValue This tag only makes sense for the moving-average filter.
It says how many past samples to average.
<max-rate-of-change>
InputValue This tag is applicable for the noise-spike filter.
It says how much the value is allowed to change per second.
<gain> InputValue This is only applicable to the gain and reciprocal filter types.
The output for gain filter is computed as input*gain while
the reciprocal filter computes output as gain/input for input
values != 0 (zero). Gain may be a constant, a property name
defined by a <prop> element within the <gain> element or a
property name initialized to a value by using a <prop> and
<value> element.
Example: a pressure-rate-filter implemented as a double exponential low pass filter
with a bandwith of 10Hz
<filter>
<name>pressure-rate-filter</name>
<debug>false</debug>
<type>double-exponential</type>
<enable>
<prop>/autopilot/locks/pressure-rate-filter</prop>
<value>true</value>
</enable>
<input>/autopilot/internal/pressure-rate</input>
<output>/autopilot/internal/filtered-pressure-rate</output>
<filter-time>0.1</filter-time>
</filter>
This will filter the pressure-rate property. The output will be to a new
property called filtered-pressure-rate. You can select any numerical property
from the property tree. The input property will not be affected by the filter,
it will stay the same as it would if no filter was configured.
Example 2:
<filter>
<name>airspeed elevator-trim gain reciprocal filter</name>
<debug>false</debug>
<enable>
<prop>/autopilot/locks/airspeed-elevator-trim-gain</prop>
<value>true</value>
</enable>
<type>reciprocal</type>
<gain>
<prop>/autopilot/settings/elevator-trim-airspeed-reciprocal-gain</prop>
<value>7</value>
</gain>
<input>/velocities/airspeed-kt</input>
<output>/autopilot/internal/elevator-trim-gain</output>
<u_min>0.005</u_min>
<u_max>0.02</u_max>
</filter>
This will use the /velocities/airspeed-kt property to produce a gain factor
that reduces as airspeed increases. At airspeeds up to 350kt the gain will
be clamped to 0.02, at 700kt the gain will be 0.01 and at 1400kt the gain will
be 0.005. The gain will be clamped to 0.005 for airspeeds > 1400kt.
The output from this filter could then be used to control the gain in a PID
controller:
<pid-controller>
<name>Pitch hold</name>
<debug>false</debug>
<enable>
<prop>/autopilot/locks/pitch</prop>
<value>true</value>
</enable>
<input>
<prop>/orientation/pitch-deg</prop>
</input>
<reference>
<prop>/autopilot/settings/target-pitch-deg</prop>
</reference>
<output>
<prop>/autopilot/internal/target-elevator-trim-norm</prop>
</output>
<config>
<Ts>0.05</Ts>
<Kp>
<prop>/autopilot/internal/elevator-trim-gain</prop>
<value>0.02</value>
</Kp>
<beta>1.0</beta>
<alpha>0.1</alpha>
<gamma>0.0</gamma>
<Ti>2.0</Ti>
<Td>0.2</Td>
<u_min>-1.0</u_min>
<u_max>1.0</u_max>
</config>
</pid-controller>
IMPORTANT NOTE: The <Kp> tag in PID controllers has been revised to operate in
the same way as the <gain> elements in filters. However, the original format
of <Kp> will continue to function as before i.e. <Kp>0.02</Kp> will specify a
fixed and unalterable gain factor, but a warning message will be output.
The gain type filter is similar to the reciprocal filter except that the gain
is applied as a simple factor to the input.
-------------------------------------------------------------------------------
Parameters
<name> The name of the filter. Give it a sensible name!
<debug> If this tag is set to true debugging info will be printed on the
console.
<enable> Encloses the <prop> and <value> tags which are used to enable or
disable the filter. Instead of the <prop> and <value> tags, a <condition>
tag may be used to define a condition. Check README.conditions for more
details about conditions. Defaults to enabled if unspecified.
<type> The type of filter. This can be exponential, double-exponential,
moving-average, noise-spike, gain or reciprocal.
<input> The input property to be filtered. This should of course be a
numerical property, filtering a text string or a boolean value does not make
sense.
<output> The filtered value. You can make up any new property.
<u_min> The minimum output value from the filter. Defaults to -infinity.
<u_max> The maximum output value from the filter. Defaults to +infinity.
These are the tags that are applicable to all filter types. The following tags
are filter specific.
<filter-time> This tag is only applicable for the exponential and
double-exponential filter types. It controls the bandwidth of the filter. The
bandwidth in Hz of the filter is: 1/filter-time. So a low-pass filter with a
bandwidth of 10Hz would have a filter time of 1/10 = 0.1
<samples> This tag only makes sense for the moving-average filter. It says how
many past samples to average.
<max-rate-of-change> This tag is applicable for the noise-spike filter. Is
says how much the value is allowed to change per second.
<gain> This, and it's enclosed <prop> and <value> tags, are only applicable to
the gain and reciprocal filter types. The <prop> tag specifies a property node
to hold the gain value and the <value> tag specifies an initial default value.
The gain defaults to 1.0 if unspecified.
The output from the gain filter type is: input * gain.
The output from the reciprocal filter type is: gain / input.
The gain can be changed during run-time by updating the value in the property
node.
<startup-current> If true, internal state is initialised with the current error
value, which can reduce startup oscillations. Otherwise if false (the default),
internal state is initialised to zero.

360
docs-mini/README.effects Normal file
View File

@@ -0,0 +1,360 @@
Effects
-------
Effects describe the graphical appearance of 3d objects and scenery in
FlightGear. The main motivation for effects is to support OpenGL
shaders and to provide different implementations for graphics hardware
of varying capabilities. Effects are similar to DirectX effects files
and Ogre3D material scripts.
An effect is a property list. The property list syntax is extended
with new "vec3d" and "vec4d" types to support common computer graphics
values. Effects are read from files with a ".eff" extension or can be
created on-the-fly by FlightGear at runtime. An effect consists of a
"parameters" section followed by "technique" descriptions. The
"parameters" section is a tree of values that describe, abstractly,
the graphical characteristics of objects that use the effect. Techniques
refer to these parameters and use them to set OpenGL state or to set
parameters for shader programs. The names of properties in the
parameter section can be whatever the effects author chooses, although
some standard parameters are set by FlightGear itself. On the other
hand, the properties in the techniques section are all defined by the
FlightGear.
Techniques
----------
A technique can contain a predicate that describes the OpenGL
functionality required to support the technique. The first
technique with a valid predicate in the list of techniques is used
to set up the graphics state of the effect. A technique with no
predicate is always assumed to be valid. The predicate is written in a
little expression language that supports the following primitives:
and, or, equal, less, less-equal
glversion - returns the version number of OpenGL
extension-supported - returns true if an OpenGL extension is supported
property - returns the boolean value of a property
float-property - returns the float value of a property, useful inside equal, less or less-equal nodes
shader-language - returns the version of GLSL supported, or 0 if there is none.
The proper way to test whether to enable a shader-based technique is:
<predicate>
<and>
<property>/sim/rendering/shader-effects</property>
<less-equal>
<value type="float">1.0</value>
<shader-language/>
</less-equal>
</and>
</predicate>
There is also a property set by the user to indicate what is the level
of quality desired. This level of quality can be checked in the predicate
like this :
<predicate>
<and>
<property>/sim/rendering/shader-effects</property>
<less-equal>
<value type="float">2.0</value>
<float-property>/sim/rendering/quality-level</float-property>
</less-equal>
<!-- other predicate conditions -->
</and>
</predicate>
The range of /sim/rendering/quality-level is [0..5]
* 2.0 is the threshold for relief mapping effects,
* 4.0 is the threshold for geometry shader usage.
A technique can consist of several passes. A pass is basically an Open
Scene Graph StateSet. Ultimately all OpenGL and OSG modes and state
attributes will be accessable in techniques. State attributes -- that
is, technique properties that have children and are not just boolean
modes -- have an <active> parameter which enables or disables the
attribute. In this way a technique can declare parameters it needs,
but not enable the attribute at all if it is not needed; the decision
can be based on a parameter in the parameters section of the
effect. For example, effects that support transparent and opaque
geometry could have as part of a technique:
<blend>
<active><use>blend/active</use></active>
<source>src-alpha</source>
<destination>one-minus-src-alpha</destination>
</blend>
So if the blend/active parameter is true blending will be activated
using the usual blending equation; otherwise blending is disabled.
Values of Technique Attributes
------------------------------
Values are assigned to technique properties in several ways:
* They can appear directly in the techniques section as a
constant. For example:
<uniform>
<name>ColorsTex</name>
<type>sampler-1d</type>
<value type="int">2</value>
</uniform>
* The name of a property in the parameters section can be
referenced using a "use" clause. For example, in the technique
section:
<material>
<ambient><use>material/ambient</use></ambient>
</material>
Then, in the parameters section of the effect:
<parameters>
<material>
<ambient type="vec4d">0.2 0.2 0.2 1.0</ambient>
</material>
</parameters>
It's worth pointing out that the "material" property in a
technique specifies part of OpenGL's state, whereas "material"
in the parameters section is just a name, part of a
hierarchical namespace.
* A property in the parameters section doesn't need to contain
a constant value; it can also contain a "use" property. Here
the value of the use clause is the name of a node in an
external property tree which will be used as the source of a
value. If the name begins with '/', the node is in
FlightGear's global property tree; otherwise, it is in a local
property tree, usually belonging to a model [NOT IMPLEMENTED
YET]. For example:
<parameters>
<chrome-light><use>/rendering/scene/chrome-light</use></chrome-light>
</parameters>
The type is determined by what is expected by the technique
attribute that will ultimately receive the value. [There is
no way to get vector values out of the main property system
yet; this will be fixed shortly.] Values that are declared
this way are dynamically updated if the property node
changes.
OpenGL Attributes
-----------------
The following attributes are currently implemented in techiques:
alpha-test - children: active, comparison, reference
Valid values for comparision:
never, less, equal, lequal, greater, notequal, gequal,
always
blend - children: active, source, destination, source-rgb,
source-alpha, destination-rgb, destination-alpha
Each operand can have the following values:
dst-alpha, dst-color, one, one-minus-dst-alpha,
one-minus-dst-color, one-minus-src-alpha,
one-minus-src-color, src-alpha, src-alpha-saturate,
src-color, constant-color, one-minus-constant-color,
constant-alpha, one-minus-constant-alpha, zero
cull-face - front, back, front-back
lighting - true, false
material - children: active, ambient, ambient-front, ambient-back, diffuse,
diffuse-front, diffuse-back, specular, specular-front,
specular-back, emissive, emissive-front, emissive-back, shininess,
shininess-front, shininess-back, color-mode
polygon-mode - children: front, back
Valid values:
fill, line, point
program
vertex-shader
geometry-shader
fragment-shader
attribute
geometry-vertices-out: integer, max number of vertices emitted by geometry shader
geometry-input-type - points, lines, lines-adjacency, triangles, triangles-adjacency
geometry-output-type - points, line-strip, triangle-strip
render-bin - (OSG) children: bin-number, bin-name
rendering-hint - (OSG) opaque, transparent
shade-model - flat, smooth
texture-unit - has several child properties:
unit - The number of an OpenGL texture unit
type - This is either an OpenGL texture type or the name of a
builtin texture. Currently supported OpenGL types are 1d, 2d,
3d which have the following common parameters:
image (file name)
filter
mag-filter
wrap-s
wrap-t
wrap-r
mipmap-control - controls how the mipmap levels are computed.
Each color channel can be computed with different functions
among average, sum, product, min and max. For example :
<function-r>average</function-r>
<function-a>min</function-a>
function-r - function for red
function-g - function for green
function-b - function for blue
function-a - function for alpha
The following built-in types are supported:
white - 1 pixel white texture
noise - a 3d noise texture
environment
mode
color
uniform
name
type - float, float-vec3, float-vec4, sampler-1d, sampler-2d,
sampler-3d
vertex-program-two-side - true, false
vertex-program-point-size - true, false
Inheritance
-----------
One feature not fully illustrated in the sample below is that
effects can inherit from each other. The parent effect is listed in
the "inherits-from" form. The child effect's property tree is
overlaid over that of the parent. Nodes that have the same name and
property index -- set by the "n=" attribute in the property tag --
are recursively merged. Leaf property nodes from the child have
precedence. This means that effects that inherit from the example
effect below could be very short, listing just new
parameters and adding nothing to the techniques section;
alternatively, a technique could be altered or customized in a
child, listing (for example) a different shader program. An example
showing inheritance Effects/crop.eff, which inherits some if its
values from Effects/terrain-default.eff.
FlightGear directly uses effects inheritance to assign effects to 3D
models and terrain. As described below, at runtime small effects are
created that contain material and texture values in a "parameters"
section. These effects inherit from another effect which references
those parameters in its "techniques" section. The derived effect
overrides any default values that might be in the base effect's
parameters section.
Generate
--------
Often shader effects need tangent vectors to work properly. These
tangent vectors, usually called tangent and binormal, are computed
on the CPU and given to the shader as vertex attributes. These
vectors are computed on demand on the geometry using the effect if
the 'generate' clause is present in the effect file. Exemple :
<generate>
<tangent type="int">6</tangent>
<binormal type="int">7</binormal>
<normal type="int">8</normal>
</generate>
Valid subnodes of 'generate' are 'tangent', 'binormal' or 'normal'.
The integer value of these subnode is the index of the attribute
that will hold the value of the vec3 vector.
The generate clause is located under PropertyList in the xml file.
In order to be available for the vertex shader, these data should
be bound to an attribute in the program clause, like this :
<program>
<vertex-shader>my_vertex_shader</vertex-shader>
<attribute>
<name>my_tangent_attribute</name>
<index>6</index>
</attribute>
<attribute>
<name>my_binormal_attribute</name>
<index>7</index>
</attribute>
</program>
attribute names are whatever the shader use. The index is the one
declared in the 'generate' clause. So because generate/tangent has
value 6 and my_tangent_attribute has index 6, my_tangent_attribute
holds the tangent value for the vertex.
Default Effects in Terrain Materials and Models
-----------------------------------------------
Effects for terrain work in this way: for each material type in
materials.xml an effect is created that inherits from a single default
terrain effect, Effects/terrain-default.eff. The parameters section of
the effect is filled in using the ambient, diffuse, specular,
emissive, shininess, and transparent fields of the material. The
parameters image, filter, wrap-s, and wrap-t are also initialized from
the material xml. Seperate effects are created for each texture
variant of a material.
Model effects are created by walking the OpenSceneGraph scene graph
for a model and replacing nodes (osg::Geode) that have state sets with
node that uses an effect instead. Again, a small effect is created
with parameters extracted from OSG objects; this effect inherits, by
default, from Effects/model-default.eff. A larger set of parameters is
created for model effects than for terrain because there is more
variation possible from the OSG model loaders than from the terrain
system. The parameters created are:
* material active, ambient, diffuse, specular, emissive,
shininess, color mode
* blend active, source, destination
* shade-model
* cull-face
* rendering-hint
* texture type, image, filter, wrap-s, wrap-t
Specifying Custom Effects
-------------------------
You can specify the effects that will be used by FlightGear as the
base effect when it creates terrain and model effects.
In the terrain materials.xml, an "effect" property specifies the name
of the model to use.
In model .xml files, A richer syntax is supported. [TO BE DETERMINED]
Material animations will be implemented by creating a new effect
that inherits from one in a model, overriding the parameters that
will be animated.
Examples
--------
The Effects directory contains the effects definitions; look there for
examples. Effects/crop.eff is a good example of a complex effect.
Application
-----------
To apply an effect to a model or part of a model use:
<effect>
<inherits-from>Effects/light-cone</inherits-from>
<object-name>Cone</object-name>
</effect>
where <inherits-from> </inherits-from> contains the path to the effect you want to apply.
The effect does not need the file extension.
NOTE:
Chrome, although now implemented as an effect, still retains the old method of application:
<animation>
<type>shader</type>
<shader>chrome</shader>
<texture>glass_shader.png</texture>
<object-name>windscreen</object-name>
</animation>
in order to maintain backward compatibility.

214
docs-mini/README.electrical Normal file
View File

@@ -0,0 +1,214 @@
Specifying and Configuring and Aircraft Electrical System
=========================================================
Written by Curtis L. Olson <http://www.flightgear.org/~curt>
February 3, 2003 - Initial revision.
June 14, 2005 - Important update
UPDATE - June 14, 2005
======================
The xml data driven electrical system described in this document has
severe flaws and is (or should be) obsolete. It is still supported
for backwards compatibility, but new electrical systems should not be
modeled with this system. Instead you should make a procedural
electrical system model using nasal, or wait for a better data driven
electrical system model to be developed "some time" in the future.
Currently the old/depricated electrical system has been made into a
proper subsystem. Most aircraft will load the default "systems"
configuration via the "/sim/systems/path" property which is set in the
top level preferences.xml file and which defaults to a value of
"Aircraft/Generic/generic-systems.xml". The generic-systems.xml file
in turn specifies an electrical system based on the old/obsolete
system. The default electrical system configuration file named in
"generic-systems.xml" is "generic-electrical.xml". This mechanism
provides a generic electrical system to any aircraft that doesn't
define their own electrical system. Also note that you can still
specify a path to an "old" xml config file using
"/sim/systems/electrical" in your aircraft-set.xml file. This is
again for backwards compatibility.
What follows here is a description of the "old" "depricated"
"obsolete" electrical system.
Introduction
============
The FlightGear electrical system model is a simplification of reality.
We don't model down to the level of individual electrons, but we do
try to model a rich enough subset of components so that a realistic
electrical system may be implemented (at least from the pilot's
perspective.) We try to model enough of the general flow so that
typical electrical system failures can be implimented and so that the
pilot can practice realistic troubleshooting techniques and learn the
basic structure and relationships of the real aircraft electrical
system.
The FlightGear electrical system is essentially a directed graph built
of 4 major components: suppliers, buses, outputs, and connectors.
Suppliers are the power sources such as batteries and alternators.
Buses collect input from multiple suppliers and feed multiple outputs.
Outputs are not strictly necessary, but are included so we can assign
current draws, and name generic output types, as well as provide a
consistent naming scheme to other FlightGear subsystems. Finally
connectors connect a supplier to a bus, or a bus to an output, and
optionally can specify a switch property (either a physical switch or
a circuit breaker.)
At run time, FlightGear parses the electrical system config file and
builds a directed graph (in the computer science sense.). Each time
step, the current is propagated forward through the system, starting
at the suppliers, flowing through the buses, and finally to the
outputs. The system follows the path specified by connectors and
honors the state of any connector switches.
FlightGear uses a depth first recursive decent algorithm to propagate
the current through the system. As the recursive calls complete, the
current draw of the "leaf nodes" can be summed up and back-propagated
through the system. This allows us to compute the total downstream
current draw at each component of the system. This allows us to
discharge the battery based on actual loads, and allows us to build an
accurate functioning ammeter model.
Suppliers
=========
A supplier entry could look like the following:
<supplier>
<name>Battery 1</name>
<prop>/systems/electrical/suppliers/battery[0]</prop>
<kind>battery</kind>
<volts>24</volts>
<amps>60</amps> <!-- WAG -->
</supplier>
<name> can be anything you choose to call this entry.
<prop> is the name of a property that will be updated with the state
of this supplier.
<kind> can be "battery", "alternator", or "external".
<volts> specifies the volts of the source
<amps> specifies the amps of the source
Currently <volts> and <amps> are not really modeled in detail. This
is more of a place holder for the future.
For alternators, you must additionally specify:
<rpm-source>/engines/engine[0]/rpm</rpm-source>
The value of the rpm source determines if the generator is able to
produce power or not.
Buses
=====
A bus entry could look like the following:
<bus>
<name>Essential/Cross Feed Bus</name>
<prop>/systems/electrical/outputs/bus-essential</prop>
<prop>/systems/electrical/outputs/annunciators</prop>
<prop>/systems/electrical/outputs/master-switch</prop>
</bus>
<name> is whatever you choose to call this bus
You can have an arbitrary number of <prop> entries. Each entry is the
name of a property that will be updated with the value of the current
at that bus. This allows you to wire devices directly to the bus but
does not allow you to insert a switch or circuit breaker in between.
See "Outputs" and "Connectors" if you want to do that.
Outputs
=======
An output entry could look like the following:
<output>
<name>Starter 1 Power</name>
<prop>/systems/electrical/outputs/starter[0]</prop>
</output>
An output isn't entirely unlike a bus, but it's nice conceptually to
have a separate entity type. This enables us to specify a common set
of output property names so that other subsystems can automatically
work with any electrical system that follows the same conventions. An
output lives on the other side of a switch, so this is how you can
wire in cockpit switches to model things like fuel pump power,
avionics master switch, or any other switch on the panel.
<name> is whatever you choose to call this bus
You can have an arbitrary number of <prop> entries. Each entry is the
name of a property that will be updated with the value of the current
at that bus. This allows you to wire devices directly to the bus but
does not allow you to insert a switch or circuit breaker in between.
See "Outputs" and "Connectors" if you want to do that.
Other FlightGear subsystems can monitor the property name associated
with the various outputs to decide how to render an instrument,
whether to run the fuel pump, whether to spin a gyro, or any other
subsystem that cares about electrical power.
Connectors
==========
An connector entry could look like the following:
<connector>
<input>Alternator 1</input>
<output>Virtual Bus 1</output>
<switch>/controls/switches/master-alt</switch>
<initial-state>off</initial-state> <!-- optional tag -->
</connector>
A connector specifies and input, and output, and any number of
switches that are wired in series. In other words, all switches need
to be true/on in order for current to get from the input to the output
of the connector.
<input> specifies the <name> of the input. Typically you would
specify a "supplier" or a "bus".
<output> specifies the <name> of the output. Typically you would
specify a bus or an output.
You can have an arbitrary number of <switch> entries. The switches
are wired in series so all of them need to be on (i.e. true) in order
for current to pass to the output.
Note: by default the system forces any listed switches to be true.
The assumption is that not every aircraft or cockpit may impliment
every available switch, so rather than having systems be switched off,
with no way to turn them on, we default to switched on.
This is a problem however with the starter switch which we want to be
initialized to "off". To solve this problem you can specify
<initial-state>off</initial-state> or
<initial-state>on</initial-state> Switches default to on, so you
really only need to specify this tag if you want the connector's
switch to default to off.
Summary
=======
The electrical system has a lot of power and flexibility to model a
variety of electrical systems. However, it is hopelessly flawed and
cannot model a lot of more complex electrical behavior needed for the
advanced electrical systems found on larger and more complex aircraft.
Please consider writing a procedural model for your electrical system
in nasal or wait for a better data driven electrical system model to
be developed. If you know something about electrical systems, please
volunteer to write a better data driven model! :-)

91
docs-mini/README.extensions Normal file
View File

@@ -0,0 +1,91 @@
Using Extensions
----------------
To use an OpenGL extension in the code is is necessary to include a refference
to the extensions.hxx header file and add the following to the code (as an
example):
/* global variables */
glPointParameterfProc glPointParameterfPtr = 0;
glPointParameterfvProc glPointParameterfvPtr = 0;
bool glPointParameterIsSupported = false;
To be able to use these extensions the functions pointers have to be initialized
by something like the following examplde code:
if (SGIsOpenGLExtensionSupported("GL_EXT_point_parameters") )
{
glPointParameterIsSupported = true;
glPointParameterfPtr = (glPointParameterfProc)
SGLookupFunction("glPointParameterfEXT");
glPointParameterfvPtr = (glPointParameterfvProc)
SGLookupFunction("glPointParameterfvEXT");
} else if ( SGIsOpenGLExtensionSupported("GL_ARB_point_parameters") ) {
glPointParameterIsSupported = true;
glPointParameterfPtr = (glPointParameterfProc)
SGLookupFunction("glPointParameterfARB");
glPointParameterfvPtr = (glPointParameterfvProc)
SGLookupFunction("glPointParameterfvARB");
} else
glPointParameterIsSupported = false;
If a function is supported the function pointers are now initialized.
When using the functions (note that glPointParameterfvPtr() is used instead of
glPointParameterfvEXT() )it is important to check whether the
glPointParameterIsSupported is set to true:
if ( distance_attenuation && glPointParameterIsSupported )
{
// Enable states for drawing points with GL_extension
glEnable(GL_POINT_SMOOTH);
float quadratic[3] = {1.0, 0.001, 0.0000001};
// makes the points fade as they move away
glPointParameterfvPtr(GL_DISTANCE_ATTENUATION_EXT, quadratic);
glPointParameterfPtr(GL_POINT_SIZE_MIN_EXT, 1.0);
}
Adding Extensions
-----------------
To add an extension to the SimGear extension support code you normally only need
to edit the extensions.hxx header file in the screen directory.
Currently there are two extensions supported:
* glPointParameterf
* glActiveTexture
Adding a new extension involves adding the defines assosiated with the extension
(surrounded by the appropriate extension test):
#ifndef GL_EXT_point_parameters
# define GL_EXT_point_parameters 1
# define GL_POINT_SIZE_MIN_EXT 0x8126
# define GL_DISTANCE_ATTENUATION_EXT 0x8129
#endif
This is needed because not all OpenGL implementations define them correctly.
The following step is to add a typedef for the function pointer:
typedef void (APIENTRY * glPointParameterfProc)(GLenum pname, GLfloat param);
The APIENTRY refference is only used by windows machines but is defined empty
for all other platforms and hence needs to be added for cross platfrom
compatibillity.

45
docs-mini/README.fgjs Normal file
View File

@@ -0,0 +1,45 @@
fgjs -- a small program for creating a basic FlightGear joystick
configuration
fgjs requires plib to be installed on your system. If you've
successfully installed and built FlightGear then you should be
all set
Build instructions
At this point, fgjs has only been built and tested under Linux,
so the makefile is a simple one. cd into the directory in which
the fgjs source resides and type 'make' and, if you are lucky,
all will go well. You can e-mail me (apeden@earthlink.net) any
changes needed to make it work on other systems. It's quite
possible that this program will become part of the regular
FlightGear package so
Running
Set up your joystick and make sure it works with js_demo from the
FlightGear distribution. Upon executing fgjs, it will prompt you
to move the control you wish to use for elevator, ailerons, etc.
Note that when being prompted for an analog control, you can skip
the current one by pressing any button and vice-versa when being
prompted for a button. You may want to do this if for, as an
example, rudder if you have only one joystick or your joystick
doesn't have as many analog axes as FlightGear supports.
Once you've run with this configuration, you may wish to tune
the dead-band a bit (see fgfsrc.js) as the default, 0.02, may
be too narrow for your particular hardware/taste.
And last, but not least, this thing needs a GUI!!!! Hopefully,
the joystick handling code and interface code are separate
enough that using that a GUI version could be built using this
source as a starting point.

416
docs-mini/README.gui Normal file
View File

@@ -0,0 +1,416 @@
FlightGear GUI Mini-HOWTO
David Megginson
Started: 2003-01-20
Last revised: 2003-01-20
FlightGear creates its drop-down menubar and dialog boxes from XML
configuration files under $FG_ROOT/gui. This document gives a quick
explanation of how to create or modify the menubar and dialogs. The
toolkit for the FlightGear GUI is PUI, which is part of plib.
All of the XML files use the standard FlightGear PropertyList format.
MENUBAR
-------
FlightGear reads the configuration for its menubar from
$FG_ROOT/gui/menubar.xml. The file consists of a series of top-level
elements named "menu", each of which defines on of the drop-down
menus, from left to right. Each menu contains a series of items,
representing the actual items a user can select from the menu, and
each item has a series of bindings that FlightGear will activate when
the user selects the item.
Here's a simplified grammar:
[menubar] : menu*
menu : label, item*
item : label, binding*
The bindings are standard FlightGear bindings, the same as the ones
used for the keyboard, mouse, joysticks, and the instrument panel.
Any commands allowed in those bindings are allowed here as well.
Here's an example of a simple menubar with a "File" drop-down menu and
a single "Quit" item:
<PropertyList>
<menu>
<label>File</label>
<item>
<label>Quit</label>
<binding>
<command>exit</command>
</binding>
</item>
</PropertyList>
PUI menus do not allow advanced features like submenus or checkmarks.
The most common command to include in a menu item binding is the
'dialog-show' command, which will open a user-defined dialog box as
described in the next section.
DIALOGS
-------
The configuration files for XML dialogs use a nested structure to set
up dialog boxes. The top-level always describes a dialog box, and the
lower levels describe the groups and widgets that make it up. Here is
a simple, "hello world" dialog:
<PropertyList>
<name>hello</name>
<width>150</width>
<height>100</height>
<modal>false</modal>
<draggable>true</draggable>
<text>
<x>10</x>
<y>50</y>
<label>Hello, world</label>
<color>
<red>1.0</red>
<green>0.0</green>
<blue>0.0</blue>
</color>
</text>
<button>
<x>40</x>
<y>10</y>
<legend>Close</legend>
<binding>
<command>dialog-close</command>
</binding>
</button>
</PropertyList>
The dialog contains two sub-objects: a text field and a button. The
button contains one binding, which closes the active dialog when the
user clicks on the button.
Coordinates are pseudo-pixels. The screen is always assumed to be
1024x768, no matter what the actual resolution is. The origin is the
bottom left corner of the screen (or parent dialog or group); x goes
from left to right, and y goes from bottom to top.
All objects, including the top-level dialog, accept the following
properties, though they will ignore any that are not relevant:
x - the X position of the bottom left corner of the object, in
pseudo-pixels. The default is to center the dialog.
y - the Y position of the bottom left corner of the object, in
pseudo-pixels. The default is to center the dialog.
width - the width of the object, in pseudo-pixels. The default is
the width of the parent container.
height - the height of the object, in pseudo-pixels. The default is
the width of the parent container.
border - the border thickness, in pseudo-pixels. The default is 2.
color - a subgroup to specify the dialogs color:
red - specify the red color component of the color scheme.
green - specify the green color component of the color scheme.
blue - specify the blue color component of the color scheme.
alpha - specify the alpha color component of the color scheme.
font - a subgroup to specify a specific font type
name - the name of the font (excluding it's .txf extension)
size - size of the font
slant - the slant of the font (in pseudo-pixels)
legend - the text legend to display in the object.
label - the text label to display near the object.
property - the name of the FlightGear property whose value will
be displayed in the object (and possibly modified through it).
binding - a FlightGear command binding that will be fired when the
user activates this object (more than one allowed).
default - true if this is the default object for when the user
presses the [RETURN] key.
Objects may appear nested within the top-level dialog or a "group"
or a "frame" object. Here are all the object types allowed, with their
special properties:
dialog
------
The top-level dialog box; the name does not actually appear in the
file, since the root element is named PropertyList.
name - (REQUIRED) the unique name of the dialog for use with the
"dialog-show" command.
modal - true if the dialog is modal (it blocks the rest of the
program), false otherwise. The default is false.
draggable - false if the dialog is not draggable. The default is true.
Example:
<PropertyList>
<name>sample</name>
<width>500</width>
<height>210</height>
<modal>false</modal>
<text>
...
</text>
<button>
...
</button>
</PropertyList>
group and frame
---------------
A group of subobjects. This object does not draw anything on the
screen, but all of its children specify their coordinates relative to
the group; using groups makes it easy to move parts of a dialog
around.
A frame is a visual representation of a group and has a border and an
adjustable background color.
Example:
<group>
<x>0</x>
<y>50</y>
<text>
...
</text>
<input>
...
</input>
<button>
...
</button>
</group>
input
-----
A simple editable text field.
Example:
<input>
<x>10</x>
<y>60</y>
<width>200</width>
<height>25</height>
<label>sea-level temperature (degC)</label>
<property>/environment/temperature-sea-level-degc</property>
</input>
text
----
A non-editable text label.
Example:
<text>
<x>10</x>
<y>200</y>
<label>Heading</label>
</text>
<text>
<x>10</x>
<y>200</y>
<label>-9.9999</label> <!-- placeholder for width -->
<format>%-0.4f m</format>
<property>/foo/altitude</property>
</text>
checkbox
--------
A checkbox, useful for linking to boolean properties.
Example:
<checkbox>
<x>150</x>
<y>200</y>
<width>12</width>
<height>12</height>
<property>/autopilot/locks/heading</property>
</checkbox>
button
------
A push button, useful for firing command bindings.
one-shot - true if the button should pop up again after it is
pushed, false otherwise. The default is true.
<button>
<x>0</x>
<y>0</y>
<legend>OK</legend>
<binding>
<command>dialog-apply</command>
</binding>
<binding>
<command>dialog-close</command>
</binding>
<default>true</default>
</button>
combo
-----
A pop-up list of selections.
value - one of the selections available for the combo. There may be
any number of "value" fields.
Example:
<combo>
<x>10</x>
<y>50</y>
<width>200</width>
<height>25</height>
<property>/environment/clouds/layer[0]/type</property>
<value>clear</value>
<value>mostly-sunny</value>
<value>mostly-cloudy</value>
<value>overcast</value>
<value>cirrus</value>
</combo>
select
------
A scrollable list of selections.
selection - a path in the property tree which holds the selectable items.
Example:
<select>
<x>10</x>
<y>50</y>
<width>200</width>
<height>25</height>
<property>/sim/aircraft</property>
<selection>/sim/aircraft-types</selection>
</select>
slider
------
A horizontal or vertical slider for setting a value.
vertical - true if the slider should be vertical, false if it should
be horizontal. The default is false.
min - the minimum value for the slider. The default is 0.0.
max - the maximum value for the slider. The default is 1.0.
Example:
<slider>
<x>10</x>
<y>50</y>
<width>200</width>
<property>/environment/visibility-m</property>
<min>5</min>
<max>50000</max>
</slider>
dial
----
A circular dial for choosing a direction.
wrap - true if the dial should wrap around, false otherwise. The
default is true.
min - the minimum value for the dial. The default is 0.0.
max - the maximum value for the dial. The default is 1.0.
Example:
<dial>
<x>10</x>
<y>50</y>
<width>20</width>
<property>/environment/wind-from-direction-deg</property>
<min>0</min>
<max>360</max>
</dial>
textbox
-------
The text will be retrieved/buffered from/within a specified
property tree, like:
<textbox>
<!-- position -->
<x>100</x>
<y>100</y>
<!-- dimensions -->
<width>200</width>
<height>400</height>
<property>/gui/path-to-text-node/contents</property>
<slider>15</slider> <!--width for slider -->
<wrap>false</wrap> <!-- don't wrap text; default: true -->
<editable>true</editable> <!-- whether the puLargeInput is supposed to be editable -->
</textbox>
__end__

106
docs-mini/README.introduction Normal file
View File

@@ -0,0 +1,106 @@
Internals
---------
The core of FlightGear is the property system. This is a tree like internal
representation of global variables. The property system is explained more
in detail later on.
FlightGear' way of doing things is breaking it up into small pieces. There is
(for example) animation code that reacts on property changes. There is also a
Flight Dynamics model (FDM) that (amongst other things) updates properties.
There is a menu system that can display and alter properties. Then we have
sound code that plays sound based on ... properties.
Maybe you see a pattern evolve by now.
All subsystems are almost self containing. Most of the time they only read the
values of some properties, and sometimes they alter other properties. This is
the basic way of communicating between subsystems.
Property System
---------------
The property system is best described as an in-memory LDAP database which holds
the state of global variables. The system has a tree like hierarchy (like a
file system) and has a root node, sub nodes (like subdirectories) and end-nodes
(variables).
All variables are kept internally as raw values and can be converted to any
other supported type (boolean, int, float double and string).
Like a file system, every node can be accessed relative to the current node, or
absolute to the root node.
The property system also allows aliasing nodes to other nodes (like symbolic
linking files or directories to other files or directories) and may be assigned
read-only or read-write.
If necessary it would be possible for parts of the program to hold it's own
property tree, which is inaccessible from the global property tree, by keeping
track of it's own root-node.
Property I/O code allows one to easily read the tree from, or write the tree to
an XML file.
Subsystems
----------
To add a new subsystem you would have to create a derived class from
SGSubsystem and define at least a small set of functions:
class FGSubsystemExample : public SGSubsystem
{
public:
FGSubsystemExample();
virtual ~FGSubsystemExample();
// Subsystem API.
void bind() override;
void init() override;
void reinit() override;
void unbind() override;
void update(double dt) override;
// Subsystem identification.
static const char* staticSubsystemClassId() { return "subsystem-example"; }
};
To register the subsystem with the subsystem manager, for non-instanced
subsystems add:
// Register the subsystem.
SGSubsystemMgr::Registrant<FGSubsystemExample> registrantFGSubsystemExample
Or to define a specific subsystem manager group, e.g. DISPLAY, and add any
dependencies:
// Register the subsystem.
SGSubsystemMgr::Registrant<FGSubsystemExample> registrantFGSubsystemExample(
SGSubsystemMgr::DISPLAY,
{{"viewer", SGSubsystemMgr::Dependency::HARD},
{"FGRenderer", SGSubsystemMgr::Dependency::NONSUBSYSTEM_HARD}});
The init() functions should make sure everything is set and ready so the
update() function can be run by the main loop. The reinit() function handles
everything in case of a reset by the user.
The bind() and unbind() functions can be used to tie and untie properties.
Finally to create and have the subsystem managed:
globals->add_subsystem("example", new FGSubsystemExample);
Now the subsystem manager calls the update() function of this class every
frame. dt is the time (in seconds) elapsed since the last call.
Scripting
---------
The scripting langage Nasal can also read and modify properties but it can also
be incorporated into the menu system. The documentation for Nasal can be found
here: http://www.plausible.org/nasal/flightgear.html

12
docs-mini/README.jsclient Normal file
View File

@@ -0,0 +1,12 @@
Start flightgear with
fgfs --jsclient=socket,in,<hz>,,<port>,udp --prop:/jsclient/axis[i]="/property/you/want/to/control" --prop:/jsclient/axis[i+1]="/another/property/you/want/to/control" ...
eg:
# fgfs --aircraft=yf23-yasim --airport=KEMT --jsclient=socket,in,5,,16759,udp --prop:/jsclient/axis[0]="/controls/flight/spoilers" --prop:/jsclient/axis[1]="/radios/comm/volume"
Start the server on the machine with the remote gameport:
JsServer <host> <port>
eg:
# JsServer 192.168.1.1 16759
(JsServer can be started before or after fgfs)

86
docs-mini/README.logging Normal file
View File

@@ -0,0 +1,86 @@
Logging in FlightGear
---------------------
[Note: JSBSim also has its own independent logging facilities, which
are not discussed here.]
FlightGear can log any property values at any interval to one or more
CSV files (which can be read and graphed using spreadsheets like
Gnumeric or Excel). Logging is defined in the '/logging' subbranch of
the main property tree; under '/logging', each '/log' subbranch
defines a separate log with its own output file and interval. Here is
a simple example that logs the rudder and aileron settings every
second (1000ms) to the file steering.csv, using a comma (the default,
anyway) as the field delimiter:
<logging>
<log>
<enabled>true<enabled>
<filename>steering.csv</filename>
<interval-ms>1000</interval-ms>
<delimiter>,</delimiter>
<entry>
<enabled>true</enabled>
<title>Rudder</title>
<property>/controls/rudder</property>
</entry>
<entry>
<enabled>true</enabled>
<title>Ailerons</title>
<property>/controls/aileron</property>
</entry>
</log>
</logging>
Each 'log' subbranch contains a required 'enabled' property, an
optional 'filename' property (defaults to "fg_log.csv"), an optional
'delimiter' property (defaults to a comma), an optional 'interval-ms'
property (defaults to 0, which logs every frame), and a series of
'entry' subbranches. The 'delimiter' property uses only the first
character of the property value as the delimiter. Note that the
logger does no escaping, so you must choose a delimiter that will not
appear in the property values (that's not hard, since most of the
values are numeric, but watch for commas in the titles).
Each 'entry' subbranch contains a required 'enabled' property, a
'property' property specifying the name of the property to be logged,
and an optional 'title' property specifying the title to use in the
CSV file (defaults to the full path of the property). The elapsed
time in milliseconds since the start of the simulation is always
included as the first entry with the title "Time", so there is no need
to include it explicitly.
Here's a sample of the logging output for the above log:
Time,Rudder,Ailerons
6522,0.000000,0.000000
7668,-0.000000,0.000000
8702,-0.000000,0.000000
9705,-0.000000,0.000000
10784,-0.000000,0.000000
11792,-0.000000,0.000000
12808,-0.000000,-0.210000
13826,-0.000000,-0.344000
14881,-0.000000,-0.066000
15901,-0.000000,-0.806000
16943,-0.000000,-0.936000
17965,-0.000000,-0.534000
19013,-0.000000,-0.294000
20044,-0.000000,0.270000
21090,-0.000000,-1.000000
22097,-0.000000,-0.168000
Note that the requested interval is only a minimum; most of the time,
the actual interval is slightly longer than the requested one.
The easiest way for an end-user to define logs is to put the log in a
separate XML file (usually under the user's home directory), then
refer to it using the --config option, like this:
fgfs --config=log-config.xml
The output log files are always relative to the current directory.
--
David Megginson, last updated 2002-02-01

125
docs-mini/README.multiplayer Normal file
View File

@@ -0,0 +1,125 @@
The commands are of the form:
--multiplay=in | out,Hz,destination address,destination port
--callsign=a_unique_name
Below are some examples of startup commands that demonstrate the use of the
multiplayer facilities.
For two players on a local network or across the internet:
----------------------------------------------------------
Player1:
--multiplay=out,10,192.168.0.3,5500 --multiplay=in,10,192.168.0.2,5501
--callsign=player1
Player2:
--multiplay=out,10,192.168.0.2,5501 --multiplay=in,10,192.168.0.3,5500
--callsign=player2
For multiple players on a local network:
----------------------------------------
Player1:
--multiplay=out,10,255.255.255.255,5500
--multiplay=in,10,255.255.255.255,5500 --callsign=player1
Playern:
--multiplay=out,10,255.255.255.255,5500
--multiplay=in,10,255.255.255.255,5500 --callsign=playern
Note that the callsign is used to identify each player in a multiplayer game
so the callsigns must be unique. The multiplayer code ignores packets that
are sent back to itself, as would occur with broadcasting when the rx and tx
ports are the same.
Multiple players sending to a single player:
--------------------------------------------
Player1:
--multiplay=out,10,192.168.0.2,5500 --callsign=player1
Player2:
--multiplay=out,10,192.168.0.2,5500 --callsign=player2
Player3:
--multiplay=out,10,192.168.0.2,5500 --callsign=player3
Player4 (rx only):
--multiplay=in,10,192.168.0.2,5500 --callsign=player4
This demonstrates that it is possible to have multiple instances of
Flightgear that send to a single instance that displays all the traffic. This
is the sort of implementation that we are considering for use as a tower
visual simulator.
For use with a server:
----------------------
Oliver Schroeder has created a server for multiplayer flightgear use.
The server acts as a packet forwarding mechanism. When it
receives a packet, it sends it to all other active players
in the vicinity (the server is configured to use 100nm by default).
Check out the server homepage <http://www.o-schroeder.de/fg_server/>
for the current status. You can either download the server for
some local use, or join the developers flying at the existing servers.
As with flightgear, the server is free software, released under GPL.
Pigeon <http://pigeond.net> has created a web page monitoring
two such servers, showing the traffic in a Google map environment.
See <http://pigeond.net/flightgear/fg_server_map.html>.
Options needed to enable multiplayer game with a server:
Player1:
--multiplay=out,10,serveraddress,5002 --multiplay=in,10,myaddress,5002
--callsign=player1
Player2:
--multiplay=out,10,serveraddress,5002 --multiplay=in,10,myaddress,5002
--callsign=player2
...
PlayerN:
--multiplay=out,10,serveraddress,5002 --multiplay=in,10,myaddress,5002
--callsign=playerN
Note that if every player using a particular server, such as one of those
listed on the Pigeon's page, needs to have a unique callsign, not
already in use on that server.
If you are sitting behind a NAT'ting firewall, then you need to forward
the incoming traffic on the firewall outer (visible to the internet)
address arriving at the UDP port you use (5002 in the case above)
over to your private LAN address. In this case, use your PRIVATE LAN address
as <myaddress>. Example (if your private LAN address is 10.0.0.1,
in order to play on pigeond.net):
fgfs --multiplay=in,10,10.0.0.1,5002 --multiplay=out,10,pigeond.net,5002
--callsign=...UNIQUE callsign here...
If you and the server are in the same address space (i.e., both have a public
IP address or both are on the same private LAN), you hopefully don't need to
mess with any firewalls.
If you don't see other players playing on the same server in your flightgear,
check that you have followed the above router configuration guidelines. Check
that you don't have any LOCAL firewall running on your computer preventing the
flightgear network traffic flow.
Finally, use ethereal(1) or tethereal(1) to capture the UDP traffic on the port
that you are using, and see if you observe both incoming and outgoing packets.
It's a good idea to talk to the IRC channel #flightgear on irc.flightgear.org
while flying on one of the public servers. Also, it makes sense for every user
on the same server to use the same weather setup, e.g., the real weather
METAR feed, selected by setting to true the real-world-weather-fetch and
control-fdm-atmosphere properties.
Further reading (a must if you have a problem):
-----------------------------------------------
[1] The flightgear server homepage <http://www.o-schroeder.de/fg_server/>
[2] The flightgear wiki multiplayer howto <http://www.seedwiki.com/wiki/flight_gear/flightgear_multiplayer_documentation.cfm>
[3] If everything else fails, ask for help on
the IRC channel #flightgear on irc.flightgear.org

661
docs-mini/README.multiscreen Normal file
View File

@@ -0,0 +1,661 @@
The Open Scene Graph library, which current FlightGear uses for its 3D
graphics, provides excellent support for multiple views of a
scene. FlightGear uses the osgViewer::Viewer class, which implements a
"master" camera with "slave" cameras that are offset from the master's
position and orientation. FlightGear provides the "camera group"
abstraction which allows the configuration of slave cameras via the
property tree.
Slave cameras can be mapped to windows that are open on different
screens, or all in one window, or a combination of those two schemes,
according to the video hardware capabilities of a machine. It is not
advisable to open more than one window on a single graphics card due
to the added cost of OpenGL context switching between the
windows. Usually, multiple monitors attached to a single graphics card
are mapped to different pieces of the same desktop, so a window can be
opened that spans all the monitors. This is implemented by Nvidia's
TwinView technology and the Matrox TripleHead2Go hardware.
The camera group is configured by the /sim/rendering/camera-group node
in the property tree. It can be set up by, among other things, XML in
preferences.xml or in an XML file specified on the command line with
the --config option.
Here are the XML tags for defining camera groups.
camera-group
For the moment there can be only one camera group. It can contain
window, camera, or gui tags.
window
A window defines a graphics window. It can be at the camera-group
level or defined within a camera. The window contains these tags:
name - string
The name of the window which might be displayed in the window's
title bar. It is also used to refer to a previously defined
window. A window can contain just a name node, in which case
the whole window definition refers to a previously defined window.
host-name - string
The name of the host on which the window is opened. Usually this is
empty.
display - int
The display number on which the window is opened.
screen - int
The screen number on which the window is opened.
x, y - int
The location on the screen at which the window is opened. This is in
the window system coordinates, which usually puts 0,0 at the upper
left of the screen XXX check this for Windows.
width, height - int
The dimensions of the window.
decoration - bool
Whether the window manager should decorate the window.
fullscreen - bool
Shorthand for a window that occupies the entire screen with no
decoration.
camera
The camera node contains viewing parameters.
window
This specifies the window which displays the camera. Either it
contains just a name that refers to a previous window definition, or
it is a full window definition.
viewport
The viewport positions a camera within a window. It is most useful
when several cameras share a window.
x, y - int
The position of the lower left corner of the viewport, in y-up
coordinates.
width, height - int
The dimensions of the viewport
physical-dimensions
The physical dimension of the projection surface.
Use this together with the master-perspective, right-of-perspective
left-of-perspective, above-perspective, below-perspective or
reference-points-perspective
width, height - double
The dimensions of the projection plane, if unset the veiwport values
are taken as default.
bezel
Gives informantion about the bezel of monitors for a seamless view.
right
right bezel with in the same units than with and height above
left
left bezel with in the same units than with and height above
top
top bezel with in the same units than with and height above
bottom
bottom bezel with in the same units than with and height above
view
The view node specifies the origin and direction of the camera in
relation to the whole camera group. The coordinate system is +y up,
-z forward in the direction of the camera group view. This is the
same as the OpenGL viewing coordinates.
x,y,z - double
Coordinates of the view origin.
heading-deg, pitch-deg, roll-deg - double
Orientation of the view in degrees. These are specified using the
right-hand rule, so a positive heading turns the view to the left,
a positive roll rolls the view to the left.
perspective
This node is one way of specifying the viewing volume camera
parameters. It corresponds to the OpenGL gluPerspective function.
fovy-deg - double
The vertical field-of-view
aspect-ratio - double
Aspect ratio of camera rectangle (not the ratio between the
vertical and horizontal fields of view).
near, far - double
The near and far planes, in meters from the camera eye point. Note
that FlightGear assumes that the far plane is far away, currently
120km. The far plane specified here will be respected, but the sky
and other background elements may not be drawn if the view plane is
closer than 120km.
fixed-near-far - bool
If true the near and far values are taken from above, if false
near and far are adapted from the scene and visibility.
Defaults to true.
offset-x, offset-y - double
Offsets of the viewing volume specified by the other parameters in
the near plane, in meters.
frustum
This specifies the perspective viewing volume using values for the near
and far planes and coordinates of the viewing rectangle in the near
plane.
left, bottom - double
right, top - double
The coordinates of the viewing rectangle.
near, far - double
The near and far planes, in meters from the camera eye point.
fixed-near-far - bool
If true the near and far values are taken from above, if false
near and far are adapted from the scene and visibility.
Defaults to true.
ortho
This specifies an orthographic view. The parameters are the sames as
the frustum node's.
fixed-near-far - bool
If true the near and far values are taken from above, if false
near and far are adapted from the scene and visibility.
Defaults to true.
master-perspective
Defines a persective projection matrix for use as the leading display
in a seamless multiscreen configuration. This kind of perspective
projection is zoomable.
eye-distance - double
The distance of the eyepoint from the projection surface in units of
the physical-dimensions values above.
x-offset, y-offset - double
Offset of the eyelpint from the center of the screen in units of
the physical-dimensions values above.
left-of-perspective, right-of-perspective, above-perspective,
below-perspective
Defines a perspective projection matrix for use as derived display
in a seamless multiscreen configuration. The projection matrix
is computed so that the respective edge of this display matches the
assiciated other edge of the other display. For example the right edge
of a left-of-perspective display matches the left edge of the parent
display. This also works with different zoom levels, leading to distorted
but still seamless multiview configurations.
The bezel with configured in the physical dimensions of this screen and
the parent screen are taken into account for this type of projection.
parent-camera - string
Name of the parent camera.
reference-points-perspective
Defines a perspective projection matrix for use as derived display
in a seamless multiscreen configuration. This type is very similar to
left-of-perspective and friends. It is just a more flexible but less
convenient way to get the same effect. A child display is configured
by 2 sets of reference points one in this current camera and one in
the parrent camera which should match in the final view.
parent-camera - string
Name of the parent camera.
this
reference points for this projection.
point - array of two points
x, y - double
x and y coodinates of the reference points in units of this
physical-dimensions.
parent
reference points for the parent projection.
point - array of two points
x, y - double
x and y coodinates of the reference points in units of the
parents physical-dimensions.
texture
This tag indicates that the camera renders to a texture instead of the
framebuffer. For now the following tags are supported, but obviously
different texture formats should be specified too.
name - string
The name of the texture. This can be referred to by other cameras.
width, height - double
The dimensions of the texture
panoramic-distortion
This tag cause the camera to create distortion geometry that
corrects for projection onto a spherical screen. It is equivalent to
the --panoramic-sd option to osgviewer.
texture - string
The name of a texture, created by another camera, that will be
rendered on the distortion correction geometry.
radius - double
Radius of string
collar - double
size of screen collar.
gui
This is a special camera node that displays the 2D GUI.
viewport
This specifies the position and dimensions of the GUI within a
window, *however* at the moment the origin must be at 0,0.
Here's an example that uses a single window mapped across 3
displays. The displays are in a video wall configuration in a
horizontal row.
<PropertyList>
<sim>
<rendering>
<camera-group>
<window>
<name>wide</name>
<host-name type="string"></host-name>
<display>0</display>
<screen>0</screen>
<width>3840</width>
<height>1024</height>
<decoration type = "bool">false</decoration>
</window>
<camera>
<window>
<name>wide</name>
</window>
<viewport>
<x>0</x>
<y>0</y>
<width>1280</width>
<height>1024</height>
</viewport>
<view>
<heading-deg type = "double">0</heading-deg>
</view>
<frustum>
<top>0.133</top>
<bottom>-0.133</bottom>
<left>-.5004</left>
<right>-.1668</right>
<near>0.4</near>
<far>120000.0</far>
</frustum>
</camera>
<camera>
<window>
<name type="string">wide</name>
</window>
<viewport>
<x>1280</x>
<y>0</y>
<width>1280</width>
<height>1024</height>
</viewport>
<view>
<heading-deg type = "double">0</heading-deg>
</view>
<frustum>
<top>0.133</top>
<bottom>-0.133</bottom>
<left>-.1668</left>
<right>.1668</right>
<near>0.4</near>
<far>120000.0</far>
</frustum>
</camera>
<camera>
<window>
<name>wide</name>
</window>
<viewport>
<x>2560</x>
<y>0</y>
<width>1280</width>
<height>1024</height>
</viewport>
<view>
<heading-deg type = "double">0</heading-deg>
</view>
<frustum>
<top>0.133</top>
<bottom>-0.133</bottom>
<left>.1668</left>
<right>.5004</right>
<near>0.4</near>
<far>120000.0</far>
</frustum>
</camera>
<gui>
<window>
<name type="string">wide</name>
</window>
</gui>
</camera-group>
</rendering>
</sim>
</PropertyList>
Here's a complete example that uses a seperate window on each
display. The displays are arranged in a shallow arc with the left and
right displays at a 45.3 degree angle to the center display because,
at the assumed screen dimensions, the horizontal field of view of one
display is 45.3 degrees. Each camera has its own window definition;
the center window is given the name "main" so that the GUI definition
can refer to it. Note that the borders of the displays are not
accounted for.
<PropertyList>
<sim>
<rendering>
<camera-group>
<camera>
<window>
<host-name type="string"></host-name>
<display>0</display>
<screen>0</screen>
<fullscreen type = "bool">true</fullscreen>
</window>
<view>
<heading-deg type = "double">45.3</heading-deg>
</view>
<frustum>
<top>0.133</top>
<bottom>-0.133</bottom>
<left>-.1668</left>
<right>.1668</right>
<near>0.4</near>
<far>120000.0</far>
</frustum>
</camera>
<camera>
<window>
<name type="string">main</name>
<host-name type="string"></host-name>
<display>0</display>
<screen>1</screen>
<fullscreen type = "bool">true</fullscreen>
</window>
<view>
<heading-deg type = "double">0</heading-deg>
</view>
<frustum>
<top>0.133</top>
<bottom>-0.133</bottom>
<left>-.1668</left>
<right>.1668</right>
<near>0.4</near>
<far>120000.0</far>
</frustum>
</camera>
<camera>
<window>
<host-name type="string"></host-name>
<display>0</display>
<screen>2</screen>
<fullscreen type = "bool">true</fullscreen>
</window>
<view>
<heading-deg type = "double">-45.3</heading-deg>
</view>
<frustum>
<top>0.133</top>
<bottom>-0.133</bottom>
<left>-.1668</left>
<right>.1668</right>
<near>0.4</near>
<far>120000.0</far>
</frustum>
</camera>
<gui>
<window>
<name type="string">main</name>
</window>
</gui>
</camera-group>
</rendering>
</sim>
</PropertyList>
This example renders the scene for projection onto a spherical screen.
<PropertyList>
<sim>
<rendering>
<camera-group>
<camera>
<window>
<name type="string">main</name>
<host-name type="string"></host-name>
<display>0</display>
<screen>0</screen>
<!-- <fullscreen type = "bool">true</fullscreen>-->
<width>1024</width>
<height>768</height>
</window>
<view>
<heading-deg type = "double">0</heading-deg>
</view>
<frustum>
<top>0.133</top>
<bottom>-0.133</bottom>
<left>-.1668</left>
<right>.1668</right>
<near>0.4</near>
<far>120000.0</far>
</frustum>
<texture>
<name>mainview</name>
<width>1024</width>
<height>768</height>
</texture>
</camera>
<camera>
<window><name>main</name></window>
<ortho>
<top>768</top>
<bottom>0</bottom>
<left>0</left>
<right>1024</right>
<near>-1.0</near>
<far>1.0</far>
</ortho>
<panoramic-spherical>
<texture>mainview</texture>
</panoramic-spherical>
</camera>
<gui>
<window>
<name type="string">main</name>
</window>
</gui>
</camera-group>
</rendering>
</sim>
</PropertyList>
Here is an example for a 3 screen seamless zoomable multiscreen
configuration using 3 533mmx300mm displays each with a 23mm bezel.
The side views are angled with 45 deg.
The commented out reference-points-perspective shows the
aequivalent configuration than the active right-of-perspective.
This is done by just using two reference points at the outer
edge of the bezel of the respective display.
<PropertyList>
<sim>
<view n="0">
<config>
<pitch-offset-deg>0.0</pitch-offset-deg>
</config>
</view>
<rendering>
<camera-group>
<window>
<name type="string">0.0</name>
<host-name type="string"></host-name>
<display>0</display>
<screen>0</screen>
<fullscreen type="bool">true</fullscreen>
</window>
<window>
<name type="string">0.1</name>
<host-name type="string"></host-name>
<display>0</display>
<screen>1</screen>
<fullscreen type="bool">true</fullscreen>
</window>
<camera>
<name type="string">CenterCamera</name>
<window>
<name>0.0</name>
</window>
<viewport>
<x>0</x>
<y>0</y>
<width>1920</width>
<height>1080</height>
</viewport>
<view>
<heading-deg type="double">0.0</heading-deg>
<roll-deg type="double">0.0</roll-deg>
<pitch-deg type="double">0.0</pitch-deg>
</view>
<physical-dimensions>
<!-- The size of the projection plane: 533mm 300mm -->
<width>533</width>
<height>300</height>
<bezel>
<right>23</right>
<left>23</left>
<top>23</top>
<bottom>23</bottom>
</bezel>
</physical-dimensions>
<master-perspective>
<!-- Cheating, the real distance is about 800mm.
But then the screen does not show what is needed to fly.
By shortening this pictures get bigger but the view also gets
less realistic.
-->
<eye-distance>450</eye-distance>
<x-offset>0</x-offset>
<y-offset>130</y-offset>
</master-perspective>
</camera>
<camera>
<name type="string">RightCamera</name>
<window>
<name>0.0</name>
</window>
<viewport>
<x>1920</x>
<y>0</y>
<width>1920</width>
<height>1080</height>
</viewport>
<view>
<heading-deg type="double">-45</heading-deg>
<roll-deg type="double">0</roll-deg>
<pitch-deg type="double">0</pitch-deg>
</view>
<physical-dimensions>
<!-- The size of the projection plane: 533mm 300mm -->
<width>533</width>
<height>300</height>
<bezel>
<right>23</right>
<left>23</left>
<top>23</top>
<bottom>23</bottom>
</bezel>
</physical-dimensions>
<right-of-perspective>
<parent-camera type="string">CenterCamera</parent-camera>
</right-of-perspective>
<!-- <reference-points-perspective> -->
<!-- <parent-camera type="string">CenterCamera</parent-camera> -->
<!-- <parent> -->
<!-- <point n="0"> -->
<!-- <x>289.5</x> -->
<!-- <y>100</y> -->
<!-- </point> -->
<!-- <point n="1"> -->
<!-- <x>289.5</x> -->
<!-- <y>-100</y> -->
<!-- </point> -->
<!-- </parent> -->
<!-- <this> -->
<!-- <point n="0"> -->
<!-- <x>-289.5</x> -->
<!-- <y>100</y> -->
<!-- </point> -->
<!-- <point n="1"> -->
<!-- <x>-289.5</x> -->
<!-- <y>-100</y> -->
<!-- </point> -->
<!-- </this> -->
<!-- </reference-points-perspective> -->
</camera>
<camera>
<name type="string">LeftCamera</name>
<window>
<name>0.1</name>
</window>
<viewport>
<x>0</x>
<y>0</y>
<width>1920</width>
<height>1080</height>
</viewport>
<view>
<heading-deg type="double">45</heading-deg>
<roll-deg type="double">0</roll-deg>
<pitch-deg type="double">0</pitch-deg>
</view>
<physical-dimensions>
<!-- The size of the projection plane: 533mm 300mm -->
<width>533</width>
<height>300</height>
<bezel>
<right>23</right>
<left>23</left>
<top>23</top>
<bottom>23</bottom>
</bezel>
</physical-dimensions>
<left-of-perspective>
<parent-camera type="string">CenterCamera</parent-camera>
</left-of-perspective>
</camera>
<gui>
<window>
<name type="string">0.0</name>
</window>
</gui>
</camera-group>
</rendering>
</sim>
</PropertyList>

259
docs-mini/README.properties Normal file
View File

@@ -0,0 +1,259 @@
================================================================================
CONTROLS
================================================================================
Flight Controls
---------------
/controls/flight/aileron
/controls/flight/aileron-trim
/controls/flight/elevator
/controls/flight/elevator-trim
/controls/flight/rudder
/controls/flight/rudder-trim
/controls/flight/flaps
/controls/flight/slats
/controls/flight/BLC // Boundary Layer Control
/controls/flight/spoilers
/controls/flight/speedbrake
/controls/flight/wing-sweep
/controls/flight/wing-fold
/controls/flight/drag-chute
Engines
-------
/controls/engines/throttle_idle
/controls/engines/engine[%d]/throttle
/controls/engines/engine[%d]/starter
/controls/engines/engine[%d]/fuel-pump
/controls/engines/engine[%d]/fire-switch
/controls/engines/engine[%d]/fire-bottle-discharge
/controls/engines/engine[%d]/cutoff
/controls/engines/engine[%d]/mixture
/controls/engines/engine[%d]/propeller-pitch
/controls/engines/engine[%d]/magnetos
/controls/engines/engine[%d]/boost
/controls/engines/engine[%d]/WEP
/controls/engines/engine[%d]/cowl-flaps-norm
/controls/engines/engine[%d]/feather
/controls/engines/engine[%d]/ignition
/controls/engines/engine[%d]/augmentation
/controls/engines/engine[%d]/afterburner
/controls/engines/engine[%d]/reverser
/controls/engines/engine[%d]/water-injection
/controls/engines/engine[%d]/condition
Fuel
----
/controls/fuel/dump-valve
/controls/fuel/tank[%d]/fuel_selector
/controls/fuel/tank[%d]/to_engine
/controls/fuel/tank[%d]/to_tank
/controls/fuel/tank[%d]/boost-pump[%d]
/consumables/fuel/tank[%d]/level-lb
/consumables/fuel/tank[%d]/level-lbs
/consumables/fuel/tank[%d]/level-gal_us
/consumables/fuel/tank[%d]/capacity-gal_us
/consumables/fuel/tank[%d]/density-ppg
/consumables/fuel/total-fuel-lbs
/consumables/fuel/total-gal_us
Gear
----
/controls/gear/brake-left
/controls/gear/brake-right
/controls/gear/brake-parking
/controls/gear/steering
/controls/gear/gear-down
/controls/gear/antiskid
/controls/gear/tailhook
/controls/gear/tailwheel-lock
/controls/gear/wheel[%d]/alternate-extension
Anti-Ice
--------
/controls/anti-ice/wing-heat
/controls/anti-ice/pitot-heat
/controls/anti-ice/wiper
/controls/anti-ice/window-heat
/controls/anti-ice/engine[%d]/carb-heat
/controls/anti-ice/engine[%d]/inlet-heat
Hydraulics
----------
/controls/hydraulic/system[%d]/engine-pump
/controls/hydraulic/system[%d]/electric-pump
Electric
--------
/controls/electric/battery-switch
/controls/electric/external-power
/controls/electric/APU-generator
/controls/electric/engine[%d]/generator
/controls/electric/engine[%d]/bus-tie
Pneumatic
---------
/controls/pneumatic/APU-bleed
/controls/pneumatic/engine[%d]/bleed
Pressurization
--------------
/controls/pressurization/mode
/controls/pressurization/dump
/controls/pressurization/outflow-valve
/controls/pressurization/pack[%d]/pack-on
Lights
------
/controls/lighting/landing-lights
/controls/lighting/turn-off-lights
/controls/lighting/formation-lights
/controls/lighting/taxi-light
/controls/lighting/logo-lights
/controls/lighting/nav-lights
/controls/lighting/beacon
/controls/lighting/strobe
/controls/lighting/panel-norm
/controls/lighting/instruments-norm
/controls/lighting/dome-norm
Armament
--------
/controls/armament/master-arm
/controls/armament/station-select
/controls/armament/release-all
/controls/armament/station[%d]/stick-size
/controls/armament/station[%d]/release-stick
/controls/armament/station[%d]/release-all
/controls/armament/station[%d]/jettison-all
Seat
----
/controls/seat/vertical-adjust
/controls/seat/fore-aft-adjust
/controls/seat/cmd_selector_valve
/controls/seat/eject[%d]/initiate
/controls/seat/eject[%d]/status
APU
---
/controls/APU/off-start-run
/controls/APU/fire-switch
Autoflight
----------
/controls/autoflight/autopilot[%d]/engage
/controls/autoflight/autothrottle-arm
/controls/autoflight/autothrottle-engage
/controls/autoflight/heading-select
/controls/autoflight/altitude-select
/controls/autoflight/bank-angle-select
/controls/autoflight/vertical-speed-select
/controls/autoflight/speed-select
/controls/autoflight/mach-select
/controls/autoflight/vertical-mode
/controls/autoflight/lateral-mode
================================================================================
FDM (Aircraft settings)
================================================================================
Position
---------------
/position/latitude-deg
/position/longitude-deg
/position/altitude-ft
Orientation
-----------
/orientation/roll-deg
/orientation/pitch-deg
/orientation/heading-deg
/orientation/roll-rate-degps
/orientation/pitch-rate-degps
/orientation/yaw-rate-degps
/orientation/side-slip-rad
/orientation/side-slip-deg
/orientation/alpha-deg
Velocities
----------
/velocities/airspeed-kt
/velocities/mach
/velocities/speed-north-fps
/velocities/speed-east-fps
/velocities/speed-down-fps
/velocities/uBody-fps
/velocities/vBody-fps
/velocities/wBody-fps
/velocities/vertical-speed-fps
/velocities/glideslope
Acceleration
------------
/accelerations/nlf
/accelerations/ned/north-accel-fps_sec
/accelerations/ned/east-accel-fps_sec
/accelerations/ned/down-accel-fps_sec
/accelerations/pilot/x-accel-fps_sec
/accelerations/pilot/y-accel-fps_sec
/accelerations/pilot/z-accel-fps_sec
Engines
-------
common:
/engines/engine[%d]/fuel-flow-gph
/engines/engine[%d]/fuel-flow_pph
/engines/engine[%d]/thrust_lb
/engines/engine[%d]/running
/engines/engine[%d]/starter
/engines/engine[%d]/cranking
piston:
/engines/engine[%d]/mp-osi
/engines/engine[%d]/egt-degf
/engines/engine[%d]/oil-temperature-degf
/engines/engine[%d]/oil-pressure-psi
/engines/engine[%d]/cht-degf
/engines/engine[%d]/rpm
turbine:
/engines/engine[%d]/n1
/engines/engine[%d]/n2
/engines/engine[%d]/epr
/engines/engine[%d]/augmentation
/engines/engine[%d]/water-injection
/engines/engine[%d]/ignition
/engines/engine[%d]/nozzle-pos-norm
/engines/engine[%d]/inlet-pos-norm
/engines/engine[%d]/reversed
/engines/engine[%d]/cutoff
propeller:
/engines/engine[%d]/rpm
/engines/engine[%d]/pitch
/engines/engine[%d]/torque
================================================================================
LIGHT
================================================================================
/sim/time/sun-angle-rad
/rendering/scene/ambient/red
/rendering/scene/ambient/ggreen
/rendering/scene/ambient/blue
/rendering/scene/diffuse/red
/rendering/scene/diffuse/green
/rendering/scene/diffuse/blue
/rendering/scene/specular/red
/rendering/scene/specular/green
/rendering/scene/specular/blue

293
docs-mini/README.protocol Normal file
View File

@@ -0,0 +1,293 @@
The generic communication protocol for FlightGear provides a powerful way
of adding a simple ASCII based or binary input/output protocol, just by
defining an XML encoded configuration file and placing it in the
$FG_ROOT/Protocol/ directory.
== file layout ================================================================
A protocol file can contain either or both of <input> and <output>
definition blocks. Which one is used depends on how the protocol
is called (e.g. --generic=file,out,1,/tmp/data.xml,myproto would
only use the <output> definitions block).
<?xml version="1.0"?>
<PropertyList>
<generic>
<output>
<binary_mode>false</binary_mode>
<line_separator></line_separator>
<var_separator></var_separator>
<preamble></preamble>
<postamble></postamble>
<chunk>
... first chunk spec ...
</chunk>
<chunk>
... another chunk etc. ...
</chunk>
</output>
<input>
<line_separator></line_separator>
<var_separator></var_separator>
<chunk>
... chunk spec ...
</chunk>
</input>
</generic>
</PropertyList>
== input/output parameters ====================================================
Both <output> and <input> blocks can contain information about
the data mode (ascii/binary) and about separators between fields
and data sets, as well as a list of <chunk>s. Each <chunk> defines
a property that should be written (and how), or a variable and which
property it should be written to.
--- ASCII protocol parameters ---
output only:
<preamble> STRING default: "" file header put on top of the file
<postamble> STRING default: "" file footer put at the end of the file
input & output:
<binary_mode> BOOL default: false (= ASCII mode)
<var_separator> STRING default: "" field separator
<line_separator> STRING default: "" separator between data sets
<var_separator> are put between every two output properties, while
<line_separator> is put at the end of each data set. Both can contain
arbitrary strings or one of the following keywords:
Name Character
newline '\n'
tab '\t'
formfeed '\f'
carriagereturn '\r'
verticaltab '\v'
Typical use could be:
<var_separator>tab</var_separator>
<line_separator>newline</var_separator>
or
<var_separator>\t</var_separator>
<line_separator>\r\n</line_separator>
--- Binary protocol parameters ---
To enable binary mode, simply include a <binary_mode>true</binary_mode> tag in
your XML file. The format of the binary output is tightly packed, with 1 byte
for bool, 4 bytes for int, and 8 bytes for double. At this time, strings are not
supported. A configurable footer at the end of each "line" or packet of binary
output can be added using the <binary_footer> tag. Options include the length
of the packet, a magic number to simplify decoding. Examples:
<binary_footer>magic,0x12345678</binary_footer>
<binary_footer>length</binary_footer>
<binary_footer>none</binary_footer> <!-- default -->
== variable parameters (chunk spec) ===========================================
Both <input> and <output> block can contain a list of <chunk> specs,
each of which describes the properties of on variable to write/read.
<name> for ease of use (not tranferred)
<node> the property tree node which provides the data
<type> the value type (needed for formatting)
one of string, float, bool, int (default: int)
<format> (ASCII protocol only, not used or needed in binary mode)
defines the actual piece of text which should be sent.
it can include "printf" style formatting options like:
<type>
%s string
%d integer (default)
%f float
<factor> an optional multiplication factor which can be used for
unit conversion. (for example, radians to degrees).
<offset> an optional offset which can be used for unit conversion.
(for example, degrees Celcius to degrees Fahrenheit).
For input chunks there exist some more options:
<rel> optional boolean parameter to enable handling of incoming values
as relative changes (default: false)
(Can be eg. used to realise up/down buttons by just sending 1 or
-1 respectively)
<min> an optional minimum limit for the value to be clamped to. This
limit is always specified as absolute value, also with relative
changes enabled. (default: 0)
<max> an optional upper limit for the input value to be clamped to. If
<min> equals <max> no limit is applied. (default: 0)
<wrap> instead of clamping to minimum and maximum limits, wrap values
around. Values will be in [min, max[ (default: false)
(Usefull for eg. heading selector to start again with 1 for
values higher than 360)
<rel>, <min>, <max> and <wrap> are only used for numeric data types. <rel> can
additionally be used with type 'bool', where it toggles the value, if the received
value evaluates to 'true', otherwise the value is left unchanged.
Chunks can also consist of a single constant <format>, like in:
<format>Data Section</format>
== examples ===================================================================
Writes log of this form:
V=16
H=3.590505
P=3.59
V=12
H=3.589020
P=3.59
<?xml version="1.0"?>
<PropertyList>
<generic>
<output>
<line_separator>newline</line_separator>
<var_separator>newline</var_separator>
<binary_mode>false</binary_mode>
<chunk>
<name>speed</name>
<format>V=%d</format>
<node>/velocities/airspeed-kt</node>
</chunk>
<chunk>
<name>heading (rad)</name>
<format>H=%.6f</format>
<type>float</type>
<node>/orientation/heading-deg</node>
<factor>0.0174532925199433</factor> <!-- degrees to radians -->
</chunk>
<chunk>
<name>pitch angle (deg)</name>
<format>P=%03.2f</format>
<node>/orientation/pitch-deg</node>
</chunk>
</output>
</generic>
</PropertyList>
Control the heading bug by sending relative changes separated by newlines:
<?xml version="1.0"?>
<PropertyList>
<generic>
<input>
<line_separator>newline</line_separator>
<chunk>
<name>heading bug</name>
<type>int</type>
<node>/autopilot/settings/heading-bug-deg</node>
<relative>true</relative>
<min>1</min>
<max>360</max>
<wrap>true</wrap>
</chunk>
</input>
</generic>
</PropertyList>
-- writing data in XML syntax -------------------------------------------------
Assuming the file is called $FG_ROOT/Protocol/xmltest.xml, then it could be
used as $ fgfs --generic=file,out,1,/tmp/data.xml,xmltest
<?xml version="1.0"?>
<PropertyList>
<generic>
<output>
<binary_mode>false</binary_mode>
<var_separator>\n</var_separator>
<line_separator>\n</line_separator>
<preamble>&lt;?xml version="1.0"?&gt;\n\n&lt;data&gt;\n</preamble>
<postamble>&lt;/data&gt;\n</postamble>
<chunk>
<format>\t&lt;set&gt;</format>
</chunk>
<chunk>
<node>/position/altitude-ft</node>
<type>float</type>
<format>\t\t&lt;altitude-ft&gt;%.8f&lt;/altitude-ft&gt;</format>
</chunk>
<chunk>
<node>/velocities/airspeed-kt</node>
<type>float</type>
<format>\t\t&lt;airspeed-kt&gt;%.8f&lt;/airspeed-kt&gt;</format>
</chunk>
<chunk>
<format>\t&lt;/set&gt;</format>
</chunk>
</output>
</generic>
</PropertyList>
-- Analyzing the resulting binary packet format -------------------------------
A utility called generic-protocol-analyse can be found under
FlightGear/utils/xmlgrep which can be used to analyze the resulting
data packet for the binary protocol.
The output would be something like:
bintest.xml
Generic binary output protocol packet description:
pos | size | type | factor | description
-----|------|--------|------------|------------------------
0 | 4 | int | | indicated speed (kt)
4 | 4 | float | | pitch att (deg)
8 | 4 | float | | magnetic heading (deg)
12 | 4 | int | | outside air temperarure (degF)
16 | 1 | bool | | autocoord
total package size: 17 bytes

178
docs-mini/README.running Normal file
View File

@@ -0,0 +1,178 @@
Starting the executable
=======================
Unix: runfgfs
Windows: runfgfs.bat
"runfgfs" is a script which runs the Flight Gear executable with
(hopefully) the correct $FG_ROOT directory specified.
First Flight
============
By default, the plane should be looking more or less straight down a
runway, and the mouse cursor should be a regular pointer. The
following steps will help you to get into the air:
- click the right mouse button once, so that a cross cursor
appears (now, the mouse will act as a control yoke)
- while holding down the left mouse button, push the mouse cursor up
until the engine is at full power (the throttle indicator is on the
left side of the HUD), then release the left mouse button
- when the plane is moving fast enough (say, 100 knots for the default
Navion), slowly pull the mouse cursor down (with no buttons pressed)
to raise the elevators until the plane rolls off the runway and into
the air
- while holding down the left mouse button, move the mouse cursor down
slightly to ease up on the throttle, then release the left mouse
button
- move the mouse up, down, and sideways as necessary to establish
level flight -- small movements are best, or you may lose control of
the plane
- click the right mouse button once more, so that a double-arrow
cursor appears (now, the mouse will allow you to look around)
- move the mouse around to look out of the plane at different angles
- press the left mouse button once to return the view to front and
centre
- click the right mouse button *twice*, so that the cross cursor
appears again (you're in yoke mode)
- now that you know how to operate the throttle, ailerons, and
elevators (as well as how to look around), try to circle around and
land back on the runway (best of luck)
Mouse controls
==============
It is possible to manipulate the basic flight controls and the view
using only the mouse. Clicking the right mouse button toggles the
mouse among three different modes:
1. Pointer mode (the default: mouse cursor is a pointer)
2. Yoke mode (mouse cursor is a cross)
3. Look-around mode (mouse pointer is a double arrow)
In yoke mode and look-around mode, the mouse cursor will remain
trapped in the Flight Gear window.
Yoke mode
---------
In yoke mode (mouse cursor as cross), mouse movement adjusts the main
flight controls, depending on which buttons you press.
With no button pressed:
(like a control yoke on an airplane)
- horizontal movement controls the ailerons
- vertical movement controls the elevators
With left button pressed:
- horizontal movement controls the brakes
- vertical movement controls the throttle
With middle button pressed:
- horizontal movement controls the rudder
- vertical movement controls the trim
Look-around mode
----------------
In look-around mode (mouse cursor as double arrow), mouse movement
changes the viewing direction: horizontal movement scrolls the view
horizontally, and vertical movement scrolls the view vertically in the
direction of mouse movement.
To return the view to front and center, click the left mouse button
once.
Keyboard controls
=================
It is also possible to fly using the numeric keypad. There is some
unresolved wierdness with the GLUT libraries and keyboard input, so
for now, the state of the "Num Lock" key is important.
Num Lock Active
---------------
Pg Up/Pg Dn Throttle
Left Arrow/Right Arrow Aileron
Up Arrow/Down Arrow Elevator
Ins/Enter Rudder
"5" Center aileron/elevator/rudder
Home/End Elevator Trim
Num Lock Inactive
-----------------
Shift + <Numeric Keypad Key> Change view
where key is one of:
8 = forward
7 = left/forward
4 = left
1 = left/back
2 = back
3 = right/back
6 = right
9 = right/forward
Brakes
------
Press the "b" key to toggle
Autopilot
---------
Control + A Toggle autopilot altitude lock.
Control + H Toggle autopilot heading lock.
Control + S Toggle autopilot autothrottle.
Control + T Toggle autopilot terrain follow.
Simulation
----------
ESC Quit Flight Gear.
a Increase speedup.
b Toggle brakes.
h Dim HUD.
i Revert to full HUD.
m Increase time warp.
p Toggle pause.
t Increase time warp delta.
v Toggle external view mode.
x Zoom out (narrow field of view).
z Increase visibility.
Shift + A Decrease speedup.
Shift + H Brighten HUD
Shift + I Minimize HUD
Shift + M Decrease time warp.
Shift + P Toggle 2D panel display.
Shift + T Decrease time warp delta.
Shift + W Toggle fullscreen/window mode.
Shift + X Zoom out (widen field of view).
Shift + Z Decrease visibility.
Other
-----
F2 = Reload tile cache.
F6 = Toggle autopilot target location.
F8 = Toggle fog modes (off, fastest, nicest)
F9 = Toggle textures on/off
F10 = Toggle menu
F11 = Set autopilot altitude
F12 = Set autopilot heading

100
docs-mini/README.sound Normal file
View File

@@ -0,0 +1,100 @@
OpenAL setup for general use (Linux)
-------------------------------------
As of the July 2004 release of OpenAL it is best to add at least the
following line to your ~/.openalrc file on Linux because it wil find out
what audio backend to use, starting with the most appropriate:
(define devices '(native alsa sdl esd arts null))
ALSA surround sound (5.1) setup
-------------------------------------
(taken from http://floam.ascorbic.com/how-to/alsa5.1)
Make a ~/.openalrc, we are telling OpenAL that we want surround sound and
we want to use ALSA instead of OSS.
(define speaker-num 4)
(define devices '(alsa))
(define alsa-out-device "surround40:0,0")
IRIX surround sound (5.1) setup
-------------------------------------
To add 4 channel surround sound on IRIX hardware that supports in
directly you can just add the following line to your ~/.openalrc file:
(define speaker-num 4)
To add 4 channel surround sound to IRIX systems that have more than one
stereo output you can add the following section to your ~/.openalrc file
(for a typical O2 configuration):
(define speaker-num 4)
(define native-out-device "Analog Out")
(define native-rear-out-device "Analog Out 2")
or alternatively:
(define speaker-num 4)
(define native-out-device "A3.Speaker")
(define native-rear-out-device "A3.LineOut2")
(Note the following section is obsolete as of the July 2004 release of
OpenAL, since your could command OpenAL to use ALSA or Arts directly)
ALSA and Arts
-------------------------------------
I'm using kernel 2.6.5 with alsa, my sound module is snd-intel8x0. When I ran
fgfs, I'd get quite 'choppy' sound (wasn't smooth, there'd be a couple of
breaks in the sound every second or so). Running arts, and starting fgfs with
"artsdsp fgfs" (from the artsdsp website: "When an application is run under
artsdsp all accesses to the /dev/dsp audio device are intercepted and mapped
into aRts API calls. While the device emulation is not perfect, most
applications work this way, albeit with some degradation in performance and
latency.") would improve the situation, but it seemed to still be choppy.
This command:
echo "fgfs 0 0 direct" >/proc/asound/card0/pcm0p/oss
(from the alsa kernel OSS emulation website:
"The direct option is used, as mentioned above, to bypass the automatic
conversion and useful for MMAP-applications")
made my sound work beautifully when fgfs was run with artsdsp. Running without
artsdsp however (with artsd suspended or killed), would give me no sound at all
(which I find a bit strange)
The following websites might help people with similar troubles:
http://www.alsa-project.org/~iwai/OSS-Emulation.html
http://www.arts-project.org/doc/handbook/artsdsp.html
Computer info:
kernel 2.6.5
flightgear 0.9.4
simgear 0.3.5
plib 1.8.3
soundcard is onboard an asus p4p800-e deluxe mobo (using snd-intel8x0), alsa,
related modules from lsmod:
Module Size Used by
snd_pcm_oss 53252 1
snd_mixer_oss 19968 1 snd_pcm_oss
snd_intel8x0 33476 1
snd_ac97_codec 63492 1 snd_intel8x0
snd_pcm 97408 2 snd_pcm_oss,snd_intel8x0
snd_timer 26112 1 snd_pcm
snd_page_alloc 11396 2 snd_intel8x0,snd_pcm
snd_mpu401_uart 7936 1 snd_intel8x0
snd_rawmidi 24832 1 snd_mpu401_uart
snd_seq_device 8324 1 snd_rawmidi
snd 53892 9 snd_pcm_oss,snd_mixer_oss,snd_intel8x0,snd_ac97_codec,snd_pcm,snd_timer,snd_mpu401_uart,snd_rawmidi,snd_seq_device
soundcore 10208 2 snd

58
docs-mini/README.src Normal file
View File

@@ -0,0 +1,58 @@
majordomo writes:
Subdirectories
==============
Main/
-------
"main()" and GLUT dependent mouse/keyboard/graphics code.
Aircraft/
---------
Structure and code to tie together all the pieces of an aircraft such
as flight model, engine model, panel, controls, etc.
Controls/
---------
Provide a standardized interface to all aircraft controls.
FDM/
-------
Strucures and code to implement various flight models. Provides a
standardized interface to all interesting flight model variabls.
Math/
-----
Contains miscellaneous matrix/vector routines.
Scenery/
--------
Scenery parsing/generating code.
Sound/
------
Sound management code
Timer/
------
Code to handle time and timing of events.
Utils/
------
Miscellaneous utility routines such as a general random number generator
Weather/
--------
Weather management and modeling code.
Win32/
------
Win32 support stuff

128
docs-mini/README.submodels Normal file
View File

@@ -0,0 +1,128 @@
<?xml version="1.0"?>
<!-- Submodels are objects which can be dropped or launched from the user
aircraft. The trigger is a boolean property, which you define, which when
"true" causes the submodel to be released/launched.
A submodel will create an AIBallistic object which will follow a ballistic
path. By default one submodel will be released when the corresponding
trigger is "true".
The initial conditions (IC) define the object's starting point (relative
to the user aircraft's "reported position"), and its initial speed and
direction (relative to the user aircraft). If you want to release many
similar objects with similar IC, then you may use the <repeat>, <delay>
and <count> properties to define this. The allowed properties are:
<name> The name of the submodel.
<model> The path to the visual model.
<trigger> The property which will act as the trigger.
<speed> Initial speed, in feet/sec, relative to user aircraft.
<repeat> Set "true" if you want multiple releases of this submodel.
<delay> Time, in seconds, between repeated releases.
<count> Number of submodels available for multiple release.
-1 defines an unlimited number.
<slaved> Not used yet.
<x-offset> Submodel's initial fore/aft position relative to user
aircraft. Fore is positive.
<y-offset> Submodel's initial left/right position relative to user
aircraft. Right is positive.
<z-offset> Submodel's initial up/down position relative to user
aircraft. Up is positive.
<yaw-offset> Submodel's initial azimuth, in degrees, relative to user
aircraft'snose. Right is positive.
<pitch-offset> Submodel's initial elevation, in degrees, relative to user
aircraft's pitch. Up is positive.
<life> Life span in seconds. Default is 900.0.
<buoyancy> In ft/sec/sec. Works opposite acceleration of gravity.
For example, if set to 32 the submodel will feel no
gravity. If greater than 32 the object will rise.
Default is 0.
<wind> Set to true if you want the submodel to react to the wind.
Default is "false".
<cd> The Coeffient of Drag. Varies with submodel shape - 0.295 for a bullet,
0.045 for an airfoil. Enter an appropriate value. Defaults to 0.295.
<eda> Effective drag area (sq ft). Usually the cross-sectional area of the
submodel normal to the airflow.
<weight> The weight of the submodel (lbs). NOT set to 0 on submodel release.You
may wish to set this value to 0 by means of key bindings or Nasal script.
Defaults to 0.25.
<contents> The path to the contents of a submodel. The contents must be in lbs.
Intended for use with drop tanks. The property value will be set
to 0 on release of the submodel: do not also set to 0 elsewhere e.g.
in key bindings. Defaults to 0.
-->
<PropertyList>
<submodel>
<name>left gun</name>
<model>Models/Geometry/tracer.ac</model>
<trigger>ai/submodels/submodel[0]/trigger</trigger>
<speed>2750.0</speed>
<repeat>true</repeat>
<delay>0.25</delay>
<count>100</count>
<x-offset>1.0</x-offset>
<y-offset>-7.0</y-offset>
<z-offset>-2.0</z-offset>
<yaw-offset>0.4</yaw-offset>
<pitch-offset>1.8</pitch-offset>
<life>2.0</life>
</submodel>
<submodel>
<name>right gun</name>
<model>Models/Geometry/tracer.ac</model>
<trigger>ai/submodels/submodel[0]/trigger</trigger>
<speed>2750.0</speed>
<repeat>true</repeat>
<delay>0.25</delay>
<count>100</count>
<x-offset>1.0</x-offset>
<y-offset>7.0</y-offset>
<z-offset>-2.0</z-offset>
<yaw-offset>-0.4</yaw-offset>
<pitch-offset>1.8</pitch-offset>
<life>2.0</life>
</submodel>
<submodel>
<name>droptank-l</name>
<model>Aircraft/Hunter/Models/droptank-100gal.ac</model>
<trigger>controls/armament/station[0]/jettison-all</trigger>
<speed>0</speed>
<repeat>false</repeat>
<count>1</count>
<x-offset>0.820</x-offset>
<y-offset>-9.61</y-offset>
<z-offset>-2.39</z-offset>
<yaw-offset>0</yaw-offset>
<pitch-offset>0</pitch-offset>
<wind>false</wind>
<eda>2.11348887</eda>
<weight>170</weight>
<cd>0.045</cd>
<contents>consumables/fuel/tank[2]/level-lbs</contents>
</submodel>
<submodel>
<name>droptank-r</name>
<model>Aircraft/Hunter/Models/droptank-100gal.ac</model>
<trigger>controls/armament/station[1]/jettison-all</trigger>
<speed>0</speed>
<repeat>false</repeat>
<count>1</count>
<x-offset>0.820</x-offset>
<y-offset>9.61</y-offset>
<z-offset>-2.39</z-offset>
<yaw-offset>0</yaw-offset>
<pitch-offset>0</pitch-offset>
<wind>false</wind>
<eda>2.11348887</eda>
<weight>170</weight>
<cd>0.045</cd>
<contents>consumables/fuel/tank[3]/level-lbs</contents>
</submodel>
</PropertyList>

82
docs-mini/README.tutorial Normal file
View File

@@ -0,0 +1,82 @@
The tutorial system is a Nasal script that runs tutorials defined by a set
of properties under /sim/tutorial. The tutorials are automatically picked up by
the GUI, and can be found under the Help menu item.
Tutorials are typically tied to specific aircraft and defined in a
separate XML file as follows:
<sim>
<tutorial include="c172-tutorial.xml"></tutorial>
</sim>
Each tutorial is defined by a "tutorial" leaf under /tutorial, and consists of
the following elements.
name - The name of the tutorial, used in the GUI
description - A plain-text description of the tutorial, displayed in the GUI.
audio-dir - (Optional) The directory (relative to FG_ROOT) to pick up any
wav files used.
timeofday - (Optional) .Time of day (morning, noon, evening...). Used to
set the initial tutorial state.
presets - (Optional) Properties to be set under /sim/presets, followed
by a presets-commit command. Used to set the initial tutorial
state. e.g. airport-id, runway, heading-deg
init - (Optional) Initial tutorial state properties to set.
Consists of one or more set nodes (see below for details).
step - A tutorial step (see below for details)
endtext - Text to display at the end of the tutorial
endtext-voice - .wav filename to play at the end of the tutorial
endtext-tts - Text to send to text-to-speech engine at the end of tutorial
The bulk of the tutorial definition consists of step definitions. These are
discreet stages within the tutorial lasting at least 5 seconds. Typically the
consist of an instruction from the FG instructor, some exit criteria used to
check that the user has performed the step correctly and can move to the next
step, and a series of error conditions to check the user isn't deviating.
Each step consists of the following elements:
instruction - Text to display to the user when they enter the step, and
when they have still to fulfill the exit criteria
instruction-tts - text to send to the text-to-speech (TTS) engine
instruction-voice - .wav filename to play
set - (Optional) properties to set when entering the step. May
be more than one.
error - Error conditions, consisting of one or more check nodes
with messages (see below)
exit - Exit criteria, consisting of one or more check nodes
without messages.
Set nodes consist of
prop - The property name to set
val - The value to set.
For example
<set>
<prop>/controls/engines/engine/throttle</prop>
<val>0.5</val>
</set>
Check nodes consist of a property to check, a single operator, and (for error
nodes) a message to display if the check evaluates to true.
prop - The property to check
lt - the value to check the property is less than
gt - the value to check the property is greater than
eq - the value to check the property is equal to.
msg - (error node only) text message to display
msg-tts - (error node only, optional) message to send to TTS engine
msg-voice - (error node only, optional) .wav filename to play
For example:
<check>
<prop>/controls/engines/engine/throttle</prop>
<lt>0.95</lt>
<msg>Apply full throttle for take-off.</msg>
</check>

1170
docs-mini/README.uiuc Normal file
View File

File diff suppressed because it is too large Load Diff

654
docs-mini/README.xmlpanel Normal file
View File

@@ -0,0 +1,654 @@
Users Guide to FlightGear panel configuration
Version 0.7.7, May 16 2001
Author: John Check <j4strngs@rockfish.net>
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. Corrections and additions
are encouraged.
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 simulation. 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 but be limited to C172 instrumentation.
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. Some major changes and additions were
made during the course of version 0.7.7 necessitating a rewrite and
expansion of this document.
About The Property Manager:
--------------------------
While not absolutely necessary in order to create aircraft panels,
some familiarity with the property manager is beneficial....
FlightGear provides a hierarchical representation of all aspects of
the state of the running simulation that is known as the property
tree. Some properties, such as velocities are read only. Others such
as the frequencies to which the navcom radios are tuned or the
position of control surfaces can be set by various means. FlightGear
can optionally provide an interface to these properties for external
applications such as Atlas, the moving map program, or even lowly
telnet, via a network socket. Data can even be placed on a serial port
and connected to, say a GPS receiver. Aside from its usefulness in a
flight training context, being able to manipulate the property tree on
a running copy of FG allows for switching components on the fly, a
positive boon for panel authors. To see the property tree start FG
with the following command line:
fgfs --props=socket,bi,5,localhost,5500,tcp
Then use telnet to connect to localhost on port 5500. You can browse
the tree as you would a filesystem.
XML and the Property Manager:
----------------------------
Panel instruments interface with the property tree to get/set values
as appropriate. Properties for which FG doesn't yet provide a value
can be created by simply making them up. Values can be adjusted using
the telnet interface allowing for creation and testing of instruments
while code to drive them is being developed.
If fact, the XML configuration system allows a user to combine
components such as flight data model, aircraft exterior model, heads
up display, and of course control panel. Furthermore, such a
preconfigured aircraft.xml can be included into a scenario with
specific flight conditions. These can be manually specified or a FG
session can be saved and/or edited and reloaded later. Options
specified in these files can be overridden on the command line. For
example:
--prop:/sim/panel/path=Aircraft/c172/Panels/c172-panel.xml
passed as an option, would override a panel specified elsewhere.
Property tree options all have the same format, specify the node and
supply it a value.
The order of precedence for options is thus:
Source Location Format
------ -------- ------
command line
.fgfsrc Users home directory. command line options
system.fgfsrc $FG_ROOT "" ""
preferences.xml $FG_ROOT XML property list
Loading Panels on the fly:
-------------------------
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. Panels can be switched on the fly by setting the
/sim/panel/path property value and reloading.
Regarding Window Geometry:
-------------------------
For the sake of simplicity the FGFS window is always considered to be
1024x768 so all x/y values for instrument placement should relative to
these dimensions. Since FG uses OpenGL 0,0 represents the lower left
hand corner of the screen. Panels may have a virtual size larger than
1024x768. Vertical scrolling is accomplished with
Shift+F5/F6. Horizontal scrolling is via Shift+F7/F8. An offset should
be supplied to set the default visible area. It is possible to place
items to overlap the 3D viewport.
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
almost always found in pairs, with the closing tag having a slash
prefixing the tag name, i.e </PropertyList>. The exception is the tag
representing an aliased property. In this case a slash is prepended to
the closing angle bracket. (see section Aliasing)
The top level panel configuration file is composed of a <name>, a
<background> texture and zero or more <instruments>.Earlier versions
required instruments to have a unique name and a path specification
pointing to the instruments configuration file.
[ Paths are relative to $FG_ROOT (the installed location of FGFS data files.) ]
[ Absolute paths may be used.Comments are bracketed with <!-- -->. ]
Old style instrument call in top level panel.xml:
------------------------------------------------
<clock> <!-- required "unique_name" -->
<path>Aircraft/c172/Instruments/clock.xml</path>
<x>110</x> <!-- required horizontal placement -->
<y>320</y> <!-- required vertical placement -->
<w>72</w> <!-- optional width specification -->
<h>72</h> <!-- optional height specification -->
</clock>
The difference between the old and new styles, while subtle, is rather
drastic. The old and new methods are indeed incompatible. I cover the
old style only to acknowledge the incompatibility. This section will
be removed after the next official FGFS release.
New Style Example Top Level Panel Config:
----------------------------------------
<PropertyList>
<name>Example Panel</name>
<background>Aircraft/c172/Panels/Textures/panel-bg.rgb</background>
<w>1024</w> <!-- virtual width -->
<h>768</h> <!-- virtual height -->
<y-offset>-305</y-offset> <!-- hides the bottom part -->
<view-height>172</view-height> <!-- amount of overlap between 2D panel and 3D viewport -->
<instruments> <!-- from here down is where old and new styles break compatibility -->
<instrument include="../Instruments/clock.xml">
<name>Chronometer</name> <!-- currently optional but strongly recommended -->
<x>150</x> <!-- required horizontal placement -->
<y>645</y> <!-- required vertical placement -->
<w>72</w> <!-- optional width specification -->
<h>72</h> <!-- optional height specification -->
</instrument>
</instruments>
</PropertyList>
Indexed Properties
------------------
This is a lot to do with the compatibility break so lets get it out of
the way. The property manager now assigns incremental indices to
repeated properties with the same parent node, so that
<PropertyList>
<x>1</x>
<x>2</x>
<x>3</x>
</PropertyList>
shows up as
/x[0] = 1
/x[1] = 2
/x[2] = 3
This means that property files no longer need to make up a separate
name for each item in a list of instruments, layers, actions,
transformations, or text chunks. In fact, the new panel I/O code now
insists that every instrument have the XML element name "instrument",
every layer have the name "layer", every text chunk have the name
"chunk", every action have the name "action", and every transformation
have the name "transformation" -- this makes the XML more regular (so
that it can be created in a DTD-driven tool) and also allows us to
include other kinds of information (such as doc strings) in the lists
without causing confusion.
Inclusion:
----------
The property manager now supports file inclusion and aliasing.
Inclusion means that a node can include another property file as if it
were a part of the current file. To clarify how inclusion works,
consider the following examples:
If bar.xml contains
<PropertyList>
<a>1</a>
<b>
<c>2</c>
</b>
</PropertyList>
then the declaration
<foo include="../bar.xml">
</foo>
is exactly equivalent to
<foo>
<a>1</a>
<b>
<c>2</c>
</b>
</foo>
However, it is also possible to selectively override properties in the
included file. For example, if the declaration were
<foo include="../bar.xml">
<a>3</a>
</foo>
then the property manager would see
<foo>
<a>3</a>
<b>
<c>2</c>
</b>
</foo>
with the original 'a' property's value replaced with 3.
This new inclusion feature allows property files to be broken up and
reused arbitrarily -- for example, there might be separate cropping
property lists for commonly-used textures or layers, to avoid
repeating the information in each instrument file.
Aliasing
--------
Properties can now alias other properties, similar to a symbolic link
in Unix. When the target property changes value, the new value will
show up in the aliased property as well. For example,
<PropertyList>
<foo>3</foo>
<bar alias="/foo"/>
</PropertyList>
will look the same to the application as
<PropertyList>
<foo>3</foo>
<bar>3</bar>
</PropertyList>
except that when foo changes value, bar will change too.
The combination of inclusions and aliases is very powerful, because it
allows for parameterized property files. For example, the XML file for
the NAVCOM radio can include a parameter subtree at the start, like
this:
<PropertyList>
<params>
<comm-freq-prop>/radios/comm1/frequencies/selected</comm-freq-prop>
<nav-freq-prop>/radios/nav1/frequencies/selected</comm-freq-prop>
</params>
...
<chunk>
<type>number-value</type>
<property alias="/params/nav-freq-prop"/>
</chunk>
...
</PropertyList>
Now, the same instrument file can be used for navcomm1 and navcomm2,
for example, simply by overriding the parameters at inclusion:
<instrument include="../Instruments/navcomm.xml">
<params>
<comm-freq-prop>/radios/comm1/frequencies/selected</comm-freq-prop>
<nav-freq-prop>/radios/nav1/frequencies/selected</comm-freq-prop>
</params>
</instrument>
<instrument include="../Instruments/navcomm.xml">
<params>
<comm-freq-prop>/radios/comm2/frequencies/selected</comm-freq-prop>
<nav-freq-prop>/radios/nav2/frequencies/selected</comm-freq-prop>
</params>
</instrument>
Instrument Architecture:
-----------------------
Instruments are defined in separate configuration files. An instrument
consists of a base width and height, one or more stacked layers, and
zero or more actions. Base dimensions are specified as follows:
<PropertyList> <!-- remember, all xml files start like this -->
<name>Airspeed Indicator</name> <!-- names are good -->
<w-base>128</w-base> <!-- required width spec-->
<h-base>128</h-base> <!-- required height spec-->
<layers> <!-- begins layers section -->
Height and width can be overriden in the top level panel.xml by
specifying <w> and <h>. Transformations are caculated against the base
size regardless of the display size. This ensures that instruments
remain calibrated
Textures:
--------
FG uses red/green/blue/alpha .rgba files for textures. Dimensions for
texture files should be power of 2 with a maximum 8:1 aspect ratio.
The lowest common denominator for maximum texture size is 256 pixels.
This is due to the limitations of certain video accelerators, most
notably those with 3Dfx chipset such as the Voodoo2.
Instrument Layers**:
-------------------
The simplest layer is a <texture>. These can be combined in <switch> layers
<texture>
A texture layer looks like this:
<layer> <!-- creates a layer -->
<name>face</name>
<texture> <!-- defines it as a texture layer -->
<path>Aircraft/c172/Instruments/Textures/faces-2.rgb</path>
<x1>0</x1> <!-- lower boundary for texture cropping-->
<y1>0.51</y1> <!-- left boundary for texture cropping-->
<x2>0.49</x2> <!-- upper boundary for texture cropping-->
<y2>1.0</y2> <!-- right boundary for texture cropping-->
</texture> <!-- closing texure tag -->
</layer> <!-- closing layer tag -->
The texture cropping specification is represented as a decimal. There
is a table at the end of this document for converting from pixel
coordinates to percentages.
This particular layer, being a gauge face has no transformations
applied to it. Layers with that aren't static *must* include <w> and
<h> parameters to be visible.
<type> May be either text or switch..
<type>switch</type>
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/Aircraft/c172/Instruments/brake.xml.
<layer>
<name>Brake light</name>
<type>switch</type> <!-- define layer as a switch -->
<property>/controls/brakes</property> <!-- tie it to a property -->
<layer1> <!-- layer for true state -->
<name>on</name> <!-- label to make life easy -->
<texture> <!-- layer1 of switch is a texture layer -->
<path>Aircraft/c172/Instruments/Textures/brake.rgb</path>
<x1>0.25</x1>
<y1>0.0</y1>
<x2>0.5</x2>
<y2>0.095</y2>
</texture>
<w>64</w> <!-- required width - layer isn't static -->
<h>24</h> <!-- required height - layer isn't static -->
</layer1> <!-- close layer1 of switch -->
<layer2> <!-- layer for false state -->
<name>off</name>
<texture>
<path>Aircraft/c172/Instruments/Textures/brake.rgb</path>
<x1>0.0</x1>
<y1>0.0</y1>
<x2>0.25</x2>
<y2>0.095</y2>
</texture>
<w>64</w>
<h>24</h>
</layer2>
</layer>
Switches can have more than 2 states. This requires nesting one switch
inside another. One could make, for example, a 3 color LED by nesting
switch layers.
<type>text</type>
A text layer may be static, as in a label, generated from a property
or a combination of both. This example is a switch that contains both
static and dynamic text:
<layer1> <!-- switch layer -->
<name>display</name>
<type>text</type> <!-- type == text -->
<point-size>12</point-size> <!-- font size -->
<color> <!-- specify rgb values to color text -->
<red>1.0</red>
<green>0.5</green>
<blue>0.0</blue>
</color> <!-- close color section -->
<chunks> <!-- sections of text are referred to as chunks -->
<chunk> <!-- first chunk of text -->
<type>number-value</type> <!-- value defines it as dynamic -->
<property>/radios/nav1/dme/distance</property> <!-- ties it to a property -->
<scale>0.00053995680</scale> <!-- convert between statute and nautical miles? -->
<format>%5.1f</format> <!-- define format -->
</chunk>
</chunks>
</layer1>
<layer2> <!-- switch layer -->
<name>display</name>
<type>text</type> <!-- type == text -->
<point-size>10</point-size> <!-- font size -->
<color> <!-- specify rgb values to color text -->
<red>1.0</red>
<green>0.5</green>
<blue>0.0</blue>
</color> <!-- close color section -->
<chunks> <!-- sections of text are referred to as chunks -->
<chunk> <!-- first chunk of text -->
<type>literal</type> <!-- static text -->
<text>---.--</text> <!-- fixed value -->
</chunk>
</chunks>
</layer2>
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>. Offsets are relative to the center of the instrument. A
shift without an offset has no effect. For example, let's say we have
a texure that is a circle. If we use this texture in two layers, one
defined as having a size of 128x128 and the second layer is defined as
64x64 and neither is supplied a shift and offset the net result
appears as 2 concentric circles.
About Transformations and Needle Placement:
------------------------------------------
When describing placement of instrument needles, a transformation
offset must be applied to shift the needles fulcrum or else the needle
will rotate around it's middle. The offset will be of <type> x-shift
or y-shift depending on the orientation of the needle section in the
cropped texture.
This example comes from the altimeter.xml
<layer>
<name>long needle (hundreds)</name> <!-- the altimeter has more than one needle -->
<texture>
<path>Aircraft/c172/Instruments/Textures/misc-1.rgb</path>
<x1>0.8</x1>
<y1>0.78125</y1>
<x2>0.8375</x2>
<y2>1.0</y2>
</texture>
<w>8</w>
<h>56</h>
<transformations> <!-- begin defining transformations -->
<transformation> <!-- start definition of transformation that drives the needle -->
<type>rotation</type>
<property>/steam/altitude</property> <!-- bind it to a property -->
<max>100000.0</max> <!-- upper limit of instrument -->
<scale>0.36</scale> <!-- once around == 1000 ft -->
</transformation> <!-- close this transformation -->
<transformation> <!-- this one shifts the fulcrum of the needle -->
<type>y-shift</type> <!-- y-shift relative to needle -->
<offset>24.0</offset> <!-- amount of shift -->
</transformation>
</transformations>
</layer>
This needles has its origin in the center of the instrument. If the
needles fulcrum was towards the edge of the instrument, the
transformations to place the pivot point must precede those which
drive the needle,
Interpolation
-------------
Non linear transformations are now possible via the use of
interpolation tables.
<transformation>
...
<interpolation>
<entry>
<ind>0.0</ind> <!-- raw value -->
<dep>0.0</dep> <!-- displayed value -->
</entry>
<entry>
<ind>10.0</ind>
<dep>100.0</dep>
</entry>
<entry>
<ind>20.0</ind>
<dep>-5.0</dep>
</entry>
<entry>
<ind>30.0</ind>
<dep>1000.0</dep>
</entry>
</interpolation>
</transformation>
Of course, interpolation tables are useful for non-linear stuff, as in
the above example, but I kind-of like the idea of using them for
pretty much everything, including non-trivial linear movement -- many
instrument markings aren't evenly spaced, and the interpolation tables
are much nicer than the older min/max/scale/offset stuff and should
allow for a more realistic panel without adding a full equation parser
to the property manager.
If you want to try this out, look at the airspeed.xml file in the base
package, and uncomment the interpolation table in it for a very funky,
non-linear and totally unreliable airspeed indicator.
Actions:
-------
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.
The x/y placement for actions specifies the origin of the lower left
corner. In the following example the first action sets up a hotspot
32 pixels wide and 16 pixels high. It lower left corner is placed 96
pixels (relative to the defined base size of the instrument) to the
right of the center of the instrument. It is also 32 pixels below the
centerline of the instrument. The actual knob texture over which the
action is superimposed is 32x32. Omitted here is a second action,
bound to the same property, with a positive increment value. This
second action is placed to cover the other half of the knob. The
result is that clicking on the left half of the knob texture decreases
the value and clicking the right half increases the value. Also
omitted here is a second pair of actions with the same coordinates but
a larger increment value. This second pair is bound to a different
mouse button. The net result is that we have both fine and coarse
adjustments in the same hotspot, each bound to a different mouse
button.
These examples come from the radio stack:
<actions> <!-- open the actions section -->
<action> <!- first action -->
<name>small nav frequency decrease</name>
<type>adjust</type>
<button>0</button> <!-- bind it to a mouse button -->
<x>96</x> <!-- placement relative to instrument center -->
<y>-32</y>
<w>16</w> <!-- size of hotspot -->
<h>32</h>
<property>/radios/nav1/frequencies/standby</property> <!-- bind to a property -->
<increment>-0.05</increment> <!-- amount of adjustment per mouse click -->
<min>108.0</min> <!-- lower range -->
<max>117.95</max> <!-- upper range -->
<wrap>1</wrap> <!-- boolean value -- value wraps around when it hits bounds -->
</action>
<action>
<name>swap nav frequencies</name>
<type>swap</type> <!-- define type of action -->
<button>0</button>
<x>48</x>
<y>-32</y>
<w>32</w>
<h>32</h>
<property1>/radios/nav1/frequencies/selected</property1> <!-- properties to toggle between -->
<property2>/radios/nav1/frequencies/standby</property2>
</action>
<action>
<name>ident volume on/off</name>
<type>adjust</type>
<button>1</button>
<x>40</x>
<y>-24</y>
<w>16</w>
<h>16</h>
<property>/radios/nav1/ident</property> <!-- this property is for Morse code identification of nav beacons -->
<increment>1.0</increment> <!-- the increment equals the max value so this toggles on/off -->
<min>0</min>
<max>1</max>
<wrap>1</wrap> <!-- a shortcut to avoid having separate actions for on/off -->
</action>
</actions>
More About Textures:
-------------------
As previously stated, the usual size instrument texture files in FGFS
are 256x256 pixels, red/green/blue/alpha format. However the mechanism
for specifying texture cropping coordinates is decimal in nature. 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.
The following table can be used to calculate texture cropping
specifications.
# of divisions | width in pixels | decimal specification
per axis
1 = 256 pixels 1
2 = 128 pixels, 0.5
4 = 64 pixels, 0.25
8 = 32 pixels, 0.125
16 = 16 pixels, 0.0625
32 = 8 pixels, 0.03125
64 = 4 pixels, 0.015625
128 = 2 pixels, 0.0078125
A common procedure for generating gauge faces is to use a vector
graphics package such as xfig, exporting the result as a postscript
file. 3D modeling tools may also be used and I prefer them for pretty
items such as levers, switches, bezels and so forth. Ideally, the
size of the item in the final render should be of proportions that fit
into the recommended pixel widths. The resulting files can be
imported into a graphics manipulation package such as GIMP, et al for
final processing.
How do I get my panels/instruments into the base package?
-------------------------------------------------------
Cash bribes always help ;) Seriously though, there are two main
considerations. Firstly, original artwork is a major plus since you
as the creator can dictate the terms of distribution.All Artwork must
have a license compatible with the GPL. Artwork of unverifiable
origin is not acceptable. Secondly, texture sizes must meet the
lowest common denominator of 256e2 pixels. Artwork from third parties
may be acceptable if it meets these criteria.
* 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).

241
docs-mini/README.xmlparticles Normal file
View File

@@ -0,0 +1,241 @@
Document started 27/01/2008 by Tiago Gusm<73>o
Updated 02/02/2008 to reflect syntax changes
Updated 03/02/2008 to add trails (connected particles)
This is a short specification/tutorial to define particle systems in FlightGear using XML
Meaningless example (what i had accumulated due to tests):
<particlesystem>
<name>fuel</name>
<!-- <texture>particle.rgb</texture> -->
<emissive>false</emissive>
<lighting>true</lighting>
<offsets>
<x-m>35</x-m>
<y-m>-0.3</y-m>
<z-m>0</z-m>
<!--<pitch-deg>90</pitch-deg>-->
</offsets>
<!--<condition>
<and>
<equals>
<property>engines/engine/smoking</property>
<value>true</value>
</equals>
<less-than>
<property>position/altitude-agl-ft</property>
<value>12000</value>
</less-than>
</and>
</condition>-->
<attach>world</attach>
<placer>
<type>point</type>
</placer>
<shooter>
<theta-min-deg>84</theta-min-deg>
<theta-max-deg>86</theta-max-deg>
<phi-min-deg>-1.5</phi-min-deg>
<phi-max-deg>1.5</phi-max-deg>
<speed>
<value>10</value>
<spread>2.5</spread>
</speed>
<rotation-speed>
<x-min-deg-sec>0</x-min-deg-sec>
<y-min-deg-sec>0</y-min-deg-sec>
<z-min-deg-sec>0</z-min-deg-sec>
<x-max-deg-sec>0</x-max-deg-sec>
<y-max-deg-sec>0</y-max-deg-sec>
<z-max-deg-sec>0</z-max-deg-sec>
</rotation-speed>
</shooter>
<counter>
<particles-per-sec>
<value>1</value>
<spread>0</spread>
</particles-per-sec>
</counter>
<align>billboard</align>
<particle>
<start>
<color>
<red>
<value>0.9</value>
</red>
<green>
<value>0.09</value>
</green>
<blue>
<value>0.09</value>
</blue>
<alpha>
<value>1.0</value>
</alpha>
</color>
<size>
<value>0.25</value>
</size>
</start>
<end>
<color>
<red>
<value>1</value>
</red>
<green>
<value>0.1</value>
</green>
<blue>
<value>0.1</value>
</blue>
<alpha>
<value>0.0</value>
</alpha>
</color>
<size>
<value>4</value>
</size>
</end>
<life-sec>
<value>10</value>
</life-sec>
<mass-kg>0.25</mass-kg>
<radius-m>0.1</radius-m>
</particle>
<program>
<fluid>air</fluid>
<gravity type="bool">true</gravity>
<wind type="bool">true</wind>
</program>
</particlesystem>
Stick this inside any model XML like it was an animation and it should
work (notice the condition requires wheel on the ground)
Specification:
Note:
<VALUEORPROP/> means you can either specify a property with factor and
offset (result = (prop*factor)+offset ) in the usual way
<particlesystem> = the base tag
<type>string</type> can be "normal" or "trail", normal is the usual quad particles, trail is a string of connected quads, see note near the end
<offsets> = this places the source of the particles (the emitter) in relation to the perhaps already offsetted model (see model-howto.html for details)
<x-m>float</x-m>
<y-m>float</y-m>
<z-m>float</z-m>
<pitch-deg>float</pitch-deg>
<roll-deg>float</roll-deg>
<heading-deg>float</heading-deg>
</offsets>
<condition> =a typical condition that if not true stops particles from being emitted (PPS=0)
....
</condition>
<name>string</name> = the name of the particle system (so it can then be referenced by animations)
<attach>string</attach> = can be "world" or "local". "world means the particles aren't "physically linked" to the model (necessary for use outside moving models), "local" means the opposite (can be used for static objects or inside moving objects)
<texture>string</texture> = the texture path relative to the XML file location
<emissive>bool</emissive> = self-explanatory
<lighting>bool</lighting> = yet to be tested, but seems obvious
<align>string</align> = can be "billboard" or "fixed", still being worked, don't use
<placer> = where particles are born
<type>string</type> = can be "sector" (inside a circle), "segments"(user-defined segments) and "point" (default)
*<radius-min-m>float</radius-min-m> = only for sector, inner radius at which particles appear
*<radius-max-m>float</radius-max-m> = only for sector, outer radius at which particles appear
*<phi-min-deg>float</phi-min-deg> = only for sector, starting angle of the slide at which particles appear
*<phi-max-deg>float</phi-max-deg> = only for sector, ending angle of the slide at which particles appear
<segments> = only for segments, encloses sequential points that form segments
<vertex> = specifies one point, put as many as you want
<x-m>float</x-m>
<y-m>float</y-m>
<z-m>float</z-m>
</vertex>
....
<vertex>
...
</vertex>
</segments>
</placer>
<shooter> = the shooter defines the initial velocity vector for your particles
*<theta-min-deg>float</theta-min-deg> = horizontal angle limits of the particle cone
*<theta-max-deg>float</theta-max-deg>
*<phi-min-deg>float</phi-min-deg> = vertical angle limits of the particle cone
*<phi-max-deg>float</phi-max-deg> for an illustration of theta/phi see http://www.cs.clemson.edu/~malloy/courses/3dgames-2007/tutor/web/particles/particles.html
<speed-mps> = the scalar velocity (meter per second)
<VALUEORPROP/> = see note
*<spread> the "tolerance" in each direction so values are in the range [value-spread, value+spread]
</speed-mps>
<rotation-speed> = the range of initial rotational speed of the particles
*<x-min-deg-sec>float</x-min-deg-sec>
*<y-min-deg-sec>float</y-min-deg-sec>
*<z-min-deg-sec>float</z-min-deg-sec>
*<x-max-deg-sec>float</x-max-deg-sec>
*<y-max-deg-sec>float</y-max-deg-sec>
*<z-max-deg-sec>float</z-max-deg-sec>
</rotation-speed>
</shooter>
<counter>
<particles-per-sec>
<VALUEORPROP/> = see note
*<spread> the "tolerance" in each direction so values are in the range [value-spread, value+spread]
</particles-per-sec>
</counter>
<particle> = defines the particle properties
<start>
<color> = initial color (at time of emission)
<red><VALUEORPROP/></red> = color component in normalized value [0,1]
<green><VALUEORPROP/></green>
<blue><VALUEORPROP/></blue>
<alpha><VALUEORPROP/></alpha>
</color>
<size> = as above, but for size
<VALUEORPROP/>
</size>
</start>
<end>
<color> = final color (at the end of the particle life)
<red><VALUEORPROP/></red>
<green><VALUEORPROP/></green>
<blue><VALUEORPROP/></blue>
<alpha><VALUEORPROP/></alpha>
</color>
<size>
<VALUEORPROP/>
</size>
</end>
*<life-sec> = the time the particles will be alive, in seconds
<VALUEORPROP/>
*</life-sec>
*<radius-m>float</radius-m> = each particles is physically treated as a sphere with this radius
*<mass-kg>float</mass-kg> = mass in KG
</particle>
<program> = defines external forces acting upon a particle
<fluid>string<fluid> = can be "air" or "water"
<gravity>bool</gravity> = can be "true" or "false". uses standard gravity
<wind>bool</wind> = can be "true" or "false". uses user position wind (not the model position, but shouldn't be noticeable, you want to disabled it when using local attach)
</program>
</particles>
Remarks:
Don't forget you can use existing animations with particles, so if you want to direct or translate the emitter, just use translate, rotate, spin and so on (other animations might have interesting effects too I guess)
Particle XML should be compatible with plib, as the tags will be ignored (you might get some warning if you attach them to animations though)
Try not to use a lot of particles in a way that fills the screen, that will demand lots of fill rate and hurt FPS
If you don't use any properties nor conditions, your particle system doesn't need to use a callback a so it's slightly better on the CPU (mostly useful for static models)
If your particle lifetime is too big you might run out of particles temporarily (still being investigated)
Use mass and size(radius) to adjust the reaction to gravity and wind (mass/size = density)
Although at the moment severe graphical bugs can be seen in the trails, they are usable. Consider your options correctly! You should consider giving them no initial velocity and most important, no spread, otherwise particles will race and the trail will fold. Start simple (no velocities and forces) and work your way up.

304
docs-mini/README.xmlsound Normal file
View File

@@ -0,0 +1,304 @@
Users Guide to FlightGear sound configuration
Version 0.9.8, October 30, 2005
Author: Erik Hofman <erik at ehofman dot com>
This document is an attempt to describe the configuration of
FlightGear flight simulator's aircraft sound in XML.
Sound Architecture:
------------------
All of the sound configuration files are XML-encoded* property lists.
The root element of each file is always named <PropertyList>. Tags are
almost always found in pairs, with the closing tag having a slash
prefixing the tag name, i.e </PropertyList>. The exception is the tag
representing an aliased property. In this case a slash is prepended to
the closing angle bracket. (see section Aliasing)
The top level sound configuration file is composed of a <fx>, a
<name>, a <path> sound file and zero or more <volume> and/or <pitch>
definitions.
[ Paths are relative to $FG_ROOT (the root of the installed base package .) ]
[ Absolute paths may be used. Comments are bracketed with <!-- -->. ]
A limited sound configuration file would look something like this:
<PropertyList>
<fx>
<engine>
<name>engine</name>
<path>Sounds/wasp.wav</path>
<mode>looped</mode>
<condition>
<property>/engines/engine/running</property>
</condition>
<volume>
<property>/engines/engine/mp-osi</property>
<factor>0.005</factor>
<min>0.15</min>
<max>0.5</max>
<offset>0.15</offset>
</volume>
<pitch>
<property>/engines/engine/rpm</property>
<factor>0.0012</factor>
<min>0.3</min>
<max>5.0</max>
<offset>0.3</offset>
</pitch>
</engine>
</fx>
</PropertyList>
This would define an engine sound event handler for a piston engine driven
aeroplane. The sound representing the engine is located in $FG_ROOT/Sounds
and is named wasp.wav. The event is started when the property
/engines/engine/running becomes non zero.
When that happens, the sound will be played looped (see <mode>) until the
property returns zero again. As you can see the volume is mp-osi dependent,
and the pitch of the sound depends on the engine rpm.
Configuration description:
-------------------------
<fx>
Named FX subtree living under /sim/sound
< ... >
This is the event separator. The text inside the brackets
can be anything. Bit it is advised to give it a meaningful name
like: crank, engine, rumble, gear, squeal, flap, wind or stall
The value can be defined multiple times, thus anything which is
related may have the same name (grouping them together).
<name>
This defines the name of the event. This name is used internally
and, although it can me defined multiple times in the same file,
should normally have an unique value.
Multiple definitions of the same name will allow multiple sections
to interfere in the starting and stopping of the sample.
This method can't be used to control the pitch or volume of the
sample, but instead multiple volume or pitch section should be
included inside the same event.
The types "raise" and "fall" will stop the playback of the sample
regardless of any other event. This means that when the type "raise"
is supplied, sample playback will stop when the event turns false.
Using the type "fall" will stop playback when the event turns true.
IMPORTANT:
If the trigger is used for anything else but stopping the sound
at a certain event, all sections with the same name *should* have
exactly the same sections for everything but property and type.
In the case of just stopping the sample at a certain event, the
sections for path, volume and pitch may be omitted.
<path>
This defined th path to the sound file. The path is relative to the
FlightGear root directory but could be specified absolute.
<condition>
Define a condition that triggers the event.
For a complete description of the FlightGear conditions,
please read docs-mini/README.conditions
An event should define either a condition or a property.
<property>
Define which property triggers the event, and refers to a node
in the FlightGear property tree. Action is taken when the property
is non zero.
A more sophisticated mechanism to trigger the event is described
in <condition>
<mode>
This defines how the sample should be played:
once: the sample is played once.
this is the default.
looped: the sample plays continuously,
until the event turns false.
in-transit: the sample plays continuously,
while the property is changing its value.
<type>
This defines the type os this sample:
fx: this is the default type and doesn't need to be defined.
avionics: sounds set to this type don't have a position and
orientation but are treated as if it's mounted to
the aircraft panel. it's up to the user to define
if it can always be heard or only when in cockpit
view.
<volume> / <pitch>
Volume or Pitch definition. Currently there may be up to 5
volume and up to 5 pitch definitions defined within one sound
event. Normally all offset values are added together and the
results after property calculations will be multiplied.
A special condition occurs when the value of factor is negative,
in which case the offset doesn't get added to the other offset values
but instead will be used in the multiplication section.
<property>
Defines which property supplies the value for the calculation.
Either a <property> or an <internal> should be defined.
The value is treated as a floating point number.
<internal>
Defines which internal variable should be used for the calculation.
The value is treated as a floating point number.
The following internals are available at this time:
dt_play: the number of seconds since the sound started playing.
dt_stop: the number of seconds after the sound has stopped.
<delay-sec>
Delay after which the sound starts playing. This is useful to let
a property start two sounds at the same time, where the second is
delayed until the first stopped playing.
<type>
Defines the function that should be used upon the property
before it is used for calculating the net result:
lin: linear handling of the property value.
this is the default.
ln: convert the property value to a natural logarithmic
value before scaling it. Anything below 1 will return
zero.
log: convert the property value to a true logarithmic
value before scaling it. Anything below 1 will return
zero.
inv: inverse linear handling (1/x).
abs: absolute handling of the value (always positive).
sqrt: calculate the square root of the absolute value
before scaling it.
<factor>
Defines the multiplication factor for the property value.
A special condition is when scale is defined as a negative
value. In this case the result of |<scale>| * <property) will be
subtracted from <default>
<offset>
The initial value for this sound. This value is also used as an
offset value for calculating the end result.
<min>
Minimum allowed value.
This is useful if sounds start to sound funny. Anything lower
will be truncated to this value.
<max>
Maximum allowed value.
This is useful if sounds gets to loud. Anything higher will be
truncated to this value.
<position>
Specify the position of the sounds source relative to the
aircraft center. The coordinate system used is a left hand
coordinate system where +Y = left, -Y = right, -Z = down, +Z =
up, -X = forward, +X = aft. Distances are in meters.
The volume calculation due to distance and orientation of the
sounds source ONLY work on mono samples!
<x>
X dimension offset
<y>
Y dimension offset
<z>
Z dimension offset
<orientation>
Specify the orientation of the sounds source.
The zero vector is default, indicating that a Source is not directional.
Specifying a non-zero vector will make the Source directional in
the X,Y,Z direction
<x>
X dimension
<y>
Y dimension
<z>
Z dimension
<inner-angle>
The inner edge of the audio cone in degrees (0.0 - 180.0).
Any sound withing that angle will be played at the current gain.
<outer-angle>
The outer edge of the audio cone in degrees (0.0 - 180.0).
Any sound beyond the outer cone will be played at "outer-gain" volume.
<outer-gain>
The gain at the outer edge of the cone.
<reference-dist>
Set a reference distance of sound in meters. This is the
distance where the gain/volume will be halved. This can be
useful for limiting cockpit sounds to the cockpit.
<max-dist>
Set the maximum audible distance for the sound in meters.
This can be useful for limiting cockpit sounds to the cockpit.
Creating a configuration file:
------------------------------
To make things easy, there is a default value for most entries to allow a
sane configuration when a certain entry is omitted.
Default values are:
type: lin
factor: 1.0
offset: 0.0 for volume, 1.0 for pitch
min: 0.0
max: 0.0 (don't check)
Calculations are made the following way (for both pitch and volume):
value = 0;
offs = 0;
for (n = 0; n < max; n++) {
if (factor < 0)
{
value += offset[n] - abs(factor[n]) * function(property[n]);
}
else
{
value += factor[n] * function(property[n]);
offs += offset[n];
}
}
volume = offs + value;
where function can be one of: lin, ln, log, inv, abs or sqrt

186
docs-mini/README.xmlsyntax Normal file
View File

@@ -0,0 +1,186 @@
XML IN FIFTEEN MINUTES OR LESS
Written by David Megginson, david@megginson.com
Last modified: $Date$
This document is in the Public Domain and comes with NO WARRANTY!
1. Introduction
---------------
FlightGear uses XML for much of its configuration. This document
provides a minimal introduction to XML syntax, concentrating only on
the parts necessary for writing and understanding FlightGear
configuration files. For a full description, read the XML
Recommendation at
http://www.w3.org/TR/
This document describes general XML syntax. Most of the XML
configuration files in FlightGear use a special format called
"Property Lists" -- a separate document will describe the specific
features of the property-list format.
2. Elements and Attributes
--------------------------
An XML document is a tree structure with a single root, much like a
file system or a recursive, nested list structure (for LISP fans).
Every node in the tree is called an _element_: the start and end of
every element is marked by a _tag_: the _start tag_ appears at the
beginning of the element, and the _end tag_ appears at the end.
Here is an example of a start tag:
<foo>
Here is an example of an end tag:
</foo>
Here is an example of an element:
<foo>Hello, world!</foo>
The element in this example contains only data element, so it is a
leaf node in the tree. Elements may also contain other elements, as
in this example:
<bar>
<foo>Hello, world!</foo>
<foo>Goodbye, world!</foo>
</bar>
This time, the 'bar' element is a branch that contains other, nested
elements, while the 'foo' elements are leaf elements that contain only
data. Here's the tree in ASCII art (make sure you're not using a
proportional font):
bar +-- foo -- "Hello, world!"
|
+-- foo -- "Goodbye, world!"
There is always one single element at the top level: it is called the
_root element_. Elements may never overlap, so something like this is
always wrong (try to draw it as a tree diagram, and you'll understand
why):
<a><b></a></b>
Every element may have variables, called _attributes_, attached to
it. The attribute consists of a simple name=value pair in the start
tag:
<foo type="greeting">Hello, world!</foo>
Attribute values must be quoted with '"' or "'" (unlike in HTML), and
no two attributes may have the same name.
There are rules governing what can be used as an element or attribute
name. The first character of a name must be an alphabetic character
or '_'; subsequent characters may be '_', '-', '.', an alphabetic
character, or a numeric character. Note especially that names may not
begin with a number.
3. Data
-------
Some characters in XML documents have special meanings, and must
always be escaped when used literally:
< &lt;
& &amp;
Other characters have special meanings only in certain contexts, but
it still doesn't hurt to escape them:
> &gt;
' &apos;
" &quot;
Here is how you would escape "x < 3 && y > 6" in XML data:
x &lt; 3 &amp;&amp; y &gt; 6
Most control characters are forbidden in XML documents: only tab,
newline, and carriage return are allowed (that means no ^L, for
example). Any other character can be included in an XML document as a
character reference, by using its Unicode value; for example, the
following represents the French word "cafe" with an accent on the
final 'e':
caf&#233;
By default, 8-bit XML documents use UTF-8, **NOT** ISO 8859-1 (Latin
1), so it's safest always to use character references for characters
above position 127 (i.e. for non-ASCII).
Whitespace always counts in XML documents, though some specific
applications (like property lists) have rules for ignoring it in some
contexts.
4. Comments
-----------
You can add a comment anywhere in an XML document except inside a tag
or declaration using the following syntax:
<!-- comment -->
The comment text must not contain "--", so be careful about using
dashes.
5. XML Declaration
------------------
Every XML document may begin with an XML declaration, starting with
"<?xml" and ending with "?>". Here is an example:
<?xml version="1.0" encoding="UTF-8"?>
The XML declaration must always give the XML version, and it may also
specify the encoding (and other information, not discussed here).
UTF-8 is the default encoding for 8-bit documents; you could also try
<?xml version="1.0" encoding="ISO-8859-1"?>
to get ISO Latin 1, but some XML parsers might not support that
(FlightGear's does, for what it's worth).
6. Other Stuff
--------------
There are other kinds of things allowed in XML documents. You don't
need to use them for FlightGear, but in case anyone leaves one lying
around, it would be useful to be able to recognize it.
XML documents may contain different kinds of declarations starting
with "<!" and ending with ">":
<!DOCTYPE html SYSTEM "html.dtd">
<!ELEMENT foo (#PCDATA)>
<!ENTITY myname "John Smith">
and so on. They may also contain processing instructions, which look
a bit like the XML declaration:
<?foo processing instruction?>
Finally, they may contain references to _entities_, like the ones used
for escaping special characters, but with different names (we're
trying to avoid these in FlightGear):
&chapter1;
&myname;
Enjoy.