[Teleus-cvs] teleus/src/game game.cpp,1.15,1.16 tscript.cpp,1.6,1.7

[<sp...@us...>]

Update of /cvsroot/teleus/teleus/src/game
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv6480/src/game

Modified Files:
	game.cpp tscript.cpp 
Log Message:
Code reviewed and comments updated.

Index: game.cpp
===================================================================
RCS file: /cvsroot/teleus/teleus/src/game/game.cpp,v
retrieving revision 1.15
retrieving revision 1.16
diff -C2 -d -r1.15 -r1.16
*** game.cpp	25 Feb 2004 02:25:44 -0000	1.15
--- game.cpp	25 Feb 2004 06:34:02 -0000	1.16
***************
*** 516,517 ****
--- 516,716 ----
  } // END NAMESPACE teleus
  
+ /**
+ \mainpage
+ 
+ \section intro Introduction
+ 
+ This is the documentation for the Teleus Space Combat Game.
+ The official website is located at <a
+ href="http://teleus.sf.net">teleus.sf.net</a>.  Please visit
+ that site for more information about the game in general.
+ 
+ This documentation is intended for developers working on the
+ Teleus game.  All of the code is available on these pages (also,
+ you can download the code from the <a
+ href="http://sourceforge.net/projects/teleus/">Teleus CVS
+ server</a> provided by <a
+ href="http://www.sourceforge.net">Sourceforge.net</a>).
+ 
+ On this main page, I'll overview the engine's current structure.
+ The details of the engine and all of its constituent classes,
+ structs, functions, <i>et cetera</i> can be found on the other
+ pages; the generated comments take precedence over this page.
+ 
+ \section form Code Format
+ 
+ The code is divided into a number of namespaces.  The
+ <tt>teleus</tt> namespace is the top-level namespace in which
+ most of the game's code is located.  There are a number of
+ sub-namespaces inside the <tt>teleus</tt> namespace, such as
+ <tt>rs</tt> (resource), <tt>math</tt>, <tt>gfx</tt>,
+ <tt>input</tt>, and so on.  All of the code under a certain
+ namespace is located in files in directories of the same name as
+ the namespace.  For example, all </tt>gfx</tt> code is located
+ in <tt>src/gfx/</tt>.
+ 
+ The <tt>src/game</tt> directory is for the <tt>teleus</tt>
+ namespace.  The <tt>game/</tt> directory stores all of the
+ global files that are located directly in the teleus namespace
+ (except for some lua/c interfacing functions, which are located
+ in the <tt>inscript</tt> namespace).
+ 
+ When including a file from another namespace, you must include
+ the directory.  For example:
+ 
+ \code
+ #include "gfx/camera.hpp"
+ #include "math/vector.hpp"
+ \endcode
+ 
+ This does not apply to the stuff in the <tt>src/game/</tt>
+ directory.  For example:
+ 
+ \code
+ #include "debug.hpp"
+ #include "tnamespace.hpp"
+ \endcode
+ 
+ \section ns Namespaces
+ 
+ There are currently seven sub-namespaces inside of the teleus
+ namespace: inscript, gfx, input, math, obj, rs, and util.  You
+ can find brief descriptions of all namespaces in the Teleus
+ Namespace List.
+ 
+ \subsection ns-inscript Lua/C Interface
+ 
+ All <a href="http://www.lua.org/">Lua</a> specific code is
+ located in the <tt>src/game/tscript.?pp</tt> files (where
+ <tt>?</tt> is either <tt>c</tt> or <tt>h</tt>).  Most of it is
+ code that allows C/C++ functions and methods access to the Lua
+ virtual machine.  For example, luaT_loadFile() loads a script
+ file into the LuaVM.  luaT_executeScript() loads and runs a
+ script.
+ 
+ All of the exported C/C++ functions are located directly in the
+ teleus namespace since Lua is a fundamental part of the engine.
+ All of the C functions that are exported as Lua functions are in
+ a sub-namespace called <tt>inscript</tt>.  These functions are
+ very recognizable because they all have the same prototype:
+ <tt>int teleus::inscript::luaT_<i>functionname</i> (lua_State
+ 					 *luaVM)</tt>.
+ 
+ The <tt><i>functionname</i></tt> part of the function's name is
+ a hint to what the Lua name is.  The Lua function is registered
+ in the Lua namespace teleus with a function name equivalent to
+ the C function's name, except the Lua function is all lowercase.
+ For example, luaT_logError() is registered as
+ <tt>teleus.logerror</tt>.  The names of the exported functions
+ are usually included in the function's comments.  And you can
+ always check out the luaopen_teleus() function to see the
+ exported functions being registered.
+ 
+ All Teleus Lua function names are prefixed with <tt>luaT_</tt>
+ to follow the Lua naming convention (except the luaopen_teleus()
+ function, which is named so to follow suit of
+ the luaopen_base, luaopen_math, <i>et
+ cetera</i>).
+ 
+ \subsection ns-gfx Graphics Code
+ 
+ All graphics specific code is located in the
+ <tt>src/gfx</tt> files.  The current heavy hitters in the
+ gfx namespace are the gfx.cpp, gfx.hpp, wm.cpp,
+ wm.hpp, camera.cpp, and camera.hpp files.  All
+ OpenGL code is located in these files (and
+ <i>only</i> these files).
+ 
+ The <tt>gfx.?pp</tt> files contain thin wrapper functions for
+ OpenGL.  These functions are not intended to allow the game to
+ be ported to Direct3d or other such 3d APIs.  These functions
+ are intended only to localize all OpenGL calls.  (It might be
+ possible to create a Direct3d version of these functions for
+ compile-time switching, but I don't know enough about Direct3d.)
+ 
+ The <tt>camera.?pp</tt> files contain a Camera class.  The
+ Camera class just encapsulates all OpenGL camera functionality.
+ I have decided that setting the viewing mode (ortho or
+ perspective) is not a camera operation; it is a standard
+ graphics operation.  The Camera class's purview is limited to
+ the location and orientation of the 3D perspective camera.  GUI
+ stuff, for example, is not part of the 3D perspective stuff, so
+ it won't be part of the camera.
+ 
+ The <tt>wm.?pp</tt> files contain thin wrapper functions for
+ SDL.  Again, these functions are not intended to allow the game
+ to be ported to other windows manager interface APIs.  These
+ functions are intended only to localize all SDL calls.
+ 
+ Currently, SDL serves two primary functions: providing an OpenGL
+ rendering context, and interfacing with the underlying operating
+ system for things like input.  The former is taken care of in
+ the <tt>gfx/wm.?pp</tt> files; the latter is taken care of in
+ the <tt>input/</tt> files.
+ 
+ \subsection ns-input Input Management
+ 
+ As of this writing, the input files have not yet been worked
+ out.  Eventually, all user input functionality will be localized
+ in these files.  Physics and interface update functions can
+ query these classes for information about the input devices'
+ current states.
+ 
+ Due to the wide variety of input hardware (especially with
+ keyboards), all input will be changeable via Lua scripted
+ bindings.  These bindings will be changeable in-game and by
+ editing the Lua scripts manually.
+ 
+ \subsection ns-math Math and Physics
+ 
+ Obviously, the math namespace is where all of the math and
+ physics functions and classes are located.  The physics
+ functions and the <tt>obj</tt> classes are closely tied, and the
+ division line is fuzzy.  The <tt>math/physics.?pp</tt> files
+ contain functions and constants for general math and physics
+ related calculations.  The <tt>math/geometry.?pp</tt> files
+ contain mathematical geometry classes (these classes are not
+ intended to be rendered directly).  The <tt>math/matrix.?pp</tt>
+ and <tt>math/vector.?pp> files contain typical matrix and vector
+ classes.
+ 
+ The <tt>math/random.?pp</tt> files contain a Random number
+ class.  This class is platform independent, so it should be
+ useful for determinism across platforms.  <tt>std::rand()</tt>
+ is, unfortunately, not standard across platforms.  This class
+ also allows the user to determine the random number's data type
+ and bounds.
+ 
+ Basically, anything that relates to pure, abstract mathematics
+ goes in this namespace.  Some classes are parents for gfx and
+ obj classes that provide more functionality.  For example, the
+ gfx::Sphere class is derived from a math class.
+ 
+ \subsection ns-obj In-Game Objects
+ 
+ The <tt>obj</tt> namespace contains all of the classes that
+ represent in-game objects.  These classes are a median between
+ the math classes and the gfx classes.  They aren't drawn, but
+ they contain more information than just mathematical attributes.
+ These classes also contain data that only makes sense in the
+ context of a game (for example, damage points for a ship or the
+ name of the owner, etc).
+ 
+ \subsection ns-rs Data Files and Resource Management
+ 
+ The <tt>rs</tt> namespace holds classes that load, unload, and
+ manage "resources".  A resource is basically media loaded from
+ files.  Scripts are not resources, and fonts are handled in the
+ gfx subsystem.  Since there is yet no media, this subsystem is
+ rather neglected.  There are a few classes, but none of them are
+ used and all will probably be replaced and reworked before they
+ are integrated into the engine.
+ 
+ \section moreinfo More Information
+ 
+ Visit the <a href="http://teleus.sf.net">Teleus website</a>
+ first.  Email one of the developers second (email addresses of
+ all the developers are on the website; currently it's just <a
+ href="mailto:sp...@us...">me</a>).
+ 
+ */

