The definitive reference for the behaviour of Quesa is currently the source code. However, this page will attempt to provide an overview of the Quesa system, and provide some background for development.
The Quesa distribution is divided into three main folders:
The SDK folder contains example applications and receives the Quesa libraries produced by builds. It also contains additional projects related to Quesa such as the Queeg game framework, and an example file importer plug-in.
The Development folder contains the projects, makefiles, and source code required to build Quesa.
The Documentation folder contains the documentation, which is a local copy of the Quesa web site.
Ignoring the SDK and Documentation directories, the third directory in the Quesa distribution is the Development directory.
This directory contains the projects, makefiles, and all of the source code required to build Quesa. The layout of this directory looks like:
Development/ Projects/ Be/ Mac/ Unix/ Windows/ Scripts/ Source/ Core/ Geometry/ Glue/ Support/ System/ Viewer/ Platform/ Be/ Mac/ Unix/ Windows/ Renderers/ Common/ Generic/ Interactive/ Wireframe/
At the top level, three directories are provided: Projects, Scripts, and Source.
The Projects directory contains the projects and makefiles required to build Quesa, split into directories for each platform.
These projects look for source files and include files within the Development/Source directory, and leave their output in the appropriate SDK/Libraries directory.
The Unix makefile is fairly rudimentary - if you have experience of tools like autoconf (and think using it would be a good idea), please let the mailing list know.
The Scripts directory contains some Perl scripts used in the development of Quesa, e.g., for updating the status table on each release, or regenerating the API reference.
The Source directory is the most important directory - it contains the entire source tree for Quesa.
The Source directory contains all of the source for all of the components of Quesa: this builds into at least three shared libraries, all of which draw files from different portions of the tree.
The Source directory is split into three main categories: Core, Platform, and Renderers.
At the lowest level, the Core directory contains five directories: Geometry, Glue, Support, System, and Viewer.
No detailed documentation or design documents exist for the internals of Quesa.
However, the main flow of control during a rendering loop can be described through a pyramid structure as seen below.
The flow of control proceeds from top to bottom, with the application invoking the Glue level at the top of the pyramid and an image being produced with the help of the Platform layer at the base of the pyramid.
Note that this is slightly inaccurate, in that the final image is actually produced by a renderer object, which sits outside this pyramid - however, the platform level is as good a place as any to consider when looking for the 'base' of Quesa.
In more detail, the steps are:
Classes And Objects
The terms 'class' and 'object' have been referred to above, and as such require further explanation.
In Quesa, virtually every persistent data structure is related in some way to an object (more specifically, a TQ3Object).
As in a language such as C++, objects are instances of entities called classes. An object holds the particular data for an instantiation of a class, while a class holds the data which is common to all objects of that type.
E.g., the triangle class contains methods which are used to initialise and destroy triangle objects. This data is common to all triangle objects (and so stored in the class), while specific instances of triangle objects carry additional data which makes them unique (e.g., their colour).
Quesa maintains a data structure known as the class tree, which acts as a database to record what classes are registered with the system. A tree is used since classes can, as in normal OO programming, inherit from other classes (e.g., the TQ3SharedObject class provides reference counting services to every class derived from it).
Modules within Quesa register their classes with the class tree when Quesa is initialised, and provide functions to manipulate instances of that class as the application creates them.
An Example Class
To get a feel for how this fits together, you may want to study one particular class. A good class to start with is the triangle geometry.
Examine System/Geometry/E3GeometryTriangle.c to see how the class registers itself with the class tree, and the methods it registers with the class tree.
These methods are invoked as triangles are created, disposed of, and manipulated, so placing breakpoints within this file will allow you to observe when and how objects are manipulated by Quesa at runtime.
The triangle object is a good starting point since it demonstrates how a simple object is registered and unregistered within Quesa, how the instance data of an object is manipulated, and how instances of the class are created and destroyed.
Although some details will differ, the code to implement a triangle object is fundamentally identical in structure to the code for all other Quesa objects.