Theresa

Version 0.5.1

Description

Theresa is a C++ framework for the underground artform of non-interactive, realtime multimedia applications, commonly called demos. There are input and other interactive modules under development, which will make it a light-weight game engine, but no such functionality exists at this time.

License

This software is licensed under the GNU Lesser Public License. However, if you are interested in licensing the software under a different license, please contact me in one of the ways listed below.

FAQ

What is it?

Theresa is a C++ framework intended for the development of non-interactive multimedia applications, commonly called demos. It is heavily modularized, with the intention that individual components can be added or removed with little effort.

Why is it?

Development of Theresa began to aid our internal demo creation, but as time went on we realized that others might be interested in the software, and also hoped that others might want to aid in the development.

Where is it?

The latest official release of Theresa can be downloaded from SourceForge.net. Additionally, the latest development sources can be checked out from the CVS repository theresa, rooted at cvs.sourceforge.net:/cvsroot/theresa. Also, the CVS repository is available for viewing via SourceForge's ViewCVS interface.

What can I do with it?

Whatever you like. Due to its modularity, Theresa can be put to a multitude of uses. The main intent, however, is for it to serve as a platform for developing demos and other, similar graphical applications.

Library Build Instructions

The only external dependency of Theresa, and a requirement for building the software, is the FMOD audio library, which can be downloaded from fmod.org. Instructions for pointing the various build environments to the location of the installed files are included below.

Darwin / Cygwin / *nix command-line

The autotools configuration path is the default build path of Theresa. If the FMOD library headers were installed into one of the canonical locations (e.g. /usr/include, /usr/local/include, ...), you can simply run the script as-is, e.g.

$ ./configure

However, if it is installed in a non-standard location, you will need to add the location of the library's header files in the list of include directories, e.g.

$ ./configure CPPFLAGS=-Ipath-to-fmod-headers

Additionally, there are a few extra useful switches you can use when running the configuration script.
Currently valid platforms are:

Name
 Description
 Supported Systems
 Status
AGL
 Uses the Carbon and AGL API:s.
 MACOX
 Mature
GLFW
 Uses the GLFW library.
 MACOSX UNIX WIN32
 Functional
GLX
 Uses the POSIX, X11 and GLX API:s.
 UNIX
 Incomplete
SDL
 Uses the SDL library.
 MACOSX UNIX WIN32
 Incomplete
WGL
 Uses the Win32 and WGL API:s.
 WIN32
 Mature

Currently valid systems are:

Name
 Description
UNIX
 Uses the *nix environment.
MACOSX
 Uses the Mac OS X environment.
WIN32
 Uses the Win32 environment.
The choice of platform dictates which set of API:s should be used during runtime, whereas the choice of system affects certain assumptions about the build environment. Different operating systems have different ways of accessing the same API:s, thus the split between the two.

After you have successfully configured the software, you can now build it. This is done by issuing a single make command in the project's root directory, e.g.

$ make

If the build is successful, then the resulting library, named libtheresa.a, can be found in the src/theresa directory. This can be used just like any other library. If you wish to install the library, you can do this with the install make target, e.g.

$ make install

Note that, depending on where you specified that the library be installed (usually /usr/local by default), you may require super-user privliges in order to run this command.

Visual Studio 6.0 and .NET

Since Windows does not come with a Unix-like environment per default, one cannot assume that the developer will be able to run the included Unix-style configuration script. Therefore, hand-written custom configuration headers have been written especially for use with the various Visual Studio environments.

These files, named ThConfig.h, are located with the corresponding solution and workspace files in the build/VS6 and build/VS.NET directories. In order to build Theresa, you will need to copy the corresponding file into the src/shared directory. Once you have done this, you can open the workspace or solution, and build the software normally.

Note that in order to compile the (required) music module, you will need to point the development environment to the location of the FMOD library header files.

The resulting library is named theresa.lib and can be found in the respective target directories under build/VS6/theresa or build/VS.NET/theresa directory, depending on your choice of environment.

Project Builder

In order to build Theresa using Project Builder, you will first need to build the configuration header file. This is done with the GNU configuration script described above. In other words, you will need to have both Terminal.app and the BSD environment installed.
  1. Open Terminal.

  2. Go to the root source directory, e.g,
    % cd ~/theresa/

  3. Run the configuration script. Note that you do not need to specify the search path for FMOD here; that is done from within the Project Builder environment.
    % ./configure

  4. Go into the src/shared subdirectory.
    % cd src/shared/

  5. Build the configuration header file.
    % make
If everything worked, you should have a file called ThConfig.h in the src/shared directory. If you do, you can then open the Project Builder project.

The result of the build process is a framwork called Theresa.framwork, with the identifier org.hypercube.theresa. Note, however, that it is by default not adapted for embedding in an application's bundle.

NOTE: If you do not have the required Unix-tools available, you should be able to write a functional configuration header using the src/shared/config.h.in and the various Visual Studio specific ThConfig.h files as reference. Remember to place the resulting file in the src/shared directory.

Dev-C++

In order to build Theresa using Dev-C++, you will first need to build the configuration header file. This is done by running the GNU configuration script described above. In other words, you will need to have the Cygwin environment installed.
  1. Open the Cygwin shell.

  2. Go to the root source directory, e.g,
    $ cd ~/theresa/

  3. Run the configuration script. Note that you do not need to specify the search path for FMOD here; that is done from within the Dev-C++ environment.
    $ ./configure

  4. Go into the src/shared subdirectory.
    $ cd src/shared/

  5. Build the configuration header file.
    $ make
If everything worked, you should have a file called ThConfig.h in the src/shared directory. If you do, you can then open the Dev-C++ project file, located in build/DevC.

The resulting library is named libtheresa.a, and can be used just like any other library.

NOTE: If you do not have the required tools available, you should be able to write a functional configuration header using the src/shared/config.h.in and the various Visual Studio specific ThConfig.h files as reference. Remember to place the resulting file in the src/shared directory, or it will not be found when building.

Application Creation Instructions

Project Builder

  1. Create a new application project, using the Carbon Application (Nib Based) template.

  2. Remove the CoreServices and ApplicationServices frameworks from the project.

  3. Add the AGL and OpenGL frameworks to the Frameworks section of the project, using the Default reference style.

  4. Add the file src/theresa/AGL/theresa.nib file to the Resources section of the project.

  5. Open the properties page for the project's target.

  6. Add the files libtheresa.a and libfmod.a to the Frameworks section of the project.

  7. Work in progress...

Documentation

Doxygen auto-generated reference manual.

Contact

Developer, Camilla Berglund <elmindreda at users dot sourceforge dot net>.


SourceForge.net Logo


Copyright © 2003 Camilla Berglund