Index: tscript.cpp
===================================================================
RCS file: /cvsroot/teleus/teleus/src/game/tscript.cpp,v
retrieving revision 1.6
retrieving revision 1.7
diff -C2 -d -r1.6 -r1.7
*** tscript.cpp	25 Feb 2004 02:19:50 -0000	1.6
--- tscript.cpp	25 Feb 2004 06:34:02 -0000	1.7
***************
*** 514,523 ****
   * This function loads and executes a script.
   *
-  * \param file the file path to the script
-  * \returns the result of the run
-  *
   * \author Daniel Royer
!  * \note The param and returns information are for the Lua
!  * function, not for the C function.
   * \todo Double-check the return value of lua_tostring.  Do I
   * need to free that memory?
--- 514,519 ----
   * This function loads and executes a script.
   *
   * \author Daniel Royer
!  *
   * \todo Double-check the return value of lua_tostring.  Do I
   * need to free that memory?
***************
*** 636,652 ****
   * log.  This function works just like the Lua \c print function.
   *
-  * \param str the string to be written to the log.  This function
-  * accepts any number of strings, just like lua's print() function.
-  * Use Lua's \c string.format function to get printf-like formating
-  * capabilities.
-  *
-  * \returns nothing
-  *
   * \note Unlike Log::record(), this function appends a newline
   * character to the output, just like Lua's \c print function
   * does.
