Difference between revisions of "SourceCode Overview"

Latest revision as of 18:47, 19 September 2007

Warning : preliminary documentation This part is about the C++ SourceCode and Lua Scripts for SFZ.

Overview

 src/			: sfz c++ source files (.cpp)
 include/		: sfz c++ header files (.h)
 data/			: sfz data files
 data/lua/		: sfz lua scripts (.lua)
 lugre/src/		: lugre c++ source files (.cpp)
 lugre/include/	: lugre c++ header files (.h)
 lugre/lua/		: lugre lua scripts (.lua)

The c++ source code is in the src/ directory, the headers are in include/

The lua code is in the data/lua/ directory, one main.lua and several libs. Large parts of SFZ are coded in lua to ensure high flexibility and customizability without recompiling, while keeping performance critical code in C++.

Lugre is a lib/framework we use across multiple projects, with Lua-bindings for Ogre3d and several other utils (networking, sound, etc).

Data

the data/ dir contains all data, lua scripts are under data/lua/

 main.material				contains definitions of materials used by ogre
 OgreCore.zip				standard materials and fonts
 lua/					contains lua scripts
 lua/main.lua				central lua file
 lua/udata.lua				helper used for lua binding (luabind.h)

C++

For most things there are:

 include/thing.h  as header
 src/thing.cpp    for the actual code
 src/thing_L.cpp  for luabindings/wrappers

SFZ

 *main.cpp				main function
 
 *object.h .cpp _L.cpp			game object baseclass (for ships,asteroids,...)
 *location.h .cpp _L.cpp		group/sub-scenegraph hierarchy
 *objectcontroller.h .cpp _L.cpp	autopilot utils
 *physicform.h .cpp 			physics/collision info (so far empty)
 *resyncreceiver.h .cpp _L.cpp		receiving of position resync messages via tcp/udp
 *sfz_scripting.h .cpp			luabindings for global functions
 
 *GhoulPrimitives.h .cpp 		obsolete, geometry generation codesnippets
 *GhoulPrimitivesLoft.cpp		obsolete, geometry generation codesnippets
 *GhoulPrimitivesOgre.cpp		obsolete, geometry generation codesnippets
 *HUDElement2D.h .cpp _L.cpp		obsolete, aiming codesnippets
 

Lugre

All the Lugre files have the "lugre_" prefix which has been removed for clarity.

 *game.h   .cpp			mainclass, init, step, deinit
 *main.h   .cpp			boilerplate utils, parsing win32 commandline, opening win32 console window...
 
 *scripting.h .cpp			lua framework
 *scripting.ogre.cpp			luabindings for ogre utils
 *scripting.general.cpp		luabindings for misc utils
 *luaxml.h .cpp			luabinding for tinyxml parser
 *luabind.h				template class for luabindings of classes
 
 *ogrewrapper.h .cpp			central interface to ogre
 *robrenderable.h .cpp			util for custom geometry renderables
 *meshshape.h .cpp			used for mousepicking of meshes
 *widget.h .cpp _L.cpp			gui system core
 *beam.h .cpp _L.cpp			3d-beam-like geometry generator
 *bitmask.h .cpp _L.cpp		2d image mousepicking mask utils
 
 *camera.h .cpp _L.cpp			luabinding for ogre cam
 *viewport.h .cpp _L.cpp		luabinding for ogre viewport
 *material.h .cpp _L.cpp		luabinding for ogre material
 *rendertexture.h .cpp _L.cpp		luabinding for ogre render-to-texture holder
 *gfx2D.h .cpp _L.cpp			luabinding for 2D graphics
 *gfx3D.h .cpp _L.cpp			luabinding for 3D graphics
 
 *SortedOverlayContainer.h		gui-element class (z-ordering)
 *BorderColourClipPaneOverlay.h	gui-element class (border rect)
 *ColourClipPaneOverlay.h		gui-element class (rect)
 *ColourClipTextOverlay.h		gui-element class (text)
 *RobRenderableOverlay.h		gui-element class (custom 2D geometry)
 
 *sound.h .cpp _L.cpp			sound and musik wrapper
 *sound_fmod.cpp			sound implementation using fmod
 *sound_openal.cpp			sound implementation using openal
 
 *net.h .cpp _L.cpp			networking
 *fifo.h _L.cpp			general purpose first in first out buffer, used by net
 
 *prefix.h				should be included first in every source file, for os specific macros
 *shell.h .cpp				os specific utils : directory listing, timer, ...
 *input.h .cpp				keyboard, mouse, see also ogrewrapper.cpp for OIS access
 *listener.h .cpp			baseclass for listener pattern
 *smartptr.h				baseclass for smartptr design pattern
 *timer.h .cpp				timed callbacks, stepper, fps-calc, etc
 *profile.h .cpp			runtime callstack and calltime measurement
 *tiny?.h ?.cpp			tiny xml parser
 *robstring1.2.h .cpp			string utils
 *random.h .cpp _L.cpp			custom random utils used for procedural stuff
 

Lua

