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.

• SDL
• SDL_image
  • libjpeg
  • libpng
  • libz
• SDL_mixer

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. 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 sourcecode.

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, go to 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 manually. 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.

Source tree

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 executable.

• 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 Teddy.
• 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 module.
• 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 wont hurt.
• Scenes contains scene and camera related stuff of Teddy.
• SysSupport contains directory scanning routines, precise (hopefully) timer code and type definitions.
• 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.

Threads

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 simulation.

At the moment there is no concurrency management at all. It does not matter now, but critical data structures should be protected later.

Current status

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.
  Update: 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 coordinates.
• 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 you need.

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 copy.

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 options.

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 paths correctly.

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 problems

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.

Linking problems

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.

Running problems

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 address

• http://www.cs.helsinki.fi/u/tksuoran/data.tgz

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.

Copyright issues

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.