Adonthell 0.4

intro.dxt

00001 /*
00002    $Id: intro.dxt,v 1.1 2001/10/15 15:00:06 gnurou Exp $
00003 
00004    Copyright (C) 2001   Alexandre Courbot
00005    Copyright (C) 2001   Kai Sterker
00006    Part of the Adonthell Project http://adonthell.linuxgames.com
00007 
00008    This program is free software; you can redistribute it and/or modify
00009    it under the terms of the GNU General Public License.
00010    This program is distributed in the hope that it will be useful,
00011    but WITHOUT ANY WARRANTY.
00012 
00013    See the COPYING file for more details.
00014 */
00015 
00016 /*!
00017  \page page1 Introduction for new programmers
00018  \section cpp C++
00019 
00020  Adonthell makes intense use of the features of C++ whenever they make the code
00021  clearer and easier and do not slow things down too much. Adonthell tries to
00022  respect the concepts of Object Oriented Programming as much as possible. In
00023  Adonthell, everything is an %object and inheritance and templates are used 
00024  where appropriate. Attributes are usually hidden and may only be accessed
00025  through an %object's methods.
00026 
00027  Further, Adonthell makes heavy use of the Standard Template Library (STL)
00028  (http://www.sgi.com/tech/stl/), especially of strings and containers 
00029  like lists and hash maps. So you'll certainly want to give it a look.
00030 
00031  \section python Python 
00032  In many kinds of computer games, including RPGs, a script language is necessary to command
00033  characters, build complex actions, cutscenes, etc... As we want modularity and
00034  reusability, in-%game actions must be real-time interpreted. Scripts need to
00035  interact with the C++ interface and of course they have to share variables with it.
00036  Python (http://www.python.org) has proven to be very efficient at both - 
00037  moreover it is an object-oriented language and therefore fits well with C++.
00038  And with SWIG (http://www.swig.org), a great tool is available to automate the 
00039  process of building the Python interface to our C++ classes.
00040  Basically, each class and method described in this document is also available
00041  from Python scripts, with only a few exceptions:
00042  Python allows no method and operator overloading, so only the first of 
00043  overloaded methods or constructors and no operators are accessible from
00044  Python.
00045 
00046  \section scorg Source code organisation 
00047  Adonthell makes use of autoconf and automake to be built. In each subdirectory  
00048  resides a Makefile.am file that containes the building rules for the files inside
00049  that directory as well as its subdirectories. Running "automake" in the root
00050  directory creates a Makefile.in from each Makefile.am. "autoconf" builds the 
00051  configure script from configure.in. Finally, running "./configure" generates
00052  all the Makefiles from the Makefile.ins, making the package ready for 
00053  compilation via "make".
00054 
00055  Here is what the source tree does look like:
00056 
00057  - doc The user and developer documentation  
00058  - src Source code for Adonthell engine - this is where the adonthell executable is built
00059    - tools Various development tools
00060       - dlgedit The dialogue editor (requires GTK+)
00061       - charedit The character editor (requires GTK+)
00062       - questedit The quest editor (requires GTK+)
00063       - maptools The map building tools
00064       - pydonthell A custom Python interpreter with Adonthell Python modules inside
00065       - oggloop Ogg music looping utility
00066 
00067  Each class that is documented here is usually defined by classname.h and
00068  implemented by classname.cc.
00069 
00070  \section datatypes Data types 
00071  Adonthell can run on several platforms, which all have different characteristics.
00072  One of these differences can reside in the way the basic C types (char, ints, ...)
00073  are encoded. A 32 bit operating system will code it's ints with 32 bits, while a
00074  64 bits operating system will use 64 bits for ints. For several operations (like
00075  reading an int from a file) this can result in different behavior, and catastrophic
00076  consequences (most likely a protection fault). That's why some of the most basic
00077  types have been redifined according to the architecture in types.h:
00078  - u_int8: unsigned 8 bit integer
00079  - s_int8: signed 8 bit integer
00080  - u_int16: unsigned 16 bit integer
00081  - s_int16: signed 16 bit integer
00082  - u_int32: unsigned 32 bit integer
00083  - s_int32: signed 32 bit integer
00084 
00085  \section gamedyn Game dynamic
00086  As we display animated things, we need to know when they have to change. A %game that
00087  runs at a different speed on various machines has nearly no interest, as only
00088  a few configurations can make it run at the right speed. So it's very important
00089  to have a timing system built into the %game engine.
00090  
00091  Adonthell uses it's own timing system. The time unit is the %game cycle, which
00092  corresponds to approximatively 1/70 of second. When the %game runs, it performs
00093  a loop which looks like this:
00094 
00095  \code
00096  while(<condition to quit the engine>) 
00097  { 
00098      gametime::update();
00099 
00100      for(i=0;i<gametime::get_frames_to_do();i++) 
00101      {
00102          <update the %game status (%character positions, etc...)> 
00103      }
00104 
00105      <perform drawing operations>
00106  }
00107  \endcode
00108 
00109  Explanations:
00110 
00111  This loop performs what is necessary to update the %screen. Depending on the speed
00112  of the CPU, this can take more or less time. You've seen that a %game cycle durate
00113  1/70 of a second. For some machines, this is not enough to perform the entire loop.
00114 
00115  As you've seen, there are two kinds of operations that are in the loop:
00116 
00117  \li Update operations, which actually update the state of the %game, according to
00118      user %input, previous %game state, etc... These operations are very fast to
00119      perform.
00120 
00121  \li Drawing operations, that is, update the %screen. This is what may slow
00122      things down. Some graphic boards simply can't redraw the entire %screen 70
00123      times per second. Moreover, even with high-end boards, hardware acceleration may
00124      not be used depending on the SDL target used. x11 is know to be unable to use 
00125      hardware acceleration, while fbcon does, when possible.
00126 
00127  So the solution to keep the %game running at the same speed on every machine is to
00128  draw less frames per second on slow machines (instead of drawing 1 frame every %game
00129  cycle, we'll draw one frame for 2 %games cycles, for example). This is where
00130  gametime is usefull: The gametime::update() method calculates the delay between
00131  the last call and the current call. It can then calculate if we've been late, and
00132  catch the time back by telling to the other %objects that we must perform 2 %games
00133  cycles instead of 1 to be sync (this is the result of the gametime::get_frames_to_do()
00134  method). For example, if the last loop took 1/35 of a second to be completed,
00135  gametime::get_frames_to_do() will return 2, so the loop will perform 2 %game updates
00136  before drawing the %screen. On the contrary, if the machine is too fast (if it can
00137  draw 2 frames for each %game cycle, for example), it will usleep() to stay in sync.
00138 
00139  In a more general manner, every class that get's updated and draw something on
00140  the %screen MUST have an update() method, that updates it's state once, and a
00141  draw() method to draw it on the %screen.
00142  
00143  */