RenderOGL Software Package

This page contains a little primer for getting started with the RenderOGL project. It contains the following sections:

• Subversion Repository: how to get your hand on the code.
• Compiling with TMK: how to compile the project once you have a copy of the code.
• Documentation: how to create and access documentation web pages
• Coding Style: guidelines for coding in RenderOGL, and help for setting up emacs.

Subversion Repository

The RenderOGL project is kept in a Subversion Repository. Subversion is a version control system for letting multiple people work on the same project. Everybody participating can have multiple copies of the Project checked out (e.g. on multiple different machines), and can edit any of them at any given time. Subversion takes care of merging the changes together.

Packages to check out

You need to check out the project from the Subversion Repository to get started. You can get your own copy of the code by using the following command:

> svn co file:///imager/project/ModelingAndRendering/SVNRepository/RenderOGL

Note: SVN path now moved to the following (need to confirm this is the latest one):

> svn co file:///ubc/cs/research/imager/project/psm/SVNRepository/RenderOGL

For this, however, you need to be a member of the UNIX group heidrich. Please talk to me if you aren't.

This will generate a subdirectory containign the code of the project. Please read the man page of Subversion (svn) to learn how to merge your changes back into the repository. NOTE: other people are relying on RenderOGL to do their research. Please do only submit tested code! Make sure you don't break other people's work!

Working from home

If you would like to work from home or on your laptop, you can do that (provided you run Linux or MacOS X) by issuing the following command

> svn co svn+ssh://<username>@cascade.cs.ubc.ca/imager/project/ModelingAndRendering/SVNRepository/RenderOGL

You will also have to install tmk (see next section). I can give you some advice on this, just ask.

Compiling with TMK

To generate executables, we use an elegant Tcl-based make utility called tmk. The philosophy behind tmk is that makefiles should be as simple and platform independent as possible. With tmk, the whole burden of platform-dependent specifications is placed on the maintainer of the tcl installation (me), not on the programmer using it. A tmk Makefile (called TMakefile) is for that reason usually only about 1-5 lines long.

In the simplest mode of operation, tmk only needs to be told in the TMakefile, which subdirectories there are, and which programming language to deal with in the individual directories. In the case of RenderOGL, that is C++. Tmk will automatically traverse the subdirectories, compile all C++ files it finds, and put the resulting files into a shared library, one for each subdirectory. The only files that do NOT get put into these libraries are those which contain a main function. These files are also compiled, but then they are then linked with the previously generated library to form an executable.

In order to allow for binary versions for multiple platforms to be around at the same time, tmk puts everything it generates into subdirectories that are called like the current OS release. For example, on a SuSE Linux Version 9.1, the debug version would be put into a directory called SuSE9.1, while the version with maximum optimization would be put into SuSE9.1_max.

In order to compile the two projects RenderOGL, you have to issue the following command sequence:

> use tmk      # put tmk in your path - you can do this in your .cshrc, but then use the options "-fq"
> cd RenderOGL # change into the project's root directory
> tmk

If you call tmk with the option -max, you will generate a maximum optimized version for the current platform, rather than a debug version.

If you want to learn more about tmk, or need to edit a TMakefile (you typically won't have to in the first while), please have a look at the documentation

More links:

• http://www.mpi-inf.mpg.de/~hitoshi/otherprojects/tmk/tmk-tips.shtml

RenderOGL Documentation

RenderOGL is a code base that expands over time, and includes a lot of individual research pojects. There is a core base of of classes in a handful of subdirectories. These are used in virtually all projects. Then there are project specific subdirectories which are usually of no concern to anybody not working in that project. Major changes in the core classes should always be discussed with me prior to their introduction.

The core directories are:

• GLVectors: a simple, highly optimized class hierarchy for vectors, points, matrices, quaternions. Please do not change anything in here without previously consulting with me.
• GeoObject: a very efficient, OpenGL-centric geometry representation. Can load standard OFF, PLY, and STL files, as well as proprietary GEO files.
• TriMesh: Triangle mesh classes based on the directed edge data structure. Can be generated from a GeoObject.
• Texture: classes for loading images and using them as OpenGL textures.
• Structures: general data structures such as oct-trees.
• UserInterface: some simple user interface components like an arcball.

Please see me to get a briefing of the components that are relevant for your project. The complete documentation of RenderOGL can be found starting at file:/imager/project/ModelingAndRendering/HTML/RenderOGL/index.html. This is a central repository of documentation generated automatically from the source code using the tool doxygen. This documentation is updated every few weeks. If you need completely up-to-date documentation for your version of the code, you can generate it yourself by issuing the following commands in your copy of the RenderOGL project:

> use doxygen
> cd RenderOGL/doc
> tmk

Coding Style

Here are some general guidelines for code devlopment in RenderOGL. Please follow these as closely as you can, since it makes the code much more readable if everybody uses the same style.

• Do not use lines wider than 80 characters (break lines where necessary).
• Use an indentation of 2 characters.
• Functions and member variables start with lower-case letters but use upper case letters at the beginning of new words (e.g. myFunction, or myVariable).
• Classes and types start with upper case letters and use upper case letters at word boundaries (e.g. MyClass, or MyEnum).
• Class files are named like the class in them. Please use "tmk newclass" to generate new classes (this will set up logs correctly)!.
• Executables follow the same naming converntions as functions and variables.
• RenderOGL uses the file endings ".C" for C++ files, and ".hh" for C++ headers (to distinguish them from ANSI C headers).
• Please use doxygen-style comments for documenting header files (see existing code for examples).
• Please use comments starting with "// !!" to indicate hacks and places that need to be changed later on. These will

Generally speaking, use the existing code as guideline for your own coding style...

Editor fun...

If you don't already have a favourite UNIX editor, you should probably use emacs. If configured correctly (see below), this will make your life much easier in the long run! If you are running emacs, but haven't configured it much, you may want to consider copying my .emacs file (~heidrich/.emacs) to your home directory. It contains a number of useful settings that simplify code development. If you have your own, highly customized version of emacs, you should at least consider adding the following piece of code to your .emacs file. It takes care of the correct indentation pattern:

(custom-set-variables
 '(c-offsets-alist (quote ((inline-open . 0) (knr-argdecl-intro . 5)
    (statement-case-open . +) (substatement-open . 0) (label . 0)
    (arglist-intro . c-lineup-arglist-intro-after-paren)
    (arglist-close . c-lineup-arglist)))))

Of course you are also free to use any other editor you like, but then you will have to watch out for the indentation yourself.

-- WolfgangHeidrich - 13 Jul 2006