1\input texinfo 2@c -*-texinfo-*- 3@c -*-auto-fill-mode-*- 4@c -*-flyspell-mode-*- 5 6@c %**start of header 7@setfilename vamos.info 8@setchapternewpage 9@settitle Vamos 10@set VERSION 0.7.0 11@set EDITION 0.5 12@set UPDATED 15 January 2012 13@c %**end of header 14 15@dircategory Applications 16@direntry 17* Vamos: (vamos). An automotive simulator 18@end direntry 19 20@ifinfo 21Vamos Automotive Simulator, by Sam Varner. 22 23This file documents the Vamos libraries and application. 24 25Copyright 2001--2012 Sam Varner 26 27Permission is granted to copy, distribute and/or modify this document 28under the terms of the GNU Free Documentation License, Version 1.1 or 29any later version published by the Free Software Foundation; with no 30Invariant Sections, with no Front-Cover Texts, and with no Back-Cover 31Texts. A copy of the license is included in the section entitled "GNU 32Free Documentation License". 33 34@ignore 35Permission is granted to process this file through TeX and print the 36results, provided the printed document carries copying permission notice 37identical to this one except for the removal of this paragraph (this 38paragraph not being relevant to the printed manual). 39@end ignore 40 41Permission is granted to copy and distribute modified versions of this 42manual under the conditions for verbatim copying, provided that the 43entire resulting derived work is distributed under the terms of a 44permission notice identical to this one. 45 46Permission is granted to copy and distribute translations of this manual 47into another language, under the above conditions for modified versions, 48except that this permission notice may be stated in a translation 49approved by the Free Software Foundation. 50@end ifinfo 51 52@titlepage 53@title Vamos Automotive Simulator 54@subtitle @value{EDITION}, version @value{VERSION} 55@subtitle @vaule{UPDATED} 56@author 57 58@page 59@c Move the copyright notice to the bottom of the page. 60@vskip 0pt plus 1filll 61Copyright @copyright{} 2001--2008 Sam Varner 62 63Permission is granted to copy, distribute and/or modify this document 64under the terms of the GNU Free Documentation License, Version 1.1 or 65any later version published by the Free Software Foundation; with no 66Invariant Sections, with no Front-Cover Texts, and with no Back-Cover 67Texts. A copy of the license is included in the section entitled "GNU 68Free Documentation License". 69 70@end titlepage 71 72@ifnottex 73@node Top, Let's Go, (dir), (dir) 74@top Vamos Automotive Simulator 75 76Sam Varner @email{snick-a-doo@@comcast.net} 77 78Vamos is an automotive simulation framework with an emphasis on 79thorough physical modeling and good C++ design. Vamos includes a 80real-time, first-person, 3D driving application. 81 82This file documents Vamos version @value{VERSION}. 83@end ifnottex 84 85@menu 86* Let's Go:: Getting on the road. 87* Controls:: Keyboard and joystick settings. 88* Dashboard:: On-screen information. 89* Cars:: Choosing and creating cars. 90* Tracks:: Choosing and creating tracks. 91* Worlds:: Specifying environments. 92* Units:: A note about units of measure. 93* Code Reference:: The inner workings. 94* Building Vamos:: Downloading and compiling the program. 95* Copying:: The GNU Free Documentation License. 96* Concept Index:: An item for each concept. 97@end menu 98 99@c============================================================================= 100@node Let's Go, Controls, Top, Top 101@chapter Let's Go 102@cindex driving 103The @file{vamos} application lets you experience the simulation first 104hand. Its main purpose is to be a test bed for the libraries. It is 105not intended to be a polished end-user application. However, you can 106drive on a number of tracks and try to beat your best time. Or you 107can just have fun driving on, and over, the ragged edge. 108 109@section Getting Started 110When you start the application with no arguments you will be looking out 111over the hood of your car, down the front straight of a simple, 112fictitious circuit. Give the car a little gas and shift into first by 113pressing and releasing the first joystick button. The clutch is engaged 114gradually, so you will need to increase the throttle to keep the engine 115revs up. If you stall, shift back to neutral (second button) and press 116the @key{s} key to restart the engine. @xref{Controls}. 117 118Once you get going you will need to shift into second. When you press 119the button to shift, the clutch is disengaged. It is re-engaged when 120you release the button. You will need to back off the throttle when 121the clutch is disengaged in order to make your shifts smooth. As with 122shifting to first gear, the clutch is engaged gradually, although much 123more quickly. 124 125The first turn on the circuit is a sharp left-hander at the top of a 126hill. This is a good place to practice sliding the car through a 127turn. You will probably hear the tires slide as you enter the turn. 128Don't worry, the tires actually have @emph{more} grip when they're 129sliding a little. However, you do lose some directional stability. 130So you point the nose a little toward the center of the turn and use 131the throttle to hold the car in the turn. If you slide the car more 132than a little, you will lose grip and probably find yourself in the 133gravel. 134 135When driving on the edge, the throttle and brake do as much as the 136steering wheel to control the trajectory of the car. In general, 137accelerating tends to straighten out the car and braking tends to turn 138the car more. To demonstrate this, try backing off the throttle 139midway through a turn. You'll find that the back end steps out a 140little causing the car to turn in. 141 142@section Robot Cars 143You can race against computer-controlled opponents. Use the @command{o} 144option with a numeric argument to race against other cars. Use the 145@command{d} if you just want to watch. 146 147@node Controls, Dashboard, Let's Go, Top 148@section Controls 149The car can be driven with a joystick, keys, or even a mouse. A 150joystick is highly recommended. 151 152Keys, buttons, and joystick axes are mapped to functions in an XML 153file in the data directory (usually 154@file{/usr/local/share/vamos/controls}). By default the file 155@file{default-controls} is used. You can specify a different file 156with the @command{-a} or @command{--controls=} options. The default 157control bindings are as follows: 158 159@cindex controls 160@multitable @columnfractions .15 .25 .60 161@item Key @tab Stick @tab Action 162@item @key{Up}* @tab Forward @tab Throttle. 163@item @key{Down}* @tab Backward @tab Brake. 164@item @key{Left}* @tab Left @tab Turn left. 165@item @key{Right}* @tab Right @tab Turn right. 166@item @key{Insert}* @tab Button-1* @tab Shift up. 167@item @key{Delete}* @tab Button-2* @tab Shift down. 168@item @key{Home}* @tab Button-3* @tab Clutch. 169@item @key{a} @tab @tab Place the car back at the starting line. 170@item @key{r} @tab @tab Place the car back on the road. 171@item @key{s} @tab @tab Start the engine after a stall. 172@item @key{f} @tab @tab Fill the fuel tank. 173@item @key{c} @tab @tab Reload the car definition file. 174@item @key{t} @tab @tab Reload the track definition file. 175@item @key{p} @tab @tab Pause the application. 176@item @key{q} @tab @tab Exit the application. 177@item @key{F9} @tab @tab Cycle through the views. 178@end multitable 179 180The `*' symbol indicates that the action is performed gradually after 181the key or button is pressed. 182 183When shifting, pressing the key or button causes the clutch to be 184disengaged before the new gear is selected. Releasing the button 185releases the clutch. The clutch is engaged slowly when shifting from 186neutral, and more quickly for other gears. The clutch is always 187disengaged quickly. 188 189@section Control File Format 190Here's the format of a controls file. 191 192@example 193@group 194<controls name="Name"> 195 <!-- Key Binding --> 196 <bind> 197 <function>function name</function> 198 <key>k</key>[<up|down/>] 199 [<time>t</time>] 200 </bind> 201 202 <!-- Button Binding --> 203 <bind> 204 <function>function name</function> 205 <button>b</button>[<up|down/>] 206 </bind> 207 208 <!-- Axis Binding --> 209 <bind> 210 <function>function name</function> 211 <axis>a</axis> 212 [<factor>f</factor>] 213 [<offset>o</offset>] 214 [<minimum>m</minimum>] 215 </bind> 216</controls> 217@end group 218@end example 219 220The @code{function} tag gives the name of the function to bind. Any 221member funciton of Gl_Car_World that takes two double arguments and 222returns a bool can be bound. The case of the name inside the 223@code{function} tag must match the actual function's name, and 224underscores must be replaced with single spaces. 225 226The @code{down} tag binds the function to a key (or button) press; 227@code{up} binds it to a key release. If neither is specified, the 228function is bound to a key press. 229 230The @code{time} tag sets how long it takes for setting to be ramped up 231to its target value. It is used for controling continuous values, 232like throttle, from the keyboard. The default time is 0. 233 234For joystick axes, vaules range from -1 to 1. This number is 235multiplied by the value in the @code{factor} tag and then the value in 236the @code{offset} tag is added. The result is clipped at 237@code{minimum}. The defaults are 1, 0, 0, respectively. 238 239@subsection Bindable Functions 240These are the functions that can be bound to controls. 241 242@table @code 243@item pause 244Pause the simulation. 245 246@item quit 247Quit the program. 248 249@item cycle view 250Change the point-of-view from car to trackside to overhead. 251 252@item read car 253Read the car definition file. 254 255@item read track 256Read the track definition file. 257 258@item read world 259Read the world definition file. 260 261@item restart car 262Put the car at the starting line. 263 264@item reset car 265Put the car back on the track. 266 267@item fill tank 268Fill the car's gas tank. 269 270@item gas 271Operate the throttle. 272 273@item brake 274Operate the brakes. 275 276@item steer 277@itemx steer left 278@itemx steer right 279Operate the steering wheel. The 'steer left' and 'steer right' 280functions are useful for binding to keys. 281 282@item shift up 283@itemx shift down 284Select an adjacent gear, except when in neutral. 285 286@item shift up disengage 287@itemx shift down disengage 288Select an adjacent gear and operate the clutch, except when in neutral. 289 290@item initial shift up 291@itemx initial shift down 292Select an adjacent gear when in neutral. 293 294@item initial shift up disengage 295@itemx initial shift down disengage 296Select an adjacent gear and operate the clutch when in neutral. 297 298@item clutch 299Operate the clutch. 300 301@item engage clutch 302@itemx disengage clutch 303Operate the clutch, except when in neutral 304 305@item initial engage clutch 306@itemx initial disengage clutch 307Operate the clutch when in neutral 308@end table 309 310A function can be bound to more than one control. However, when the 311simulation is running, the joystick is read after the keys. If, for 312example, you bind the throttle to the up arrow key and to a joystick 313axis, the joystick (if present) will override the keyboard. 314 315Similarly, more than one function can be bound to a control. Each 316function is called in turn until one of them returns true. 317 318For shifting, you will likely bind two functions to each shifting 319control, one for shifting from neutral (e.g. @code{initial shift up}) 320and the other for shifting from other gears (e.g. @code{shift up}). 321If you bind the clutch to a key or button, rather than a continuous 322contral, you will also bind two functions to the clutch controls. The 323reason is that you may want different behavior from the clutch in 324these two situations. 325 326When shifting from neutral to first, you will let the clutch out 327slowly to get the car started without stalling. When shifting to 328other gears you will operate the clutch more quickly. You can make 329this happen by binding both @code{initial shift up disegnage} and 330@code{shift up disengage} to the same key or button, and using a 331larger value in the @code{time} tage for @code{initial shift up 332disengage}. 333 334@node Dashboard, Cars, Controls, Top 335@section Dashboard 336@cindex dashboard 337Several rows of text are printed along the bottom of the screen to 338provide some information about the car, similar to the gauges on a 339car's dashboard. You also get some information that you would not 340normally see on a dashboard. Here's what is shown, going down the 341columns, starting on the left. 342 343@table @asis 344@item RPM 345The engine speed in revolutions per minute. 346 347@item Torque 348The current engine torque in Newton-meters. 349 350@item Speed 351The car's speed in kilometers per hour. 352 353@item Gear 354The currently selected gear. @samp{N} stands for neutral and 355@samp{R} is for reverse. 356 357@item Break and Throttle 358The cyan bar shows the current brake setting. The magenta bar shows the 359throttle setting. These bars are useful for evaluating robot cars. 360 361@item Slip Ratios 362The slip ratios for each of the tires as a percentage. A slip ratio is 363the difference between the speed of the contact patch and the road 364moving beneath it, divided by the speed of the wheel's hub. Rolling 365without sliding yields a slip ratio of zero. Locking the wheels results 366in a slip ratio of 100%. Slip ratios are useful for seeing how close 367you are to the limit of adhesion. A ratio of 9% or 10% is usually close 368to optimal. 369 370@item Fuel 371Amount of fuel remaining in liters. 372 373@item Air Density 374The current density of the air that the car is driving through. This 375number decreases in another car's slipstream. 376 377@item Lap Time 378The elapsed time for the current lap. 379 380@item Last 381The time taken to complete the previous lap and the difference between 382this time and the best time. 383 384@item Best 385The shortest lap time so far. 386 387@item frame/s 388The current frame rate. 389 390@item Sector 391The number of the current timing sector and the elapsed time for that 392sector. 393 394@item Best 395The best time for the current sector. 396 397@item Last Sector 398The time taken to complete the previous sector and the difference 399between this time and the best time for that sector. 400 401@item Distance 402The distance from the start/finish line in meters. 403@end table 404 405@node Cars, Tracks, Dashboard, Top 406@section Cars 407@cindex cars 408A number of different car definitions are provided. The car can be 409selected with @command{-c <car>} or @command{--car=<car>}, where 410@command{<car>} is one of the following 411 412@table @file 413@item F1 414A modern Formula One car. 415 416@item F1-1967 417A late sixties Formula One car. For reasons I don't yet understand, 418this car is very difficult to control. 419 420@item front-drive 421A front wheel drive car. 422 423@item GT 424@itemx default-car 425A rear wheel drive sports car. 426 427@item trainer 428An under-powered car for beginners. 429@end table 430 431@section Car File Format 432The car definition goes inside a @code{car} tag. You can assign a 433name to the car with the @code{name} attribute. 434 435@example 436@group 437<car name="GT"> 438 ... 439</car> 440@end group 441@end example 442 443The sections below show how the various subsystems are defined. 444 445@subsection Robot Parameters 446These settings define the target performance of the robot car. The 447robot will use the specified slip ratio for acceleration. Deceleration 448and lateral acceleration give the performance targets for braking and 449cornering on a flat and level road with no aerodynamic assistance. The 450actual targets are adjusted in real time for the slope of the track and 451aerodynamic downforce. 452 453Note that these are just targets. If they are set to values that can't 454be achieved by the car the robot will drive the car off the road. 455 456@example 457@group 458 <robot> 459 <slip-ratio>9.0</slip-ratio> 460 <deceleration>1.4</deceleration> 461 <lateral-acceleration>1.5</lateral-acceleration> 462 </robot> 463@end group 464@end example 465 466@subsection View 467The driver's point-of-view is set with the @code{position} tag. You 468may use whatever units you like, as long as you're consistent. 469@xref{Units}. The horizontal field-of-view is set with the 470@code{field-width} tag. The vertical field-of-view is calculated 471automatically from the current window geometry. 472 473@example 474@group 475 <view> 476 <position>[ 1.3, 1.0, 0.8 ]</position> 477 <field-width>60.0</field-width> 478 </view> 479@end group 480@end example 481 482@subsection Steering 483 484The maximum steering angle is set with the @code{max-angle} tag. The 485@code{exponent} detemines how linear the steering response is. A 486higher number makes the steering less sensitive at small angles. 487 488@example 489@group 490 <steering> 491 <max-angle>10.0</max-angle> 492 <exponent>3.0</exponent> 493 </steering> 494@end group 495@end example 496 497@subsection Drivetrain 498The drivetrain section defines the engine, clutch, transmission and 499differential. 500 501@example 502@group 503 <drivetrain> 504 <engine> 505 ... 506 </engine> 507 508 <clutch> 509 ... 510 </clutch> 511 512 <transmission> 513 ... 514 </transmission> 515 516 <differential> 517 ... 518 </differential> 519 </drivetrain> 520@end group 521@end example 522 523The subsections of the drivetrain are described below. 524 525@example 526@group 527 <engine> 528 <position>[ 1.5, 1.0, 0.2 ]</position> 529 <mass>200.0</mass> 530 <max-power>3.0e5</max-power> 531 <peak-engine-rpm>8000.0</peak-engine-rpm> 532 <rpm-limit>10000.0</rpm-limit> 533 <inertia>0.10</inertia> 534 <idle>0.05</idle> 535 <start-rpm>1000</start-rpm> 536 <stall-rpm>500</stall-rpm> 537 <fuel-consumption>0.0001</fuel-consumption> 538 539 <sound> 540 <file>engine.wav</file> 541 <pitch>0.01</pitch> 542 <volume>0.8</volume> 543 <throttle-volume-factor>1.0</throttle-volume-factor> 544 <engine-speed-volume-factor>0.001</engine-speed-volume-factor> 545 </sound> 546 </engine> 547@end group 548@end example 549 550The @code{position} and @code{mass} parameters affect the weight 551distribution of the car. The torque curve is calculated from 552@code{max-power} and @code{peak-engine-rpm} using a polynomial 553expression given in @cite{Motor Vehicle Dynamics, Genta (1997)}, where 554@code{peak-engine-rpm} is the engine speed at which the maximum power 555output (@code{max-power}) is achieved. A rev limit can be set with 556@code{rpm-limit}. The rotational inertia of the moving parts is 557@code{inertia}. @code{idle} is the throttle position at idle. 558Starting the engine initially sets the engine speed to 559@code{start-rpm}. Letting the engine speed drop below 560@code{stall-rpm} makes the engine stall. The rate of fuel 561consumption is set with @code{fuel-consumption}. 562 563The engine sound is set in the @code{sound} section. @code{file} is 564the name of a WAV file in the @file{data/sounds} directory. 565@code{throttle-volume-factor} and @code{engine-speed-volume-factor} 566determine how the loudness of the sound changes. 567 568@example 569@group 570 <clutch> 571 <sliding>0.5</sliding> 572 <radius>0.25</radius> 573 <area>0.2</area> 574 <max-pressure>1.0e4</max-pressure> 575 </clutch> 576@end group 577@end example 578 579The torque on the clutch is found by dividing the clutch pressure by 580the value in the @code{area} tag and multiplying by the @code{radius} 581and @code{sliding} (friction) parameters. 582 583The gear ratios can be defined in two different ways inside the 584@code{transmission} tag. The ratios can be defined individually as in 585the example below. The first number inside the brackets is the gear 586(-1 is reverse), and the second is the clutch speed divided by the 587driveshaft speed. 588 589@example 590@group 591 <transmission> 592 <gear-ratio>[ -1, -2.69 ]</gear-ratio> 593 <gear-ratio>[ 1, 2.53 ]</gear-ratio> 594 <gear-ratio>[ 2, 1.71 ]</gear-ratio> 595 <gear-ratio>[ 3, 1.42 ]</gear-ratio> 596 <gear-ratio>[ 4, 1.19 ]</gear-ratio> 597 <gear-ratio>[ 5, 1.04 ]</gear-ratio> 598 <shift-delay>0.2</shift-delay> 599 </transmission> 600@end group 601@end example 602 603Alternatively, the number of gears and the highest and lowest ratios 604can be specified. The other gears will be calculate such that the 605reciprocals of the ratios are equally spaced. 606 607@example 608@group 609 <transmission> 610 <forward-gears>5</forward-gears> 611 <first-ratio>3.21</first-ratio> 612 <last-ratio>1.10</last-ratio> 613 <shift-delay>0.2</shift-delay> 614 </transmission> 615@end group 616@end example 617 618The @code{shift-delay} tag tells how long it takes to change gears. 619For a paddle-shifter, like a modern Formula One car, 620@code{shift-delay} can be set to zero. 621 622@subsection Fuel Tank 623The fuel tank's position, the current volume of fuel and the density 624of the fuel affect the car's weight distribution. The @code{capacity} 625tag sets the maximum volume of fuel that the tank can hold. The 626initial volume is set with the @code{volume} tag. The density of the 627fuel is set with @code{fuel-density}. 628 629@example 630@group 631 <fuel-tank> 632 <position>[ 1.00, 1.00, 0.25 ]</position> 633 <capacity>100.0</capacity> 634 <volume>100.0</volume> 635 <fuel-density>0.8</fuel-density> 636 </fuel-tank> 637@end group 638@end example 639 640@subsection Wheels 641The @code{wheel} section contains information about the suspension, 642tire, and brakes as well as the wheel itself. The @code{side} and 643@code{end} attributes tell where the wheel is located. The values of 644these attributes are important. 645 646The @code{steered} tag tells that the wheel responds to steering 647input. The @code{driven} tag tells that torque from the engine is 648applied to the wheel. Only two wheels may have a @code{steered} tag, 649and only two may have a @code{driven} tag. 650 651@example 652@group 653 <wheel side="right" end="front"> 654 <steered/> 655 <driven/> 656 <position>[ 3.0, 0.05, -0.1 ]</position> 657 <mass>30.0</mass> 658 <restitution>0.1</restitution> 659 <suspension> 660 ... 661 </suspension> 662 <tire> 663 ... 664 </tire> 665 <brakes> 666 ... 667 </brakes> 668 <wheel> 669@end group 670@end example 671 672Values set in one wheel section are persistent; if you want the same 673value for another wheel, you do not need set it. 674 675The suspension, tire, and brakes sections are described below. 676 677@subsection Suspension 678@example 679@group 680 <suspension> 681 <position>[ 3.0, 0.35, -0.1 ]</position> 682 <hinge>[ 2.0, 0.35, 0.3 ]</hinge> 683 <spring-constant>22000.0</spring-constant> 684 <bounce>2000.0</bounce> 685 <rebound>2000.0</rebound> 686 <travel>0.4</travel> 687 <max-compression-velocity>10.0</max-compression-velocity> 688 <camber>-2.0</camber> 689 <caster>5.0</caster> 690 <toe>-2.0</toe> 691 </suspension> 692@end group 693@end example 694 695The @code{hinge} is the center of the wheel's path as the suspension 696moves. The location of the hinge is determined by suspension 697geometry, and may be outside of the car itself. Currently, this 698parameter has no effect of performance. It may be used in the future 699for configuring anti-dive and anti-squat suspension geometries. 700 701@code{bounce} and @code{rebound} are the damping coefficients for 702compression and expansion of the suspension, respectively. If the 703speed at which the suspension is compressed, or expanded exceeds the 704value in @code{max-compression-velocity}, the dampers ``lock up.'' 705 706Wheel alignment is set with the @code{camber}, @code{caster}, and 707@code{toe} tags. All angles are in degrees. 708 709@subsection Tires 710The @code{longitudinal}, @code{transverse}, and @code{aligning} 711section each contain a vector of ``magic formula'' coefficients as 712presented in @cite{Motor Vehicle Dynamics, Genta (1997)}. The two 713elements of @code{rolling-resistance} are the constant and 714velocity-squared terms, respectively. 715 716@example 717@group 718 <tire> 719 <friction> 720 <longitudinal> 721 [ 1.65, 0.0, 1690.0, 0.0, 229.0, 0.0, 0.0, 0.0, -10.0, 0.0, 0.0 ] 722 </longitudinal> 723 <transverse> 724 [ 1.80, 0.0, 1690.0, 800.0, 6.03, 0.0, -0.359, 1.0, 0.0, -6.11e-3, -3.22e-2, 0.0, 0.0, 0.0, 0.0 ] 725 </transverse> 726 <aligning> 727 [ 2.07, -6.49, -21.9, 0.416, -21.3, 2.94e-2, 0.0, -1.20, 5.23, -14.8, 0.0, 0.0, -3.74e-3, 3.89e-2, 0.0, 0.0, 0.639, 1.69 ] 728 </aligning> 729 </friction> 730 <radius>0.310</radius> 731 <rolling-resistance>[ 1.3e-2, 6.5e-6 ]</rolling-resistance> 732 <rotational-inertia>10.0</rotational-inertia> 733 </tire> 734@end group 735@end example 736 737@subsection Brakes 738@example 739@group 740 <brakes> 741 <friction>0.8</friction> 742 <max-pressure>2.0e6</max-pressure> 743 <front-bias>0.55</front-bias> 744 <radius>0.2</radius> 745 <area>0.01</area> 746 </brakes> 747@end group 748@end example 749 750@code{front-bias} is the fraction of braking pressure applied to the 751front brakes. 752 753@subsection Particles and Contact Points 754Particles affect the mass distribution of the car. 755 756@example 757@group 758 <particle> 759 <position>[ 2.0, 1.0, 0.5 ]</position> 760 <mass>100.0</mass> 761 </particle> 762@end group 763@end example 764 765Contact points are particles that participate in collisions. The 766material specified in the @code{material} tag (either ``metal'' or 767``rubber'') determines the sound made when contact is detected. The 768coefficients of friction and restitution are set with the 769@code{friction} and @code{restitution} tags, respectively. 770 771@example 772@group 773 <contact-point> 774 <mass>40.0</mass> 775 <position>[ 0.0, 0.0, 0.0 ]</position> 776 <material>metal</material> 777 <friction>0.5</friction> 778 <restitution>0.1</restitution> 779 </contact-point> 780@end group 781@end example 782 783@subsection Drag and Wings 784The aerodynamic properties of the car are determined by the 785@code{drag} and @code{wing} sections. The frontal area and 786coefficient of drag, set it @code{frontal-area} and 787@code{drag-coefficient}, are used to calculate the drag force. 788 789@example 790@group 791 <drag> 792 <position>[ 2.0, 1.0, 0.25 ]</position> 793 <frontal-area>2.0</frontal-area> 794 <drag-coefficient>0.3</drag-coefficient> 795 </drag> 796@end group 797@end example 798 799Downforce can be added with wings. The amount of downforce is 800determined by the value in the @code{lift-coefficient} tag. If the 801lift coefficient is positive, upforce is generated. This is usually 802undesirable for cars. The @code{efficiency} determines how much drag 803is added as downforce increases. The @code{surface-area} is the 804surface area of the wing. This value is also used in the drag 805calculation. 806 807@example 808@group 809 <wing> 810 <position>[ 0.0, 0.9, 0.5 ]</position> 811 <frontal-area>0.2</frontal-area> 812 <surface-area>0.5</surface-area> 813 <lift-coefficient>-4.0</lift-coefficient> 814 <efficiency>0.5</efficiency> 815 </wing> 816@end group 817@end example 818 819@node Tracks, Worlds, Cars, Top 820@section Tracks 821@cindex tracks 822Once you get bored with the default, you might want to try driving on 823some different tracks. The track can be selected using command line 824arguments. Use either @command{vamos -t <track>} or @command{vamos 825--track==<track>}, where @command{<track>}, is the name of one of the 826XML files in the @file{data/tracks} directory. There are files for 827almost all of the Formula One circuits for the past couple of decades, 828plus a few more. These include 829 830@table @file 831@item drag 832A striaight flat strip of road. 833 834@item Monza 835The high-speed Italian circuit. 836 837@item Peanut 838@itemx default-track 839A simple track. 840 841@item Road_Atlanta 842The Georgia-shaped track in Georgia. 843 844@item Silverstone 845The home of the British grand prix. 846 847@item skid_pad 848A cirular track for testing handling. 849 850@item Spa 851The Spa-Francorchamps track in Belgium. 852 853@item Suzuka 854The track for many Japanase Grands Prix. 855@end table 856 857You can use the @command{trk-convert} program to turn a track file for 858RARS (Robot Auto Racing @url{http://rars.sourceforge.net}) into a 859C++ track file for Vamos. The converted files usually need 860some adjusting, so you'll have to learn a little about Vamos track 861files. 862 863@section Track File Format 864 865Tracks are defined in XML files. Here's the beginning of a track 866file. 867 868@example 869@group 870<track name="Peanut"> 871 <racing-line show="0"> 872 <iterations>800</iterations> 873 <stiffness>1.0</stiffness> 874 <damping>0.01</damping> 875 <margin>1.6</margin> 876 <resolution>14.0</resolution> 877 </racing-line> 878@end group 879@end example 880 881@subsection Racing Line 882The racing line section is optional. A good line is calculated for 883almost all tracks using the default parameters (shown). Changing the 884@code{show} parameter to 1 will cause the racing line to be drawn on the 885track. However, the @command{-l} option is a more convenient way to do 886this. 887 888Use more iterations if the racing line does not converge to something 889reasonable. You can try fewer to reduce the calculation time. 890 891The racing line is calculated by simulating a chain of masses with springs 892that tend to straighten the chain. Stiffness sets the spring constant. 893Damping prevents runaway oscillation. 894 895The margin is how close to the edge of the road the line is allowed to 896get. 897 898Resolution is the distance between masses. This parameter defaults to 899the width of the road at the starting line. 900 901The racing line can be modified by the tags 902@code{racing-line-adjustment} and @code{curvature-factor} in the 903@code{road}. See below. 904 905@subsection The Sky Box 906 907@example 908@group 909 <sky> 910 <sides>textures/sky_sides.png</sides> 911 <top>textures/sky_top.png</top> 912 <bottom>textures/sky_bottom.png</bottom> 913 <smooth/> 914 </sky> 915@end group 916@end example 917 918The @code{sky} section describes the sky box, which is a cube onto which 919a background is mapped. The @code{sides} image is wrapped around the 920front, right, back, and left sides of the sky box. The optional 921@code{smooth} tag can improve the quality of the sky box images. 922 923@subsection Materials 924 925After the sky box, the properties of the various materials that make 926up the track are defined. 927 928@example 929@group 930 <material name="track" type="asphalt"> 931 <friction>1.0</friction> 932 <restitution>0.1</restitution> 933 <rolling>1.0</rolling> 934 <drag>0.0</drag> 935 <bump-amplitude>0.01</bump-amplitude> 936 <bump-wavelength>100.0</bump-wavelength> 937 <texture> 938 <file>textures/track2.png</file> 939 <length>200.0</length> 940 <smooth/> 941 <mipmap/> 942 </texture> 943 </material> 944@end group 945@end example 946 947The name is used to identify the material in other parts of the file. 948The type helps determine what sound is played. The type must be one 949of rubber, metal, asphalt, concrete, grass, gravel, or dirt. 950 951The @code{friction} tag sets the relative friction of the surface. 952If, for example, you want to specify another surface that has half the 953friction of asphalt, you whould set the friction value to 0.5. The 954calculation of the actual frictional force involves the car. 955Similarly, relative values of the coefficient of restitution, rolling 956resistance, and velocity-dependent drag are set with the 957@code{restitution}, @code{rolling}, and @code{drag} tags. 958 959The bumpiness of the surface is set with the @code{bump-amplitude}, 960and @code{bump-wavelength} tags. They define a sinusiodal variation 961in the track's elevation. You may use whatever units you like, as 962long as you're consistent. @xref{Units}. 963 964The texture image is set in the @code{texture} section. The file is 965the name of a PNG image file. The physical size that the image covers 966is set with the @code{length} and @code{width} tags. In this example, 967the @code{width} tag is omitted. As a result, the texture is 968stretched to fit the width of the track. 969 970The @code{smooth} and @code{mipmap} tags improve the quality of the 971images, but they also reduce the frame rate. 972 973@subsection Segments 974 975The materials are grouped into ``segments'' that describe the 976materials for the track, kerbs, shoulders, and barriers. 977 978@example 979@group 980 <segment name="left turn"> 981 [ wall grass kerb track kerb gravel tires ] 982 </segment> 983@end group 984@end example 985 986The name is used to identify the segment in other parts of the file. 987Inside the @code{segment} tag is an array of material names. The 988material of the right-side barrier (as seen from a car traveling 989forward around the track) is first. 990 991@subsection Track Geometry 992 993The track is made up of @code{road} sections. Here is a simple 994@code{road} section 995 996@example 997@group 998 <road segment="left turn"> 999 <resolution>5.0</resolution> 1000 <length>130.0</length> 1001 <radius>160.0</radius> 1002 </road> 1003@end group 1004@end example 1005 1006The @code{segment} attribute names a list of materials defined earlier 1007in the file. The @code{resolution} sets the size of the quadrilateral 1008divisions in the road section. The smaller the resolution, the more 1009closely the section approximates a smooth curve. The length and width 1010are given in meters. However, any system of units can be used as long 1011as they are used consistently throughout the simulation for both 1012derived and fundamental quantities. 1013 1014The first road section must set the width of the track and shoulder, 1015and also the height of the barriers. These dimensions are specified 1016as (distance, width) pairs. Any number of pairs may be specified for 1017a given width, the program will interpolate linearly between 1018specified points. 1019 1020@example 1021@group 1022 <!-- front straight --> 1023 <road segment="straight pit"> 1024 <resolution>10.0</resolution> 1025 <length>100.0</length> 1026 <left-width>[ 0.0, 25.0 ]</left-width> 1027 <right-width>[ 0.0, 25.0 ]</right-width> 1028 <left-road-width>[ 0.0, 8.0 ]</left-road-width> 1029 <right-road-width>[ 0.0, 8.0 ]</right-road-width> 1030 <left-wall-height>2.0</left-wall-height> 1031 <right-wall-height>2.0</right-wall-height> 1032 <elevation>[ 20.0, 0.0 ]</elevation> 1033 <elevation>[ 200.0, 5.0 ]</elevation> 1034 </road> 1035@end group 1036@end example 1037 1038Similarly, any number of elevation points may be specified. A spline 1039is used to interpolate between elevation points to achieve smooth 1040elevation changes. 1041 1042The @code{racing-line-adjustment} adjusts the edges of the track left 1043(positive) or right (negative) for the purpose of calculating the racing 1044line. It is often useful to do this to shift the line toward the edge 1045of the track so that the robot cars will run onto the kerbs. 1046 1047If the cars go too fast or too slow for on a particular segment, the 1048@code{curvature-factor} can be specified to make the robots think the 1049racing line is curved more or less than it actually is. The actual 1050curvature is multiplied by this number. If it's greater than one the 1051cars will go slower; if it's less they'll go faster. 1052 1053@subsection Braking Markers 1054 1055Braking markers are signs that show the distance to an upcoming turn. 1056For turns approached a high speed, markers at 150 m, 100 m, and 50 m 1057are typically shown. 1058 1059@example 1060@group 1061 <road> 1062 ... 1063 <braking-marker> 1064 <file>textures/50.png</file> 1065 <distance>50.0</distance> 1066 <size>[ 1.4, 0.7 ]</size> 1067 <offset>[ 2.0, 0.0 ]</offset> 1068 <side>right</side> 1069 </braking-marker> 1070 <braking-marker> 1071 <file>textures/100.png</file> 1072 <distance>100.0</distance> 1073 </braking-marker> 1074 <braking-marker> 1075 <file>textures/150.png</file> 1076 <distance>150.0</distance> 1077 </braking-marker> 1078 ... 1079 </road> 1080@end group 1081@end example 1082 1083Once the size and offset parameters have been set, they do not need to 1084be specified again unless you want to use different values. 1085 1086@subsection Kerbs 1087 1088Concrete kerbs are often placed along the insides of curves, and on 1089the opposite side at the curve exits. I'm not really sure why. 1090Nonetheless, kerbs can be specified in the road sections. 1091 1092@example 1093@group 1094 <road> 1095 ... 1096 <left-kerb> 1097 <start> 1098 <distance>10.0</distance> 1099 <transition> 1100 <length>4.0</length> 1101 <width>1.0</width> 1102 </transition> 1103 </start> 1104 <end> 1105 <distance>100.0</distance> 1106 <transition> 1107 <length>4.0</length> 1108 <width>1.0</width> 1109 </transition> 1110 </end> 1111 <profile>[ 1.0, 0.1 ][ 3.0, 0.1 ][ 3.1, 0.0 ]</profile> 1112 </left-kerb> 1113 1114 <right-kerb> 1115 ... 1116 </right-kerb> 1117 ... 1118 </road> 1119@end group 1120@end example 1121 1122Each road section can have a left-side and a right-side kerb. A set 1123of coordinates of the form [ distance-from-edge-of-track, 1124elevation-above-track ] set the shape of the kerb in the 1125@code{profile} tag. A [ 0.0, 0.0 ] coordinate is inserted 1126automatically. 1127 1128The @code{start} and @code{end} tags tell where and how the kerb begins 1129and ends. If the distance is positive it is relative to the beginning 1130of the road section. If it's negative it is measured from the end. The 1131distance may be omitted for either or both ends. The default start and 1132end distances are zero and the end of the track, respectively. 1133 1134The @code{transition} section tells how the ends of the kerb are capped. 1135In the example above, the kerb tapers down track level and a width of 11361.0 m in a distance of 4.0 m. The transition does not add length to the 1137kerb. The @code{start} and @code{end} tags specify the endpoints of the 1138kerb including the transitions. 1139 1140If the @code{end} tag is omitted on one segment and the @code{start} tag 1141is omitted on the next, the kerb will run seamlessly across the segment 1142boundary. If the kerb should run through the segment and connect with 1143kerbs on the next and previous segments an empty tag 1144(@code{<left-kerb/>} or @code{<right-kerb/>}) will do. 1145 1146Once the transition length and width, and the profile are set they do 1147not need to be specified again unless you want to use different 1148values. You can use @code{<transition/>} to specify a transition with 1149the previously set values. For example, this kerb runs the entire 1150length of its road section and is capped with transitions at both 1151ends. 1152 1153@example 1154@group 1155 <right-kerb> 1156 <start><transition/></start> 1157 <end><transition/></end> 1158 </right-kerb> 1159@end group 1160@end example 1161 1162If there's no @code{start} tag, the kerb starts at the beginning of 1163the road section with no transition. If there's to @code{end}, the 1164kerb ends at the end of the road section. To make the kerb join 1165smoothly across two road sections, omit the @code{end} in the first 1166section, and omit the @code{start} in the second. 1167 1168Kerbs are typically serrated. Again, I don't know why. This can be 1169simulated by setting the bump parameters on the kerb material defined 1170near the beginning of the track file. 1171 1172@subsection Closing a Circuit 1173Adjusting a track to make meet the beginning seamlessly is tedious. 1174If a @code{<circuit/>} tag is included, the program will make the 1175adjustments automatically. You can specify how many of the last 1176segments will be adjusted with the @code{segments} attribute. For 1177example, with @code{<circuit segments="2"/>} only the last two 1178segments will be changed. Note the quotes around the value (required 1179by the XML standard) and the trailing slash. 1180 1181Allowed values for the @code{segments} tag are 0, 1, 2, and 3. The 1182default is 3. 1183 1184@table @file 1185@item 3 1186Adjust the length of the next-to-last segment (which must be a curve), 1187to make the last segment parallel to the first. Adjust the length of 1188the third-to-last segment (which must be straight) to put the last 1189segment in line with the first. Adjust the length of the last segment 1190so that it meets the beginning of the first. 1191 1192@item 2 1193Adjust the radius and length of the next-to-last segment to align the 1194last with the first. Adjust the length of the last segment 1195so that it meets the beginning of the first. 1196 1197@item 1 1198Adjust the length of the last segment so that it meets the beginning 1199of the first. 1200 1201@item 0 1202Adjust nothing. 1203@end table 1204 1205In all cases (including 0) the elevation curve is forced to close. 1206 1207If the track can not be closed with the specified adjustments, or the 1208requirements about what segments must be stright or curved, the 1209exception @code{Vamos_Track::Can_Not_Close} is thrown. 1210 1211@node Worlds, Units, Tracks, Top 1212@section Worlds 1213The ``world'' specifies various environmental factors. Here's the 1214entire default world file. 1215 1216@example 1217@group 1218<world name="Earth"> 1219 <!-- Acceleration due to gravity --> 1220 <gravity>9.8</gravity> 1221 1222 <maximum-time-step>0.01</maximum-time-step> 1223 1224 <atmosphere> 1225 <!-- Air density --> 1226 <density>1.2</density> 1227 <!-- Wind velocity --> 1228 <velocity>[ 0.0, 0.0, 0.0 ]</velocity> 1229 </atmosphere> 1230 1231 <lighting> 1232 <!-- Direction to the light source --> 1233 <source-position>[ 0.0, -1.0, 1.0 ]</source-position> 1234 <!-- RGB for ambient light --> 1235 <ambient>[ 0.7 , 0.7, 0.7 ]</ambient> 1236 </lighting> 1237</world> 1238@end group 1239@end example 1240 1241Here is a description of the sections. 1242 1243@table @code 1244@item gravity 1245Acceleration due to gravity. The typical value for Earth is 9.8 1246m/s^2. 1247 1248@item maximum-time-step 1249Each frame in the simulation will be sub-divided into time steps no 1250larger than this value. If you see jitter when the car is stopped, 1251try lowering the maximum time step. However, you may take a 1252performance hit, if the value is too small. 1253 1254@item atmosphere 1255Density of the air and wind velocity. 1256 1257@item lighting 1258Light source position and ambient light level. 1259@end table 1260 1261Other world files can be specified with the @command{--world=} or 1262@command{-w} options. Just for fun, a world file for the moon is 1263provided. 1264 1265@c============================================================================= 1266@node Units, Code Reference, Worlds, Top 1267@chapter Units 1268@cindex units 1269 1270A number that describes a physical quantity is meaningless unless the 1271units of measure are given. If we have a length of 20, we don't know 1272if it's 20 meters, 20 feet, or 20 light years. Despite this fact, 1273there are no units specified in Vamos. 1274 1275Consider the fundamental quantities to be time, length, and mass. 1276From these, you can derive the units for any quantity used in the 1277simulation. For instance, the units on velocity are a length unit 1278divided by a time unit. Force units are mass times length divided by 1279time squared. As long as the fundamental and derived units are 1280consistent, it does not matter what base units are used. 1281 1282There's one exception. Since the simulation relies on library 1283functions for timing information, and these libraries use seconds, the 1284unit of time must be seconds. 1285 1286I always use SI (metric) units because it's easy to keep the base and 1287derived units consistent. The SI base units are the meter (m) for 1288length and kilogram (kg) for mass. Power is derived quantity with 1289units of Watts. A Watt is a kg*m^2/s^3. If you use feet and slugs as 1290your base unit, then your power will be in slug*ft^2/s^3; you can't 1291simply use horsepower. 1292 1293Derived units used in the simulation are 1294 1295@itemize @bullet 1296@item area (distance^2) 1297 1298@item volume (distance^3) 1299 1300@item speed (distance/time) 1301 1302@item acceleration (distance/time^2) 1303 1304@item force (mass*acceleration) 1305 1306@item torque (force*distance) 1307 1308@item engine power (force*distance/time) 1309 1310@item spring constant (force/distance) 1311 1312@item damping (force/speed) 1313 1314@item density (mass/volume) 1315@end itemize 1316 1317There are some places where non-SI units are used. All angles are 1318specified in degrees. Engine speeds are specified in rotations per 1319minute (RPM). The coefficients for tire friction have their customary 1320units. 1321 1322@c============================================================================= 1323@node Code Reference, Building Vamos, Units, Top 1324@chapter Code Reference 1325 1326The code is devided into four modules that reside in four namespaces, 1327@code{Vamos_Geometry}, @code{Vamos_Body}, @code{Vamos_Track} and 1328@code{Vamos_World}. Each namespace contains the code for a library. 1329These libraries are @code{libvamos-geometry}, @code{libvamos-body}, 1330@code{libvamos-track}, and @code{libvamos-world}. The geometry library 1331has classes for vectors, matrices and curves. The body library has a 1332class for a rigid body and classes for a car and its parts. It also has 1333other classes that are needed by more than one of the other libraries. 1334The track library has the classes needed for building a track. The 1335world library handles a rigid body's interaction with the track. 1336 1337@menu 1338* The Geometry Library:: Vectors, matrices, curves, etc. 1339* The Media Library:: Code for sound, images, 3D models. 1340* The Track Library:: The driving surface. 1341* The Body Library:: Cars and other rigid bodies. 1342* The World Library:: The world mediates interactions. 1343@end menu 1344 1345The geometry library is used by both the body and world libraries. The 1346body library is used by the world library. The dependency graph looks 1347like this: 1348@example 1349@group 1350 libvamos-geometry 1351 / | 1352 / | 1353 libvamos-media | 1354 \ | 1355 \ | 1356 ----+---- 1357 / | \ 1358 / | \ 1359 libvamos-track | libvamos-body 1360 \ | / 1361 \ | / 1362 libvamos-world 1363 1364@end group 1365@end example 1366Libraries farther down the graph depend on the libraries above them. If 1367you only need the services of the geometry library, then you only have 1368one library to link. If you use the body library, then you need to link 1369the geometry and media libraries as well. If you use the world library, 1370then you need to link all five. When linking multiple libraries you may 1371need to make sure that @code{libvamos-geometry} is linked first, 1372followed by @code{libvamos-body}, and then @code{libvamos-world}. If 1373you get errors from the linker about undefined references to functions 1374defined in one of these libraries, then you may have to adjust the link 1375order. 1376 1377Care was taken to avoid a dependency of @code{libvamos-track} on 1378@code{libvamos-body} and vice versa. This allows cars and tracks to 1379tested independently. 1380 1381@node The Geometry Library, The Media Library, , Code Reference 1382@section The Geometry Library 1383@cindex geometry library 1384@cindex @code{Vamos_Geometry} 1385@cindex @file{libvamos-geometry} 1386 1387The geometry module is a collection of mathematical constants, 1388functions, and objects. There are also a few less mathematical classes 1389that are required by more than one other module. This is done to avoid 1390dependency problems. 1391 1392@section Three_Vector 1393@cindex @code{Three_Vector} 1394@cindex vector 1395A @code{Three_Vector} represents a vector in three dimensions. Some 1396supported operations are 1397 1398@itemize @bullet 1399@item subscripting using @code{[]} 1400 1401@item vector addition and subtraction using @code{+} and @code{-} 1402 1403@item multiplication and division by a scalar using @code{*} and @code{/} 1404 1405@item left and right matrix multiplication using @code{*} 1406 1407@item dot and cross products using the @code{dot()} and @code{cross()}methods 1408 1409@item projection onto another vector using the @code{project()} method 1410 1411@item magnitude using the @code{abs()} method 1412@end itemize 1413 1414Matrix multiplication is done with a @code{Three_Matrix}. 1415 1416@section Three_Matrix 1417@cindex @code{Three_Matrix} 1418@cindex matrix 1419 1420A @code{Three_Matrix} represents 3x3 matrix. It's suitable for 1421representing a three-dimensional rotation matrix or inertia tensor. 1422Some suported operations are 1423 1424@itemize @bullet 1425@item subscripting using @code{[]} 1426 1427@item matrix addition and subtraction using @code{+} and @code{-} 1428 1429@item multiplication and division by a scalar using @code{*} and @code{/} 1430 1431@item left and right vector multiplication using @code{*} 1432 1433@item matrix multiplication using @code{*} 1434 1435@item eigenvalue and eigenvector determination 1436 1437@item inversion 1438@end itemize 1439 1440@section Inertia_Tensor 1441@cindex @code{Inertia_Tensor} 1442@cindex inertia tensor 1443An inertia tensor is a matrix that describes a rigid body's responce 1444to torques. The @code{Inertia_Tensor} generates the tensor from the 1445locations of masses on a body. The masses and positions are specified 1446using the @code{add()} method. The @code{inertia()} method returns 1447the moment of inertia for a force applied at a particular point on the 1448body. 1449 1450@section Two_Point 1451@cindex @code{Two_Point} 1452@cindex point 1453A @code{Two_Point} describes a point in a plane. It is a @code{struct} 1454with two data members, @code{x} and @code{y}. A constructor is provided 1455for initializing the members. No vector operations are supported, and 1456some of the supported operations are undefined for vectors. That's why 1457this class is called @code{Two_Point} and not @code{Two_Vector}. The 1458supported operations are scalar and member-wise addition, subtraction, 1459multiplication, and division. For the scalar versions, the operation is 1460performed on each member. 1461 1462@code{Spline} is the only user of @code{Two_Point}. Perhaps it should 1463be defined in @code{Spline}'s header so that there's less temptation to 1464use @code{Two_Point} inappropriately. 1465 1466@section Spline 1467@cindex @code{Spline} 1468@cindex spline 1469@code{Spline} is a class for a parametric cubic spline interpolation 1470between points. A vector of @code{Two_Point}s through which the curve 1471passes and angle of the curve at the first and last points are passed to 1472the constructor. 1473 1474@code{Spline}s are used to make smooth road elevation changes and banking 1475transitions. 1476 1477@section Surface 1478@cindex @code{surface} 1479A @code{Surface} describes the friction, rolling resistance, restitution 1480and texture image of a surface such as pavement, grass or gravel. 1481 1482@section Texture_Image 1483@cindex @code{Texture_Image} 1484@cindex texture 1485@cindex image 1486The @code{Texture Image} class provides a convenient way of reading a 1487@file{*.ppm} image file from the disk and for getting information about 1488the image. 1489 1490@section Conversions 1491@cindex @code{Conversions} 1492The header file @file{Conversions.h} contains a few functions for 1493performing frequently-used unit conversions. Currently, there are 1494conversions for radians and degress, radians per second and revolutions 1495per minute, and meters per second and kilometers per hour. 1496 1497@node The Media Library, The Track Library, The Geometry Library, Code Reference 1498@section The Media Library 1499@cindex media library 1500@cindex @code{Vamos_Media} 1501@cindex @file{libvamos-media} 1502 1503@node The Track Library, The Body Library, The Media Library, Code Reference 1504@section The Track Library 1505@cindex track library 1506@cindex @code{Vamos_Track} 1507@cindex @file{libvamos-track} 1508 1509A @code{Track} is a collection of straight and curved pieces of road. 1510These pieces are described by classes derived from @code{Road_Segment}. 1511Currently, we have a straight segment class (@code{Straight_Road}), and 1512a circle arc segment class (@code{Arc_Road}). The track is assembled so 1513that there are no corners where two segments join. 1514 1515If you look at the code you'll find a class for a segment that smoothly 1516curves through a set of given points (@code{Spline_Road}). This class 1517has been commented out because I don't know how to do the transformation 1518from world coordinates to track coordinates for a spline. 1519 1520The elevation and banking at any number of points on a segment can be 1521specified. The specified points are interpolated with a cubic spline so 1522that the transitions are smooth. 1523 1524@example 1525@group 1526Track o---Road_Segment 1527 ^ ^ 1528 / \ 1529Straight_Road Arc_Road 1530@end group 1531@end example 1532 1533@node The Body Library, The World Library, The Track Library, Code Reference 1534@section The Body Library 1535@cindex body library 1536@cindex @code{Vamos_Body} 1537@cindex @file{libvamos-body} 1538@cindex @code{Body} 1539@cindex @code{Particle} 1540@cindex @code{Frame} 1541@cindex @code{Car} 1542 1543A @code{Body} describes a three-dimensional rigid body made up of point 1544particles. These particles are described by @code{Particle} and its 1545subclasses. Position and orientation for both @code{Body}s and 1546@code{Particle}s is provided by the @code{Frame} base class. The 1547@code{Car} class is derived from @code{Body} 1548 1549@example 1550@group 1551 Frame 1552 ^ ^ 1553 / \ 1554 Body o---Particle 1555 ^ 1556 | 1557 Car 1558@end group 1559@end example 1560 1561@menu 1562* Frame:: A coordinate system. 1563* Particle:: A body is made up of point particles. 1564* Body:: A rigid body. 1565* Car:: A drivable body. 1566@end menu 1567 1568@node Frame 1569@subsection Frame 1570 1571@node Particle 1572@subsection Particle 1573 1574@node Body 1575@subsection Body 1576 1577@node Car 1578@subsection Car 1579 1580@subsubsection Drivetrain 1581 1582@subsubsection Wheel 1583 1584 1585@node The World Library, , The Body Library, Code Reference 1586@section The World Library 1587@cindex world library 1588@cindex @code{Vamos_World} 1589@cindex @file{libvamos-world} 1590 1591To avoid dependencies, @code{Track}, @code{Atmosphere}, and 1592@code{Body} were each designed so that they know nothing about the 1593others. It is the purpose of the @code{World} class to mediate any 1594interactions among those classes. Because @code{Track}, 1595@code{Atmosphere}, and @code{Body} are independent, it is neccessary 1596that @code{World} depend on each of these classes. A subclass of 1597@code{World} that provides an interface to the input methods of 1598@code{Car} is provided. It's called @code{Car_World}. (Apologies to 1599Marcus Hewat, creator of the Carworld program, 1600@url{http://perso.club-internet.fr/hewat/carworld/carworld.htm}. 1601Aside from some bits of code I stole for reading textures from files 1602and drawing text on the screen, this project is unrelated to 1603Carworld.) 1604 1605@example 1606@group 1607 World 1608 o ^ o o---. 1609 / | \ \ 1610 Track | Body Atmosphere 1611 | ^ 1612 Car_World | 1613 o | 1614 \ | 1615 Car 1616@end group 1617@end example 1618 1619The @code{World} base class doesn't do any graphics. If you want to see 1620the results of the simulation on screen, you must derive an appropriate 1621class and define the @code{draw()} method. An example of such a class 1622that uses OpenGL, @code{Gl_Car_World}, is provided. You must also use 1623subclasses of Track and Car (such as @code{Gl_Track} and @code{Gl_Car}) 1624that use the same graphics system if you wish to see instances of those 1625objects. 1626 1627A typical application will construct a @code{Track}, @code{Atmosphere}, 1628and @code{Car}, and then construct a @code{World} by passing pointers to those 1629objects. The simulation is started by calling the @code{World}'s 1630@code{start()} method. The @code{World} is responsible for initializing the 1631graphics system (if used) and starting the event loop. 1632 1633@subsection Atmosphere 1634@cindex @code{Atmosphere} 1635To be written. 1636 1637@c============================================================================= 1638@node Building Vamos, Copying, Code Reference, Top 1639@appendix Building Vamos 1640@cindex building 1641 1642@section Downloading 1643@cindex downloading 1644You can get the latest release by going to the Vamos home page, 1645@url{http://vamos.sourceforge.net}, and following the ``Download'' 1646link. Another way to get there is to go through the SourceForge 1647project page, @url{http://sourceforge.net/projects/vamos}. 1648 1649@section Dependencies 1650@cindex dependencies 1651Vamos makes use of some external libraries. These libraries need to 1652be present in order to compile Vamos. 1653 1654OpenGL-compatible libraries, including the OpenGL Utility Library 1655(GLU) and the OpenGL Utility Toolkit (GLUT) must be installed. Mesa 1656@url{http://www.mesa-3d.org} works fine. In addition, you need 1657accelerated video hardware. Some video cards require specific GL 1658implementations. 1659 1660SDL @url{http://www.libsdl.org} is used for event handling (keys, mouse, 1661and joystick). Sound is handled by OpenAL 1662@url{http://connect.creativelabs.com/openal}. 1663 1664You will also need a reasonably up-to-date C++ compiler. Specifically, 1665it must handle namespaces. Gcc version 2.96 and later, including 3.x, 1666and 4.x should do. See @url{http://gcc.gnu.org}. The code is intended 1667to be portable, standard C++, so other compilers should work as well. 1668 1669@section Compiling 1670@cindex compiling 1671@cindex configure 1672@cindex installing 1673After downloading the source archive (the @file{tar.gz} file), unpack 1674it with the @command{tar} command, or some other utility. All of the 1675files in the archive are placed in a subdirectory. If the 1676archive is @file{vamos-1.2.3.tar.gz}, the files are placed in 1677@file{vamos-1.2.3}. 1678 1679Vamos uses the GNU Autotools (@command{automake}, @command{autoconf}, 1680and @command{libtool}) to check for prerequisites and handle different 1681architectures. Change to the directory created by un-archiving and 1682type @command{./configure}. Type @command{./configure --help} to see 1683the options accepted by @code{configure}. I have only tried to 1684compile Vamos on GNU/Linux and Cygwin/Win32 platforms. Please write 1685me if you find an architecture that is not handled correctly. 1686 1687The @command{configure} script generates the @file{Makefile}s needed 1688to compile the program. Issue the @command{make} command to start the 1689compilation. If you encounter errors, or warnings that you think I 1690should know about, please contact me. 1691 1692If the compilation succeeds, you can install the libraries, headers, 1693and application by typing @command{make install}. You may need to be 1694a privileged user to install software on your system. You do not need 1695to install the program to run the application. Switch to the 1696@file{vamos} directory and run @command{./vamos} to try the 1697application without installing. 1698 1699@node Copying, Concept Index, Building Vamos, Top 1700@appendix Copying 1701@cindex copying 1702 1703Vamos may be copied according to the terms of the GNU General Public 1704License (GNU GPL). The license is in the file COPYING in the 1705top-level directory of the source code. 1706 1707This documentation may be copied according to the 1708terms of the GNU Free Documentation License (GNU FDL) which is printed 1709below. 1710 1711@appendixsec GNU Free Documentation License 1712 1713@cindex FDL, GNU Free Documentation License 1714@center Version 1.1, March 2000 1715 1716@display 1717Copyright @copyright{} 2000 Free Software Foundation, Inc. 171859 Temple Place, Suite 330, Boston, MA 02111-1307, USA 1719 1720Everyone is permitted to copy and distribute verbatim copies 1721of this license document, but changing it is not allowed. 1722@end display 1723 1724@enumerate 0 1725@item 1726PREAMBLE 1727 1728The purpose of this License is to make a manual, textbook, or other 1729written document @dfn{free} in the sense of freedom: to assure everyone 1730the effective freedom to copy and redistribute it, with or without 1731modifying it, either commercially or noncommercially. Secondarily, 1732this License preserves for the author and publisher a way to get 1733credit for their work, while not being considered responsible for 1734modifications made by others. 1735 1736This License is a kind of ``copyleft'', which means that derivative 1737works of the document must themselves be free in the same sense. It 1738complements the GNU General Public License, which is a copyleft 1739license designed for free software. 1740 1741We have designed this License in order to use it for manuals for free 1742software, because free software needs free documentation: a free 1743program should come with manuals providing the same freedoms that the 1744software does. But this License is not limited to software manuals; 1745it can be used for any textual work, regardless of subject matter or 1746whether it is published as a printed book. We recommend this License 1747principally for works whose purpose is instruction or reference. 1748 1749@item 1750APPLICABILITY AND DEFINITIONS 1751 1752This License applies to any manual or other work that contains a 1753notice placed by the copyright holder saying it can be distributed 1754under the terms of this License. The ``Document'', below, refers to any 1755such manual or work. Any member of the public is a licensee, and is 1756addressed as ``you''. 1757 1758A ``Modified Version'' of the Document means any work containing the 1759Document or a portion of it, either copied verbatim, or with 1760modifications and/or translated into another language. 1761 1762A ``Secondary Section'' is a named appendix or a front-matter section of 1763the Document that deals exclusively with the relationship of the 1764publishers or authors of the Document to the Document's overall subject 1765(or to related matters) and contains nothing that could fall directly 1766within that overall subject. (For example, if the Document is in part a 1767textbook of mathematics, a Secondary Section may not explain any 1768mathematics.) The relationship could be a matter of historical 1769connection with the subject or with related matters, or of legal, 1770commercial, philosophical, ethical or political position regarding 1771them. 1772 1773The ``Invariant Sections'' are certain Secondary Sections whose titles 1774are designated, as being those of Invariant Sections, in the notice 1775that says that the Document is released under this License. 1776 1777The ``Cover Texts'' are certain short passages of text that are listed, 1778as Front-Cover Texts or Back-Cover Texts, in the notice that says that 1779the Document is released under this License. 1780 1781A ``Transparent'' copy of the Document means a machine-readable copy, 1782represented in a format whose specification is available to the 1783general public, whose contents can be viewed and edited directly and 1784straightforwardly with generic text editors or (for images composed of 1785pixels) generic paint programs or (for drawings) some widely available 1786drawing editor, and that is suitable for input to text formatters or 1787for automatic translation to a variety of formats suitable for input 1788to text formatters. A copy made in an otherwise Transparent file 1789format whose markup has been designed to thwart or discourage 1790subsequent modification by readers is not Transparent. A copy that is 1791not ``Transparent'' is called ``Opaque''. 1792 1793Examples of suitable formats for Transparent copies include plain 1794@sc{ascii} without markup, Texinfo input format, La@TeX{} input format, 1795@acronym{SGML} or @acronym{XML} using a publicly available 1796@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed 1797for human modification. Opaque formats include PostScript, 1798@acronym{PDF}, proprietary formats that can be read and edited only by 1799proprietary word processors, @acronym{SGML} or @acronym{XML} for which 1800the @acronym{DTD} and/or processing tools are not generally available, 1801and the machine-generated @acronym{HTML} produced by some word 1802processors for output purposes only. 1803 1804The ``Title Page'' means, for a printed book, the title page itself, 1805plus such following pages as are needed to hold, legibly, the material 1806this License requires to appear in the title page. For works in 1807formats which do not have any title page as such, ``Title Page'' means 1808the text near the most prominent appearance of the work's title, 1809preceding the beginning of the body of the text. 1810 1811@item 1812VERBATIM COPYING 1813 1814You may copy and distribute the Document in any medium, either 1815commercially or noncommercially, provided that this License, the 1816copyright notices, and the license notice saying this License applies 1817to the Document are reproduced in all copies, and that you add no other 1818conditions whatsoever to those of this License. You may not use 1819technical measures to obstruct or control the reading or further 1820copying of the copies you make or distribute. However, you may accept 1821compensation in exchange for copies. If you distribute a large enough 1822number of copies you must also follow the conditions in section 3. 1823 1824You may also lend copies, under the same conditions stated above, and 1825you may publicly display copies. 1826 1827@item 1828COPYING IN QUANTITY 1829 1830If you publish printed copies of the Document numbering more than 100, 1831and the Document's license notice requires Cover Texts, you must enclose 1832the copies in covers that carry, clearly and legibly, all these Cover 1833Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on 1834the back cover. Both covers must also clearly and legibly identify 1835you as the publisher of these copies. The front cover must present 1836the full title with all words of the title equally prominent and 1837visible. You may add other material on the covers in addition. 1838Copying with changes limited to the covers, as long as they preserve 1839the title of the Document and satisfy these conditions, can be treated 1840as verbatim copying in other respects. 1841 1842If the required texts for either cover are too voluminous to fit 1843legibly, you should put the first ones listed (as many as fit 1844reasonably) on the actual cover, and continue the rest onto adjacent 1845pages. 1846 1847If you publish or distribute Opaque copies of the Document numbering 1848more than 100, you must either include a machine-readable Transparent 1849copy along with each Opaque copy, or state in or with each Opaque copy 1850a publicly-accessible computer-network location containing a complete 1851Transparent copy of the Document, free of added material, which the 1852general network-using public has access to download anonymously at no 1853charge using public-standard network protocols. If you use the latter 1854option, you must take reasonably prudent steps, when you begin 1855distribution of Opaque copies in quantity, to ensure that this 1856Transparent copy will remain thus accessible at the stated location 1857until at least one year after the last time you distribute an Opaque 1858copy (directly or through your agents or retailers) of that edition to 1859the public. 1860 1861It is requested, but not required, that you contact the authors of the 1862Document well before redistributing any large number of copies, to give 1863them a chance to provide you with an updated version of the Document. 1864 1865@item 1866MODIFICATIONS 1867 1868You may copy and distribute a Modified Version of the Document under 1869the conditions of sections 2 and 3 above, provided that you release 1870the Modified Version under precisely this License, with the Modified 1871Version filling the role of the Document, thus licensing distribution 1872and modification of the Modified Version to whoever possesses a copy 1873of it. In addition, you must do these things in the Modified Version: 1874 1875@enumerate A 1876@item 1877Use in the Title Page (and on the covers, if any) a title distinct 1878from that of the Document, and from those of previous versions 1879(which should, if there were any, be listed in the History section 1880of the Document). You may use the same title as a previous version 1881if the original publisher of that version gives permission. 1882 1883@item 1884List on the Title Page, as authors, one or more persons or entities 1885responsible for authorship of the modifications in the Modified 1886Version, together with at least five of the principal authors of the 1887Document (all of its principal authors, if it has less than five). 1888 1889@item 1890State on the Title page the name of the publisher of the 1891Modified Version, as the publisher. 1892 1893@item 1894Preserve all the copyright notices of the Document. 1895 1896@item 1897Add an appropriate copyright notice for your modifications 1898adjacent to the other copyright notices. 1899 1900@item 1901Include, immediately after the copyright notices, a license notice 1902giving the public permission to use the Modified Version under the 1903terms of this License, in the form shown in the Addendum below. 1904 1905@item 1906Preserve in that license notice the full lists of Invariant Sections 1907and required Cover Texts given in the Document's license notice. 1908 1909@item 1910Include an unaltered copy of this License. 1911 1912@item 1913Preserve the section entitled ``History'', and its title, and add to 1914it an item stating at least the title, year, new authors, and 1915publisher of the Modified Version as given on the Title Page. If 1916there is no section entitled ``History'' in the Document, create one 1917stating the title, year, authors, and publisher of the Document as 1918given on its Title Page, then add an item describing the Modified 1919Version as stated in the previous sentence. 1920 1921@item 1922Preserve the network location, if any, given in the Document for 1923public access to a Transparent copy of the Document, and likewise 1924the network locations given in the Document for previous versions 1925it was based on. These may be placed in the ``History'' section. 1926You may omit a network location for a work that was published at 1927least four years before the Document itself, or if the original 1928publisher of the version it refers to gives permission. 1929 1930@item 1931In any section entitled ``Acknowledgments'' or ``Dedications'', 1932preserve the section's title, and preserve in the section all the 1933substance and tone of each of the contributor acknowledgments 1934and/or dedications given therein. 1935 1936@item 1937Preserve all the Invariant Sections of the Document, 1938unaltered in their text and in their titles. Section numbers 1939or the equivalent are not considered part of the section titles. 1940 1941@item 1942Delete any section entitled ``Endorsements''. Such a section 1943may not be included in the Modified Version. 1944 1945@item 1946Do not retitle any existing section as ``Endorsements'' 1947or to conflict in title with any Invariant Section. 1948@end enumerate 1949 1950If the Modified Version includes new front-matter sections or 1951appendices that qualify as Secondary Sections and contain no material 1952copied from the Document, you may at your option designate some or all 1953of these sections as invariant. To do this, add their titles to the 1954list of Invariant Sections in the Modified Version's license notice. 1955These titles must be distinct from any other section titles. 1956 1957You may add a section entitled ``Endorsements'', provided it contains 1958nothing but endorsements of your Modified Version by various 1959parties---for example, statements of peer review or that the text has 1960been approved by an organization as the authoritative definition of a 1961standard. 1962 1963You may add a passage of up to five words as a Front-Cover Text, and a 1964passage of up to 25 words as a Back-Cover Text, to the end of the list 1965of Cover Texts in the Modified Version. Only one passage of 1966Front-Cover Text and one of Back-Cover Text may be added by (or 1967through arrangements made by) any one entity. If the Document already 1968includes a cover text for the same cover, previously added by you or 1969by arrangement made by the same entity you are acting on behalf of, 1970you may not add another; but you may replace the old one, on explicit 1971permission from the previous publisher that added the old one. 1972 1973The author(s) and publisher(s) of the Document do not by this License 1974give permission to use their names for publicity for or to assert or 1975imply endorsement of any Modified Version. 1976 1977@item 1978COMBINING DOCUMENTS 1979 1980You may combine the Document with other documents released under this 1981License, under the terms defined in section 4 above for modified 1982versions, provided that you include in the combination all of the 1983Invariant Sections of all of the original documents, unmodified, and 1984list them all as Invariant Sections of your combined work in its 1985license notice. 1986 1987The combined work need only contain one copy of this License, and 1988multiple identical Invariant Sections may be replaced with a single 1989copy. If there are multiple Invariant Sections with the same name but 1990different contents, make the title of each such section unique by 1991adding at the end of it, in parentheses, the name of the original 1992author or publisher of that section if known, or else a unique number. 1993Make the same adjustment to the section titles in the list of 1994Invariant Sections in the license notice of the combined work. 1995 1996In the combination, you must combine any sections entitled ``History'' 1997in the various original documents, forming one section entitled 1998``History''; likewise combine any sections entitled ``Acknowledgments'', 1999and any sections entitled ``Dedications''. You must delete all sections 2000entitled ``Endorsements.'' 2001 2002@item 2003COLLECTIONS OF DOCUMENTS 2004 2005You may make a collection consisting of the Document and other documents 2006released under this License, and replace the individual copies of this 2007License in the various documents with a single copy that is included in 2008the collection, provided that you follow the rules of this License for 2009verbatim copying of each of the documents in all other respects. 2010 2011You may extract a single document from such a collection, and distribute 2012it individually under this License, provided you insert a copy of this 2013License into the extracted document, and follow this License in all 2014other respects regarding verbatim copying of that document. 2015 2016@item 2017AGGREGATION WITH INDEPENDENT WORKS 2018 2019A compilation of the Document or its derivatives with other separate 2020and independent documents or works, in or on a volume of a storage or 2021distribution medium, does not as a whole count as a Modified Version 2022of the Document, provided no compilation copyright is claimed for the 2023compilation. Such a compilation is called an ``aggregate'', and this 2024License does not apply to the other self-contained works thus compiled 2025with the Document, on account of their being thus compiled, if they 2026are not themselves derivative works of the Document. 2027 2028If the Cover Text requirement of section 3 is applicable to these 2029copies of the Document, then if the Document is less than one quarter 2030of the entire aggregate, the Document's Cover Texts may be placed on 2031covers that surround only the Document within the aggregate. 2032Otherwise they must appear on covers around the whole aggregate. 2033 2034@item 2035TRANSLATION 2036 2037Translation is considered a kind of modification, so you may 2038distribute translations of the Document under the terms of section 4. 2039Replacing Invariant Sections with translations requires special 2040permission from their copyright holders, but you may include 2041translations of some or all Invariant Sections in addition to the 2042original versions of these Invariant Sections. You may include a 2043translation of this License provided that you also include the 2044original English version of this License. In case of a disagreement 2045between the translation and the original English version of this 2046License, the original English version will prevail. 2047 2048@item 2049TERMINATION 2050 2051You may not copy, modify, sublicense, or distribute the Document except 2052as expressly provided for under this License. Any other attempt to 2053copy, modify, sublicense or distribute the Document is void, and will 2054automatically terminate your rights under this License. However, 2055parties who have received copies, or rights, from you under this 2056License will not have their licenses terminated so long as such 2057parties remain in full compliance. 2058 2059@item 2060FUTURE REVISIONS OF THIS LICENSE 2061 2062The Free Software Foundation may publish new, revised versions 2063of the GNU Free Documentation License from time to time. Such new 2064versions will be similar in spirit to the present version, but may 2065differ in detail to address new problems or concerns. See 2066@uref{http://www.gnu.org/copyleft/}. 2067 2068Each version of the License is given a distinguishing version number. 2069If the Document specifies that a particular numbered version of this 2070License ``or any later version'' applies to it, you have the option of 2071following the terms and conditions either of that specified version or 2072of any later version that has been published (not as a draft) by the 2073Free Software Foundation. If the Document does not specify a version 2074number of this License, you may choose any version ever published (not 2075as a draft) by the Free Software Foundation. 2076@end enumerate 2077 2078@page 2079@appendixsubsec ADDENDUM: How to use this License for your documents 2080 2081To use this License in a document you have written, include a copy of 2082the License in the document and put the following copyright and 2083license notices just after the title page: 2084 2085@smallexample 2086@group 2087 Copyright (C) @var{year} @var{your name}. 2088 Permission is granted to copy, distribute and/or modify this document 2089 under the terms of the GNU Free Documentation License, Version 1.1 2090 or any later version published by the Free Software Foundation; 2091 with the Invariant Sections being @var{list their titles}, with the 2092 Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}. 2093 A copy of the license is included in the section entitled ``GNU 2094 Free Documentation License''. 2095@end group 2096@end smallexample 2097 2098If you have no Invariant Sections, write ``with no Invariant Sections'' 2099instead of saying which ones are invariant. If you have no 2100Front-Cover Texts, write ``no Front-Cover Texts'' instead of 2101``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts. 2102 2103If your document contains nontrivial examples of program code, we 2104recommend releasing these examples in parallel under your choice of 2105free software license, such as the GNU General Public License, 2106to permit their use in free software. 2107 2108@c Local Variables: 2109@c ispell-local-pdict: "ispell-dict" 2110@c End: 2111 2112@node Concept Index, , Copying, Top 2113@unnumbered Concept Index 2114 2115@printindex cp 2116 2117@contents 2118 2119@bye 2120