File Readme1st..htm
Purpose Explaining where to start.
For Readers/users of the DemoGL sourcecode, DemoGL Developers.
Last changed 02-jun-2001
Last changed by Frans Bouma ([FB])


1. Preface.

Welcome to the DemoGL v1.3x sourcecode package!

It's recommended to read this file first before diving into the sourcecode itself. This file will explain where to start and what to read before you should start reading/modifying the sourcecode. All sourcecode documentation is done in HTML 3.2 to make it easier to read for people without wordprocessors and still have some kind of formatting.

1.1. Source doc headers.
The header above tells the readers of several .htm files in this sourcecode package what the file does, what its purpose is and for who the file is ment.


2. Sourcecode Frequently Asked Questions.

Below are several topics formulated as Frequently Asked Questions plus answers.
2.1. Why is the sourcecode released?
The sourcecode of DemoGL v1.3 is released to provide a way to users of the library to modify the library to their own needs, add additional, rarely used features, use it in other programming environments than VC++, port it to other platforms. It is _NOT_ released as a documentation how DemoGL works. If you want to know what a certain function does, consult the documentation that comes with the DemoGL SDK.

2.2. Why is the sourcecode not using a GNU based license?
The main developer of DemoGL, Frans Bouma, thinks Open Source is about freedom in the most literal form. This means users of the sourcecode should not be limited in their freedom of movement/usage by a license that is viral in any form. The only publicly known and accepted license that provides that is the BSD license, the license used for this sourcecode package. The main difference between BSD and for example the LGPL license is that when you change some code in this package and distribute the result in binary form with your application, you don't have to distribute the sourcecode of that modification as well.

2.3. For who is this sourcecode ment?
As stated in the header of this file, the sourcecode package is ment for people who want to use parts of the sourcecode in other packages, people who want to change parts of DemoGL so it better fits their needs and for people who want to know how to write a demosystem and want to peek behind the scenes. It's not ment for people who want to make demos using DemoGL. DemoGL is ment to let people focus on their own effects, their own code. Those people shouldn't have to read the sourcecode to be productive, to use DemoGL. For them the SDK documentation is the thing they should be reading.

2.4. Where to start?
The source is written in C/C++, using Visual Studio v6.0. You should be comfortable with C and/or C++ to at least understand the code. Because of the IDE used for development, several VC++ specific features are included in the sourcecode. (bool instead of BOOL, precompiled headers etc). You should be familiar with these features when you want to compile the sourcecode using another compiler. Because win32 API is used for a lot of things, it will be hard to port the library to another platform, for example MacOS, BeOS or Linux. When you plan to port the sourcecode, be prepared to face a lot of recoding of win32 specific code. The library is not designed to be ported in the first place, so platform specific code is not placed in one file for example.

You should be familiar with the common problems of library programming and interface massacres. Changing code behind the scenes is easy, but it also easily reflects changes in the functionality of common known public methods of the library, the interface. Always be prepared to the phenomenon that your work could cause you to fall into that trap. Thus plan first, investigate where to place new code and what code to change before doing so. Always use some sort of sourcecode control, so you can fall back to older versions of your library when changes don't work as expected. This way you avoid the situation that your library will end up in a mess that doesn't work.

With this sourcecode package comes a file called srcdescr.htm. This file contains all information about how the sourcecode works, why it is designed the way it is designed, what all these 'm_i' characters mean etc. It's however a good start to learn what the API calls do by studying the user documentation. This way you know what functionality is provided through which call and when you want to trace certain functionality down inside the library you know where to start.


3. What to do when...

Several situations related to DemoGL and the sourcecode are described and what you should do in that particular situation.
3.1. You've read srcdescr.htm. What to do next?
When you just want to read parts of the sourcecode, for example because you are interested how some things are done, you can start right away.

When you plan to add code to the sourcecode package, for example a new feature, be sure you understand the way the source is set up and coded. Every programmer programs differently, constructs code differently and finds some solutions better than others while other programmers think the opposite. That's fine, as long as you're working alone on the sourcecode. When you plan to open up your modifications to other DemoGL developers around the world, be sure you follow the rules set in srcdescr.htm. Also be sure that what you add is not already in the library or just not fitting in the design philosophy of DemoGL.

The same goes for modifying code in the library. The sourcecode is build in 2 years time, and in the latest release, v1.3, a lot of the original code is re-written. Still some legacy code is in there and should be rewritten/modified or removed. When you do that, be sure your changes don't affect other parts of the library or cause basic functionality to fail.

3.2. You want to contribute code to the DemoGL library.
DemoGL had its own spot at sourceforge: http://www.sourceforge.net/projects/demogl, but because Sourceforge uses the very unfriendly CVS tool to do sourcecontrol, the sourceforge project is not continued. If you want to contribute to the DemoGL sourcecode, mail to the development team: devteam@demogl.com.

When you submitted a new feature in the form of a codesnippet, don't expect to get it included into the sourcetree immediately. What you submit will be reviewed by the project maintainers and eventually recoded if the quality of the code doesn't fit the requirements. So in the worst case it can eventually be rejected completely.

The central source: http://www.demogl.com, also contains the latest sourcecode and news.

3.4. You want to port the sourcecode to another compiler on win32.
There are a few things that are very annoying in C/C++ sourcecode. Among them: a long list of compiler specific #ifdef's. Try to avoid these as much as possible. If you can't avoid compiler specific #defines, insert them with great care. Most of the time you can avoid compiler specific #defines at all by using IDE settings, project settings or even makefiles designed per compiler.

3.5. You want to port the sourcecode to another platform.
A port to another platform will result in a fork of the sourcetree. This way it's the most efficient way to deal with platform specific problems. And in the end, that's what DemoGL does: dealing with the platform specific stuff, while the user of the library just deals with OpenGL related stuff.

A fork will also keep the sourcecode clean from platform specific designs not applicable for the platform the user is on it now (f.e.: Linux specific code in the sourcetree used by a win32 developer).

3.6. You are offended by the BSD license and want to apply another license to the code.
No can do. Only owners of the copyright of the sourcecode can add licenses to that code. You can only add another license to the code you wrote yourself, not the code that is supplied in this package.


4. A few hints.

Read, understand, plan, act. Don't mess these up, follow them in this order. That way you will be successful in adopting the sourcecode in your own larger projects or adding new functionality to the library. It's wise to add functionality based on the design of the library and not based on sourcecode. This way the sourcecode will always reflect the intentional design and not become a pile of code that once was reflecting that design.

Document your changes for developers AND for users. Because the library has user documentation, any changes to the functionality of that library requires changes in the user documentation. Document those changes, so library maintainers can add these changes into the general documentation if you submit these changes to these library maintainers. If you plan to do a distribution of DemoGL yourself with the modifications you made in it, that's fine, but document your changes. Also document the code changes you've made. The code is designed in a certain way and your changes should adapt that design and build upon that design, not conflict with that design.