Difference between revisions of "SourceCode Overview"

Revision as of 11:49, 8 August 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.<br>
large parts of SFZ are coded in lua to ensure high flexibility, <br>
and customizability without recompiling, while keeping performance critical code in c++.

http://lugre.sf.net is a lib/framework we use across multiple projects, with Lua-bindings for Ogre3d and several other utils (networking,sound,...)

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++

outdated : this part needs to be updated to reflect the externalization of lugre

 for most things there are  
 include/thing.h  as header
 src/thing.cpp    for the actual code
 src/thing_L.cpp  for lua bindings/wrappers

*main.cpp			main function
*game.h .cpp			mainclass, init, step, deinit

*scripting.h .cpp		global interface for lua, and utils
*luabind.h			template class for lua binding
*luaxml.h .cpp			make tinyxml parser available for lua
(there are currently luabindings for data, builder, gfx2D, gfx3D, widget, fifo, luaxml,...)

*ogrewrapper.h .cpp		central interface to ogre
*robrenderable.h .cpp		util for custom renderables
*meshshape.h .cpp		used for mousepicking of meshes (statics,dynamics,chars)
*widget.h .cpp _L.cpp		managing for gui elements

*gfx2D.h .cpp _L.cpp		wrapper for 2D graphics
*gfx3D.h .cpp _L.cpp		wrapper for 3D graphics
*SortedOverlayContainer.h	gui-element class (z-ordering)
*BorderColourClipPaneOverlay.h	gui-element class
*ColourClipPaneOverlay.h	gui-element class
*ColourClipTextOverlay.h	gui-element class

*camera.h .cpp _L.cpp		lua binding for ogre cam
*viewport.h .cpp _L.cpp		lua binding for ogre viewport
*material.h .cpp _L.cpp		lua binding for ogre material
*rendertexture.h .cpp _L.cpp	lua binding for ogre render-to-texture holder

*sound.h .cpp _L.cpp		sound and musik wrapper
*sound_fmod.cpp			sound implementation using fmod
*sound_openal.cpp		sound implementation using openal

*prefix.h			should be included first in every source file, for os specific macros
*shell.h .cpp			obsolete, inits timer and random
*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

*net.h .cpp			networking
*fifo.h 			first in first out buffer, used by net

lua

outdated : this part needs to be updated to reflect the externalization of lugre

main.lua			main file

lib.guimaker.lua		core of the guisystem drin, utility functions for creating text-fields etc, no UO specific code
				sort of like the interface to the c++ gui code, and common shortcuts
lib.edittext.lua		text-input fields
lib.fadelines.lua		the messages at the bottom left of the screen that slowly fade away
lib.input.lua			keyboard and mouse events, keybindings
lib.plaingui.lua		simple gui, only used for teleport dialog in offline gameplay
lib.time.lua			calcs fps, calls MainStep from main.lua and calls registered steppers
lib.util.lua			some utilities, mainly vector and quaternion math
lib.xml.lua			xml-parser utils (see lib.gfm.lua for parser usage)

notes

<ghoulsblade> many c++ files come in pairs, like   gfx3D.cpp and gfx3D_L.cpp   _L contains the lua bindings
<ghoulsblade> gfx3d and gfx2d are the main parts of the ogre lua binding
<ghoulsblade> they capsule scenenodes and graphical entities 
<ghoulsblade> i.e.  a scenenode with a mesh-entity in c++ ogre is capsuled in a gfx3d object in our code
<ghoulsblade> there is also a big dump for lots of global lua function bindings in   lugre/src/lugre_scripting*
<ghoulsblade> we use a custom smartpointer thing that is a bit different from the usual definition of smartpointer
<ghoulsblade> 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
<ghoulsblade> that is because most of the time objects and graphics are explicitly destroyed,  but other code elements might be still tracking them
<ghoulsblade> 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
<ghoulsblade> another point of interest is fifo.h  , a general purpose buffer writer/reader
<ghoulsblade> it has a lua binding and is used extensively for networking stuff
<ghoulsblade> lugre_robstring.cpp has a few string utils i collected over the years in many different projects
<ghoulsblade> 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
<ghoulsblade> 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
<ghoulsblade> shell.h has a few os-specific utils like listing files, getting timestamp, etc
<ghoulsblade> input.h is a wrapper for some input systems, currently used with OIS that comes with ogre
<ghoulsblade> also has keycode-name association 
<ghoulsblade> lugre_ogrewrapper.cpp is the ogre boilerplate and some utils (like screenshot, mousepicking) 
<ghoulsblade> that file kindof replaces the ogre example framework