Getting Started

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:

• SDK
• Development
• Documentation

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.

File Structure

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.

Projects

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.

Scripts

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.

Source

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.

• The Core directory contains the core source code for Quesa. Everything within this directory is cross platform.
• The Platform directory contains platform specific code, split into further directories for each platform.
• The Renderers directory contains the source code for Quesa's plug-in renderers. Everything within this directory is cross platform, and capable of being built as a separate shared library which can be loaded at run-time.

Source/Core

At the lowest level, the Core directory contains five directories: Geometry, Glue, Support, System, and Viewer.

• The Geometry directory contains the individual geometry classes. Each class is contained in a separate .c file, with a matching .h file to export the methods available for that class.
• The Glue directory contains the symbols exported by the Quesa library: these are the entry points called by applications, and are responsible for performing parameter checking, system housekeeping, and forwarding the call to the implementation routine.
  Each .c file in this directory contains the entry points for the matching API .h file (e.g., QD3DMath.c corresponds to QD3DMath.h).
• The Support directory contains support code: debug routines, memory management, hash tables, the class tree, etc.
• The System directory contains the bulk of Quesa - the files within this directory are the actual implementation routines invoked by the Glue entry points.
  There is a single .c and .h file for each of the Glue .c files (e.g., E3Math.[ch] corresponds to QD3DMath.c).
• The Viewer directory contains the source for the Viewer library: this is a utility library which sits on top of Quesa, and as such can be self-contained.

Internal Structure

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:

1. The Application calls an API entry point, which is implemented by a function within the Core/Glue area of the source tree. This function performs parameter validation, updates some internal structures, and forwards the call to the matching implementation routine.
2. This implementation routine typically lives within the Core/System area of the source tree, and will ultimately perform the majority of the work involved in handling the request.
3. A more specialised level exists below the System level, which is the geometry objects. These are invoked during the rendering pipeline, and produce efficient (e.g., TriMesh) representations of higher level geometries for a renderer.
4. The lowest level that still remains platform independent is the Core/Support level. This includes fundamental data structures such as the class tree (a tree-like structure which indicates the relationships between the various classes registered with Quesa).
5. Finally, the lowest level is the platform specific level. This is typically concerned with issues such as shared library loading, working with the platform's native windowing API to arrange output, and implementing platform specific storage classes.

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.