From ab9e651503414e6d58ab75bbd7bd7a26755938f0 Mon Sep 17 00:00:00 2001 From: ehofman Date: Sat, 21 Aug 2004 08:57:29 +0000 Subject: [PATCH] Sync with the source code. --- Docs/README.IO | 44 +++ Docs/README.Joystick | 1 + Docs/README.multiplayer | 72 +++++ Docs/README.sound | 62 ++++ Docs/README.xmlpanel | 654 ++++++++++++++++++++++++++++++++++++++++ Docs/README.xmlsound | 272 +++++++++++++++++ Docs/README.xmlsyntax | 186 ++++++++++++ 7 files changed, 1291 insertions(+) create mode 100644 Docs/README.Joystick create mode 100644 Docs/README.multiplayer create mode 100644 Docs/README.sound create mode 100644 Docs/README.xmlpanel create mode 100644 Docs/README.xmlsound create mode 100644 Docs/README.xmlsyntax diff --git a/Docs/README.IO b/Docs/README.IO index 6e838c6e9..38607916e 100644 --- a/Docs/README.IO +++ b/Docs/README.IO @@ -15,6 +15,50 @@ The general form of the command line option is as follows: hz = number of times to process channel per second (floating point values are ok. +Generic Communction: + + --generic=params + + With this option it is possible to output a pre-configured + ASCII string using a predefined seperator. The configuration is + defined in an XML file located in the Protocol directiory 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 + output to a file: file,dir,hz,filename,protocol + + + The confinfiguration file is defined as follows: + + + + + + + \n + + + speed + int + V=%d + /velocities/speed + 0.0 + 1.0 + + + + ... + + + ... + + + + + + Serial Port Communication: --nmea=serial,dir,hz,device,baud diff --git a/Docs/README.Joystick b/Docs/README.Joystick new file mode 100644 index 000000000..955bf3835 --- /dev/null +++ b/Docs/README.Joystick @@ -0,0 +1 @@ +Replaced by Docs/README.Joystick.html in the base package. diff --git a/Docs/README.multiplayer b/Docs/README.multiplayer new file mode 100644 index 000000000..ee081a139 --- /dev/null +++ b/Docs/README.multiplayer @@ -0,0 +1,72 @@ +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 (when one is created): +-------------------------------------------- +Player1: +--multiplay=out,10,serveraddress,6000 --multiplay=in,10,myaddress,5500 +--callsign=player1 + +Player2: +--multiplay=out,10,serveraddress,6000 --multiplay=in,10,myaddress,5501 +--callsign=player2 + +Playern: +--multiplay=out,10,serveraddress,6000 --multiplay=in,10,myaddress,5502 +--callsign=playern + +The server would simply act as a packet forwarding mechanism. When it +receives a packet, it sends it to all other active players. diff --git a/Docs/README.sound b/Docs/README.sound new file mode 100644 index 000000000..a180cec62 --- /dev/null +++ b/Docs/README.sound @@ -0,0 +1,62 @@ + +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") + + +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 diff --git a/Docs/README.xmlpanel b/Docs/README.xmlpanel new file mode 100644 index 000000000..960dd2e63 --- /dev/null +++ b/Docs/README.xmlpanel @@ -0,0 +1,654 @@ +Users Guide to FlightGear panel configuration +Version 0.7.7, May 16 2001 +Author: John Check + +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 . Tags are +almost always found in pairs, with the closing tag having a slash +prefixing the tag name, i.e . 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 , a + texture and zero or more .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: +------------------------------------------------ + + Aircraft/c172/Instruments/clock.xml + 110 + 320 + 72 + 72 + + +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: +---------------------------------------- + + Example Panel + Aircraft/c172/Panels/Textures/panel-bg.rgb + 1024 + 768 + -305 + 172 + + + + + Chronometer + 150 + 645 + 72 + 72 + + + + + + + +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 + + + 1 + 2 + 3 + + +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 + + + 1 + + 2 + + + +then the declaration + + + + +is exactly equivalent to + + + 1 + + 2 + + + +However, it is also possible to selectively override properties in the +included file. For example, if the declaration were + + + 3 + + +then the property manager would see + + + 3 + + 2 + + + +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, + + + 3 + + + +will look the same to the application as + + + 3 + 3 + + +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: + + + + /radios/comm1/frequencies/selected + /radios/nav1/frequencies/selected + + + ... + + + number-value + + + + ... + + +Now, the same instrument file can be used for navcomm1 and navcomm2, +for example, simply by overriding the parameters at inclusion: + + + + /radios/comm1/frequencies/selected + /radios/nav1/frequencies/selected + + + + + + /radios/comm2/frequencies/selected + /radios/nav2/frequencies/selected + + + +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: + + + Airspeed Indicator + 128 + 128 + + +Height and width can be overriden in the top level panel.xml by +specifying and . 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 . These can be combined in layers + + +A texture layer looks like this: + + + face + + Aircraft/c172/Instruments/Textures/faces-2.rgb + 0 + 0.51 + 0.49 + 1.0 + + + +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 and + parameters to be visible. + + May be either text or switch.. + +switch +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. + + + Brake light + switch + /controls/brakes + + on + + Aircraft/c172/Instruments/Textures/brake.rgb + 0.25 + 0.0 + 0.5 + 0.095 + + 64 + 24 + + + off + + Aircraft/c172/Instruments/Textures/brake.rgb + 0.0 + 0.0 + 0.25 + 0.095 + + 64 + 24 + + + +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. + +text +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: + + + display + text + 12 + + 1.0 + 0.5 + 0.0 + + + + number-value + /radios/nav1/dme/distance + 0.00053995680 + %5.1f + + + + + display + text + 10 + + 1.0 + 0.5 + 0.0 + + + + literal + ---.-- + + + + + +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 +. 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 x-shift +or y-shift depending on the orientation of the needle section in the +cropped texture. + +This example comes from the altimeter.xml + + + long needle (hundreds) + + Aircraft/c172/Instruments/Textures/misc-1.rgb + 0.8 + 0.78125 + 0.8375 + 1.0 + + 8 + 56 + + + rotation + /steam/altitude + 100000.0 + 0.36 + + + y-shift + 24.0 + + + + +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. + + + ... + + + 0.0 + 0.0 + + + 10.0 + 100.0 + + + 20.0 + -5.0 + + + 30.0 + 1000.0 + + + + +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: + + + small nav frequency decrease + adjust + + 96 + -32 + 16 + 32 + /radios/nav1/frequencies/standby + -0.05 + 108.0 + 117.95 + 1 + + + swap nav frequencies + swap + + 48 + -32 + 32 + 32 + /radios/nav1/frequencies/selected + /radios/nav1/frequencies/standby + + + ident volume on/off + adjust + + 40 + -24 + 16 + 16 + /radios/nav1/ident + 1.0 + 0 + 1 + 1 + + + +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). + diff --git a/Docs/README.xmlsound b/Docs/README.xmlsound new file mode 100644 index 000000000..9307d64ef --- /dev/null +++ b/Docs/README.xmlsound @@ -0,0 +1,272 @@ +Users Guide to FlightGear sound configuration +Version 0.7.11, apr 27 2002 +Author: Erik Hofman + +This document is an attempt to describe the configuration of +FlightGear flight simulator's aircraft sound via XML. + +Some History: +------------ +Older versions of FGFS had a hard coded audio layer. This was a +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 sounds. + +A rewrite of the sound code was done around v0.7.10 by Erik Hofman +allowing for configuration of the sounds via XML to address this +limitation. + +Sound Architecture: +------------------ +All of the sound configuration files are XML-encoded* property lists. +The root element of each file is always named . Tags are +almost always found in pairs, with the closing tag having a slash +prefixing the tag name, i.e . 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 , a +, a sound file and zero or more and/or +definitions. + +[ Paths are relative to $FG_ROOT (the installed location of FGFS data files.) ] +[ Absolute paths may be used.Comments are bracketed with . ] + +A limited sound configuration file would look something like this: + + + + + engine + Sounds/wasp.wav + looped + + /engines/engine/running + + + /engines/engine/mp-osi + 0.005 + 0.15 + 0.5 + 0.15 + + + /engines/engine/rpm + 0.0012 + 0.3 + 5.0 + 0.3 + + + + + +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 ) until the +property returns zero again. As you can see the volume is mp-osi dependant, +and the pitch of the sound depents on the engine rpm. + +Configuration description: +------------------------- + + + Named FX subtree living under /sim/sound + + < ... > + This is the event seperator. The text inside the brackets + can be anything. Bit it is adviced to give it a meaningfull 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). + + + 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 controll 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. + + + This defined th path to the sound file. The path is relative to the + FlightGear root directory but could be specified absolute. + + + 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. + + + Define which property triggers the event, and reffers 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 + + + This defines how the sample should be played: + + once: the sample is played once. + this is the default. + + looped: the sample plays continuesly, + until the event turns false. + + in-transit: the sample plays continuesly, + while the property is changing its value. + + / + 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 miltplied. + 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. + + + Defins which property supplies the value for the calculation. + Either a or an should be defined. + The value is treatened as a floating point number. + + + Defins which internal variable should be used for the calculation. + The value is treatened 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. + + + Defines the function that should be used upon the property + before it is used for calculating the net result: + + lin: lineair 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 lineair handling (1/x). + + abs: absolute handling of the value (always positive). + + sqrt: calculate the square root of the absolute value + before scaling it. + + + 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 || * + + + The initial value for this sound. This value is also used as an + offset value for calulating the end result. + + + Minimum allowed value. + This is usefull if sounds start to sound funny. Anything lower + will be truncated to this value. + + + Maximum allowed value. + This is usefull if sounds gets to loud. Anything higher will be + truncated to this value. + + + Specify the position of the sounds source relative to the + pilot's ears. The coordinate system used is a right hand + coordinate system where -X = left, +X = right, -Y = down, +Y = + up, -Z = forward, +Z = aft. Distances are in meters. + + + X dimension offset + + + Y dimension offset + + + Z dimension offset + + + 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. + + + Set the maximum audible distance for the sound in meters. + This can be useful for limiting cockpit sounds to the cockpit. + + +Creating a configrationfile: +--------------------------- + +To make things easy, there is a default falue 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 diff --git a/Docs/README.xmlsyntax b/Docs/README.xmlsyntax new file mode 100644 index 000000000..6c55c1969 --- /dev/null +++ b/Docs/README.xmlsyntax @@ -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: + + + +Here is an example of an end tag: + + + +Here is an example of an element: + + Hello, world! + +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: + + + Hello, world! + Goodbye, world! + + +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): + + + +Every element may have variables, called _attributes_, attached to +it. The attribute consists of a simple name=value pair in the start +tag: + + Hello, world! + +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: + + < < + & & + +Other characters have special meanings only in certain contexts, but +it still doesn't hurt to escape them: + + > > + ' ' + " " + +Here is how you would escape "x < 3 && y > 6" in XML data: + + x < 3 && y > 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é + +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: + + + +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 +"". Here is an example: + + + +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 + + + +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 so on. They may also contain processing instructions, which look +a bit like the XML declaration: + + + +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.