-  *
-  * \note The param and returns information are for the Lua
-  * function, not for the C function.
   */
  int inscript::luaT_logRecord (lua_State *luaVM){
--- 632,638 ----
***************
*** 665,682 ****
   * log.  This function works just like the Lua \c print function.
   *
-  * \param str the string to be written to the log.  This function
-  * accepts any number of strings, just like Lua's \c print function.
-  * Use Lua's \c format function to get printf-like formating
-  * capabilities.
-  *
-  * \returns nothing
   *
   * \note Unlike Log::error(), this function appends a newline
   * character to the output, just like Lua's print() function
   * does.
-  *
-  * \note The param and returns information are for the lua
-  * function, not for the c function.
-  *
   */
  int inscript::luaT_logError (lua_State *luaVM){
--- 651,658 ----
***************
*** 727,739 ****
   * disparity between the c++ code and the lua code.
   *
-  * \param key the key of the setting to be written
-  * \param value the new value (a number, string, or boolean)
-  * \returns nothing
-  *
   * \todo This function does not yet change the lua variable
   *
-  * \note The param and returns information are for the lua
-  * function, not for the c function.
-  *
   */
  int inscript::luaT_writeUserSetting (lua_State *luaVM){
--- 703,708 ----
***************
*** 772,784 ****
   * disparity between the c++ code and the lua code.
   *
-  * \param key the key of the setting to be written
-  * \param value the new value (a number, string, or boolean)
-  * \returns nothing
-  *
   * \todo This function does not yet change the lua variable
-  *
-  * \note The param and returns information are for the lua
-  * function, not for the c function.
-  *
   */
  int inscript::luaT_writeGlobalSetting (lua_State *luaVM){
--- 741,745 ----