SFZ

 main.lua				main file				
 lib.mainmenu.lua			the menu before the game starts
 
 lib.client.lua			client
 lib.client.message.lua		client netmessage handling
 lib.server.lua			server
 lib.server.message.lua		server netmessage handling
 lib.netmessagelist.lua		network protocol
 		
 lib.object.lua			gameobject main file
 lib.object.movement.lua		orientation,movement
 lib.object.pos.lua			distance calc, global2local
 lib.object.search.lua			nearest, raypick
 lib.object.hp.lua			damage
 lib.object.shield.lua			shields
 lib.object.weapon.lua			firepower, cooldown
 lib.object.destroy.lua		cleanup,register listeners
 lib.object.container.lua		cargo,weaponslots
 lib.object.furniture.lua		tables,computers,grates,ladders...
 lib.object.hangar.lua			launch and dock fighters, exit in spacesuit
 
 lib.mission.lua			mission system
 lib.service.lua			service system for stations/planets, e.g. repair
 lib.target.lua			targeting system (next,prev,nearest...)
 lib.trade.lua				trading system buy/sell stuff
 lib.autopilot.lua			autopilot system
 lib.plugin.lua			plugin system
 lib.system.lua			solar systems
 lib.location.lua			group/sub-scenegraph hierarchy system
 lib.effect.lua			effect system, lasers,explosions...
 lib.music.lua				music system, tracklist, shuffles
 
 lib.shipedit.lua			ship editor
 lib.shipeditmodule.lua		modules/shipparts in editor
 lib.shipeditguess.lua			educated guessing of good ship positions
 lib.shipeditloadsave.lua		load and save ship-designs to disk
 
 lib.preview.lua			mesh to image via render-to-texture		
 lib.interior.walk.lua			walking around
 lib.shipvoxelgrid.lua			collision, interior
 lib.shipgfx.lua			optimising ship meshes, removing inner walls
 lib.loft.lua				geometry generation		
 testarea.lua				experiments
 
 lib.keybinds.lua			maps keys to actions, edit this to change your controls
 lib.keys.lua				networking enums for abstract key names
 
 lib.buymenu.lua			obsolete 
 lib.map.lua				obsolete
 lib.hud.lua				obsolete
 

Lugre

 lib.input.lua				keyboard/mouse events
 lib.gui.lua				gui : event distribution
 lib.guimaker.lua			gui : creation utils lowlevel
 lib.plaingui.lua			gui : creation utils highlevel
 lib.guiutils.lua			gui : logo,bottomline,fps-display
 lib.edittext.lua			gui : text-input fields
 lib.tooltip.lua			gui : tooltips
 lib.movedialog.lua			gui : dialog movement utils
 lib.chatline.lua			gui : text-input line at the bottom of the screen, chat history
 lib.fadelines.lua			gui : console-lines at the bottom slowly fading out
 lib.contextmenu.lua			gui : right-click menu
 lib.cursor.lua			gui : mouse-icon
 
 lib.listener.lua			listener system
 lib.material.lua			material utils
 lib.cam.lua				camera handling, 3rd person utils
 lib.netmessage.lua			network protocol framework
 lib.plugin.lua			plugin system
 lib.sound.lua				sound system
 lib.time.lua				timeout,stepper,fpscalc
 lib.types.lua				type system (flyweight design-pattern)
 
 lib.beam.lua				geometry generation
 lib.box.lua				geometry generation
 lib.primitive.lua			geometry generation
 lib.prism.lua				geometry generation
 lib.voxel.lua				mesh 2 voxel utils
 
 lib.util.lua				misc utils, vector, quaternion
 lugre.lua				main include file
 udata.lua				luabinding helper, loaded from c++ code early

notes

many c++ files come in pairs, like gfx3D.cpp and gfx3D_L.cpp _L contains the lua bindings
gfx3d and gfx2d are the main parts of the ogre lua binding
they capsule scenenodes and graphical entities
i.e. a scenenode with a mesh-entity in c++ ogre is capsuled in a gfx3d object in our code
there is also a big dump for lots of global lua function bindings in lugre/src/lugre_scripting*
we use a custom smartpointer thing that is a bit different from the usual definition of smartpointer
instead of releasing memory when all references are deleted, our smartpointers act as listeners to the death-event of the target, and set themselves to null if the target is destroyed
that is because most of the time objects and graphics are explicitly destroyed, but other code elements might be still tracking them
this way the others don't have to be manually notified that the target is gone, they can just check if the smartpointer is null
another point of interest is fifo.h , a general purpose buffer writer/reader
it has a lua binding and is used extensively for networking stuff
lugre_robstring.cpp has a few string utils i collected over the years in many different projects
it has a nice printf syntax that outputs an std::string that often comes in handy as i don't like the << syntax that much
also has explode and a few other utils, some of the code is also inlined in robstring.h but i think it isn't used too much in sfz as most string stuff is done in lua
shell.h has a few os-specific utils like listing files, getting timestamp, etc
input.h is a wrapper for some input systems, currently used with OIS that comes with ogre
also has keycode-name association
lugre_ogrewrapper.cpp is the ogre boilerplate and some utils (like screenshot, mousepicking)
that file kindof replaces the ogre example framework

what does the PROFILE do?

It was originally planned for measuring (profiling) code execution time and callcount, we mainly use it to provides stacktrace info in release builds. It should be written a the start of nearly all somewhat bigger functions that aren't called too often (to prevent performance hit). Tt's a trick using an empty object just to install a callback at function start and when the function returns (empty object is destroyed automatically when the stack is cleaned up). The code for it is in lugre/include/lugre_profile.h and lugre/src/lugre_profile.cpp . It enables some nice things, like including a stacktrace in warning and debug messages without interrupting the program