This document is last updated to state of Teddy version 1.55.
Please send me email to
and tell me what things you have had trouble with, so I can improve
this text. Thank you.
Getting Started with glElite and Teddy
This document describes briefly how to get started
working on this project. I will refer to this project
as 'Teddy' from now on; it will also cover anything
for glElite as well though.
Notes about environment, library and tool requirements
Teddy is intendent to work on multiple platforms,
although only Win32 and linux environments have been
tested so far.
Teddy is written in C++, and uses STL, so you will
need a compiler which supports these; LCC for example
will not work. I have used Visual Studio 6 in Win32
environment and g++ in linux. Project and workspace
files are provided for Visual Studio 6, and configure
script is provided for linux. I have been trying to
make Teddy build with Cygwin / MingW as well, but so
far I have not succeeded.
Teddy depends on several libraries, which you need
before you can build Teddy.
The most important library is
the Simple Directmedia Library - SDL. On linux environment
SDL is easy to setup for development using standard
configure && make && make install procedure.
In Win32 it is best to use the libraries included in my
source release archive, or rebuild the library yourself.
You need to be familiar with building and installing libraries
and their headers. I recommend following settings for all
libraries: debug: 4 byte structure alignment, debug
multithreaded dll runtime libraries, release: 4 byte structure
alignment, multithreaded dll runtime libraries. That will make
sure the structures are compatible with SDL, and that the
runtime libraries are compatible with Teddy. Postfix debugging
versions of the libraries with 'D'.
The SDL library is the only required library. Others are optional,
but highly recommended.
Windows users should notice that libjpeg, libpng and libz are
packed together with SDL_image. So if you are Windows developer,
you will only need SDL and optionally SDL_image and SDL_mixer.
Documentation for Teddy is generated using
Doxygen is not required to build and test Teddy, but reading
it's documentation of Doxygen might be a good idea, so that
you know how to place documentation into sourcecode. Doxygen is
only required to regenerate and update documentation from the
Registering at sourceforge and getting sources
First you should
register yourself at sourceforge
and let me know about you so I can add you to the team.
At the moment our team is small, and anyone who is willing
to contribute is welcome.
You should also join the
glElite developers mailinglist.
There has been hardly any traffic at all there yet, so don't be
afraid of getting flooded. I would very much like to use the
mailing list for all glElite and Teddy related discussion as
primary forum and media.
To get started, you need sources. You can grab almost latest
source .zip or .tar.gz directly from
the glElite web page
for quick look (also remember to get the separate data file).
For any real work though you really should use the concurrent
version control system, CVS. If you are not familiar with CVS,
The CVS Book.
When you are more familiar with CVS (basics), you can access
Teddy CVS here.
Files in the source package
Files in Teddy are arranged as follows:
- C++ source files in Teddy/src should need no more explanation.
- Documentation files in Teddy/src are mostly embedded into
sourcecode. Text files are in the root directory Teddy/ are sort of GNU
standard files, but I have not much experience about these.
- Project, workspace and build files come in two
versions; for Win32 and for linux environment. You should not edit
Visual studio project or workspace files manually.
- Runtime data files are required to actually run Teddy when
you have managed to build it. You must have these data files
in the current directory when you run Teddy, so you should copy the
executable to whereever you have the data files, and execute Teddy in
that directory. In Windows environment, the data files are in directory
named TeddyRelease, and Visual Studio project automatically places the
executable to that directory. In linux you will need to copy the executable
Notice that in some releases some data files may be copyrighted and not
distributed with the source.
- CVS files must be left untouched; they contain important
version control information.
- Other files contains at least the fix.sh
script file in the root directory. It can be used to convert
windows line endings to unix line endings. You should try to run this
if you have modified sources in Win32 environment. Theoretically CVS
should fix line endings properly, but I still need to use fix.sh.
Once you have got your working copy of sources, browse
them. I have arranged sources into sub-directories, each
of which make up static library, which are linked together
with sources in the root source directory to make up the
- Graphics contains the lower part of graphics
rendering architecture of Teddy. Other parts are in several
other modules. You should at least know that PhysicalComponents
module has Projection class, which is responsible for applying
materials and rendering any 3D graphics. Note that while
some parts of OpenGL have been encapsulated into View class in
Graphics, there are still a lot of direct OpenGL calls all over
- Imports contains object loaders, at the moment
from LightWave and experimental Frontier: First Encounters
ship model extractor. The FFE ship model extractor needs
data files which are not distributed with source. Some
lightwave ships are also not distributed with the source.
- Materials contains lower part of material
architecture of Teddy. It also contains the initial
texture mapping routines. The upper part of material
architecture is implemented in Projection class of
PhysicalComponents module, and View class of Graphics
- Maths contains low level mathematical routines.
One of the oldest parts of Teddy. Some classes are written
in hurry and used for few things only.
- Models contains the Model and ModelInstance
presentation and operations. The Model architecture in
Teddy is hierarchial. ModelInstance is a single instance
of some Mesh. Mesh represents the shape of some object
type. Mesh is (usually) made of Elements. For example,
LightWave objects are made of Face Elements. LineMesh is
made of Line Elements, etc. Mesh can also contain a submesh.
Each mesh has material information.
- PhysicalComponents contains user interface
architecture for Teddy. This architecture contains an
optional full-featured (planned) windowing system and
some basic components. Most of it is work in progress. You
should know about the Projection class. The Area class is
baseclass for all user interface components, looking at it
- Scenes contains scene and camera related
stuff of Teddy.
- SysSupport contains directory scanning
routines, precise (hopefully) timer code and type
- Teddy in the root source directory is the
main application. The UI class contains all highlevel
testing environment setup and runtime operations.
- TinyGL is a small OpenGL subset software
renderer. The the platform has no native OpenGL support,
TinyGL will be used instead. It lacks some features like
alpha blending, but is still much better than no support
at all. Notice that MESA software rendering is external
to Teddy, and thus considered 'native'. MESA has alpha
blending, but TinyGL might be faster.
- UniverseDevelopmentKit is Sean O'Neils
creation, which contains basic mathematics classes
and spherical ROAM algorithm. These sources are
maintained by Sean O'Neil, and I try to make as few
changes as possible to these sources.
Teddy uses two threads: the main thread, and simulation timer.
The main thread sits in a loop updating graphics display and
polling events, running as fast as possible (we might want to
add limit here on really superfast machine, no need to render
more frames that refresh frequence of monitor..).
The simulation thread maintains system time. It also processes
currently active events (keys pressed down etc) as updated by
the main thread. Events are forwarded to Input::FocusManager,
which eventually forwards events to individual physical user
interface components. Components then invoke user interface
logical actions, which are part of UI class in the testing
environment. Finally, the simulation thread updates physics
At the moment there is no concurrency management at all. It
does not matter now, but critical data structures should be
At the moment there is a lot of work that needs to be done. The list below
contains some things in unsorted order. Feel free to attack any of these
problems, and or list new ones! I am sure we can make this list a long one..
- There is no game what so ever. Simple physics
simulation with collision detection and laser beams
might be fun to try; I think current version of Teddy
has required features so that simple game protos could
be placed on top of it.
- Physics simulation code is almost non-existent; there is
simple collision checking working in progress, but no ships,
no weapons.. One possibility
to get some game would be to integrate Christian Pinders
Elite - The New Kind into glElite. Elite - The New Kind
has reverse-engineered C source for the original 8-bit Elite.
The copyright issues of straight Elite conversions should
be resolved though; it is unlikely that we could release
glElite under any GNU license.
- Rendering architecture should be improved so that it
knows and uses vertex arrays (including compiled
vertex arrays and NVidia stuffs) - At the moment Teddy
uses very unoptimized rendering, no vertex arrays, not
even displaylists. There is code for displaylists, which
has been used before reworking materials.
The ROAM code contains and uses vertex arrays, which
also uses NVidia range and fence extensions, but only
in Win32 when compiled with MSVC.
- The ROAM code has now been updated, now for a second time. It
still needs some tuning, but it certainly is better now.
- Rendering architecture should be improved so that it
knows how to get best performance when handling materials.
Applying different material means OpenGL state change, which
is usually slow; At the moment I try to group ModelInstances
by material, but it simply does not work, because objects
are hierarchial, and each submesh has it's own material.
- Rendering architecture should be improved so that it
knows how to do multiple depth buffer passes, or something,
to get rid of limited depth buffer precision.
- I would like to have alpha blending effects like explosions
and engine glows added to the rendering architecture. Some of
these need that vertices are manually projected to screen
- Texture support needs testing and improving.
Multitexturing is not yet used.
- Smoothing meshes (normals) is way too primitive at the moment.
All normals are currently shared, but that really works only
on really smooth surface like sphere. For other surfaces, the
very same vertex may have different normal on different face.
This is the case for a sharp-edged cube, for example.
- Linux configure etc. scripts should be reviewed and improved.
I am not a linux expert, so the scripts are far from standard.
- A proper installer for both Win32 and linux would be nice; there
is none for either at the moment.
- The physical user interface component class hierarchy is very
experimental. It would be nice to get something robust out of it
eventually. It might be a good idea to get some basic components
working 'soon', as they potentially could help development.
- The existing code does not pay much attention to memory leaks
(which are guaranteed to exist). Destructors should be properly
implemented at some point.
- Documentation can always be improved.
Frequently asked questions about glElite / Teddy development
What is CVS, must I use it, and how do I do that?
CVS is concurrent version control system. It maintains file
consistency when multiple users are working on the project
at same time. It even enables to users to modify same files
at the same time. It is essential that everyone uses CVS when
working with Teddy.
When you use CVS, everyone has his or her own working copy
of all files. Additionally there is a single repository,
which maintains official version of files. The repository is maintained
and located in Sourceforge. There are few important basic operations that
Two most important operations are update and commit.
Commit command compares your files to the reposity and sends the
changes you have made to the repository. Update commands gets the
latest versions of files from the reposity to your working copy.
The changes that others have committed are now in your working
You may wonder: If I make some changes and use update, will I
lose my changes? No. Good. Wait. What if someone else has also
changed the file, and committed changes before I have? Still
no problems; when you make commit, CVS may tries to merge your
changes. Sometimes it is not sure how this should be done, and
you may have to manually decide what to do; CVS commit will abort
and ask you to solve the conflict. Just open the file and edit it
so that it will build again. You will notice that CVS has included
both versions of parts that you both have changed.
You will have to manually add each new files to the CVS.
Same applies to remove. Note that CVS interpretes files
as text by default, and expects that it can make some changes to
the file. This means that binary files are effectively corrupted
by CVS unless you explicitly tell CVS that it should leavy this
file exactly as it is given. To do this, add files using -kb
It would be a good convention to always update before commit,
and never do commit until you are sure that it builds without
any errors - at least on your favorite platform.
Problems with configure
Windows and linux file systems are slightly incompatible. Some
times it may happen that files execution permission flags get
lost. You may have to chmod a+rx ./configure in order to be able
to execute ./configure
Additional trouble can be caused by different line endings. You
may have to run fix.sh in the root directory of Teddy to fix line
endings in all text files. Different line endings can cause many
different problems, so try this first if you get really weird and
unexpected error messages.
The configure script may have trouble locating SDL. This usually
means that you have not SDL installed, or you SDL is not in your
path (SDL contains configuration script which gets to path when
you install it), or your SDL is too old. It is also possible
(even likely if you have specific linux distribution and install
newer SDL manually) that you have several versions of SDL in your
system, and they mess up each other. At the moment I require SDL
1.2.2 or newer.
If you are trying to build Teddy on multiuser system where you
are not superuser, there might be SDL installed on the system,
but it might not be in the default path. Ask if SDL is present
and where it would be. You have also option to install your own
version of SDL using prefix option of SDL configure script. You
may get it work even on top of older version of SDL if you set
It may happen that ./configure is totally missing too, or does not
work properly somehow (this is indicated by building problems). In
this case you may have to run aclocal and autoconf
which (re)generate the ./configure script.
Compiling may fail for several reasons. If you get errors about
SDL or other library includes in Win32 MSVC environment, you must
add SDL includes (also libs) to Tools/Options/Directories in Visual
Studio. In linux the ./configure -script usually makes sure SDL
and other libraries will work.
Compiling may also fail if for some reason platform dependent
code is tried to be built on alien platform. This will happen
when someone who has written the code has not been careful.
You will have to isolate the offending code and disable it for
your platform, or write implementation. I mean, you could, if
you wanted to. Usually you should just let me know.
Compiling may also fail just because there is error in the code.
This can happen when someone fixes the code when resolving CVS
Visual studio project and workspace files may be corrupted in
some weird way. This may happen when development takes place in
linux side and things change. You may need to add and or remove
files or even add new projects.
If you use the same directory on multiple machines, from network
filesystem, or simply pack and copy to other machine, or upgrade
you machine, you should remember to clean the old working files.
This problem is severe in linux environment; configure cache may
be incorrect for the new system; Makefile generated by configure may
be outdated, etc. In linux environment source dependencies are
generated by Makefile by scanning source directories for sources.
Thus if new files are added or got from CVS update, you will have
to make clean, maybe rerun configure and make sure Makefile is updated.
In linux environment you may get errors about missing symbols even
though source code is fine and compiles without errors. It turns out
that gcc processes files in the order which they are given on
the command line. When gcc is linking libraries, it only picks those
symbols that have been referenced so far. This is why Maths library
currently is last in the list for gcc. It is possible that when sources
are edited, a new dependency is created, and the order of libraries
in the Makefile.in must be changed.
If you have not set up SDL and other libraries correctly you will
have problems with linking, too.
You will need SDL library. Other libraries, SDL_image and SDL_mixer,
are optional. SDL_image further requires libpng, libz, and libpng.
Teddy happily crashes if it can not find some crucial data files.
Teddy looks for all datafiles in current directory. The normal
./configure && make procedure in linux will copy Teddy executable
to the TeddyRelease directory, which is outside the CVS, but part
of the source archive. You must run Teddy there.
Notice that some release of Teddy / glElite do not all data files in
TeddyRelease directory within the LGPL source archive. Some
copyrighted Elite and or Frontier: First Encounters derived data files
are distributed separately. You can get the datafiles from the internet
You can also use getdata.sh to download and unpack this file.
Contents of data.tgz are required to run Teddy if you want to
see Elite or Frontier: First Encounters ship models.
Currently no such data is being used though.
Are there any coding conventions?
I would very much like that you would use real tabs for
indentation. And never use tabs for anything else.
It does not matter what value for tabs you use.
Linux kernel coding conventions have not yet figured
it out, but it is possible to write sourcecode which
looks perfectly good with variable tab settings. The way
to do it is to:
- use tabs for indentation
- use tabs only for indentation
- don't use tabs to align something that needs spaces to align
For other things (naming, layout..), you have two options.
Use consistently your own conventions; this is fine - or
look at my source code. It is not good example at some places,
but looking around here and there you should get the idea.
One thing is that I hate is prefixing class names with C,
but I can live with that if you really have to do it.
I would like to have one class per .h / .cpp file.
Large classes can be divided into several .cpp files.
Elite is copyrighted, and GNU licences do not allow to include
copyrighted material. Thus Teddy is under LGPL, but glElite is,
urm, well, under no license at all. There may be some lightwave
files in Teddywhich remotely look like Archimedes Elite ships,
but erm, we'll fix that. We should make separate distribution
on glElite and something..
Who is making glElite / Teddy
The core of Teddy is written by Time Suoranta. Some data structures and
ROAM code is written by Sean O'Neil. TinyGL is written by Fabrice Bellard.