lescegra.h

Go to the documentation of this file.

/*********************************************************************
* lescegra                                                           *
*                                                                    *
* http://geeky.kicks-ass.org/projects/lescegra.html                  *
*                                                                    *
* Copyright 2003 by Enno Cramer <uebergeek@web.de>                   *
*                                                                    *
* This library is free software; you can redistribute it and/or      *
* modify it under the terms of the GNU Library General Public        *
* License as published by the Free Software Foundation; either       *
* version 2 of the License, or (at your option) any later version.   *
*                                                                    *
* This library is distributed in the hope that it will be useful,    *
* but WITHOUT ANY WARRANTY; without even the implied warranty of     *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU  *
* Library General Public License for more details.                   *
*                                                                    *
* You should have received a copy of the GNU Library General Public  *
* License along with this library; if not, write to the Free         *
* Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. *
*********************************************************************/

#ifndef LESCEGRA_H
#define LESCEGRA_H 1

/**
 * \file  lescegra.h
 * \brief lescegra - an OpenGL scene graph (3d graphics engine)
 */

/**
 * \mainpage lescegra - a 3D graphics engine
 * \version 1.0 (beta)
 * \author  Enno Cramer <uebergeek@web.de>
 * \date    2003
 *
 * \section main_about About
 * Lescegra is an object oriented 3D graphics engine based on the OpenGL API.
 * It is written in strict ANSI C and brings no dependencies beyond an OpenGL
 * implementation.
 *
 * \section main_docs Documentation
 * - \ref usage
 * - \ref extending
 * - \ref style
 */
 
/**
 * \page usage Usage
 * 
 * \section usage_basic Basic
 * Using lescegra in your application involves the following steps:
 * -# initialize the display mode
 * -# set up the scene graph
 * -# run the update-display loop
 *   -# update the scene graph
 *   -# display the scene
 *
 * \note When using callback driven toolkits like GLUT the update-display loop
 * is replaced by a timeout handler repeatedly updating the scene graph and
 * triggering the redisplay of the scene.
 *
 * \section usage_initvideo Initialize the Display Mode
 * Before you can start using lescegra, you have to set up the OpenGL display
 * mode. This mostly means creating a window for your application and enabling
 * some OpenGL features you want to use.
 *
 * Example:
 * \code
 * void init_display(void) {
 *     glutInitDisplayMode(GLUT_DOUBLE | GLUT_RGB | GLUT_DEPTH);
 *     glutCreateWindow("lescegra sample");
 *
 *     glClearColor(0.0, 0.0, 0.0, 0.0);
 *
 *     glEnable(GL_DEPTH_TEST);
 *     glEnable(GL_LIGHTING);
 *     glEnable(GL_TEXTURE_2D);
 *     glEnable(GL_CULL_FACE);
 *
 *     glCullFace(GL_BACK);
 * }
 * \endcode
 *
 * \section usage_setupscene Setting up the Scene
 * The first thing to do, after initializing the display mode, is to create
 * your scene representation. This mostly involves creating a suitable camera
 * and all the objects that will be visible.
 *
 * Example:
 * \code
 * static LsgCamera* camera;
 * static LsgNode* scene;
 *
 * void init_scene(void) {
 *     LsgPerspectiveCam* pcam;
 *     LsgCoords* coords;
 *
 *     pcam = LsgPerspectiveCam_create();
 *     vertex_assign(pcam->location, 3.0, 4.0, 2.0);
 *     vertex_assign(pcam->lookat,   0.0, 0.0, 0.0);
 *     vertex_assign(pcam->up,       0.0, 1.0, 0.0);
 *     pcam->fovy =   45.0;
 *     pcam->aspect =  1.0;
 *     pcam->dmin =    0.1;
 *     pcam->dmax =   10.0;
 *
 *     coords = LsgCoords_create(1.0);
 *
 *     camera = (LsgCamera*)pcam;
 *     scene  = (LsgNode*)coords;
 * }
 * \endcode
 *
 * \section usage_display Display the Scene
 * To display your scene you have to do the following steps:
 * -# clear the screen
 * -# initialize the modelview and projection matrix
 * -# create the correct view frustum
 * -# render the scene with a camera
 * -# flush the OpenGL pipeline
 * -# swap the display buffers
 *
 * \note Steps 2 and 3 can mostly be moved into the program initialization phase
 * as the display process should restore the transformation matrizes and the
 * view frustum.
 *
 * Example:
 * \code
 * void display(void) {
 *     LsgFrustum viewfrustum;
 *  
 *     LsgFrustum_init(&viewfrustum, matrix_identity, matrix_identity);
 *  
 *     glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
 *
 *     glMatrixMode(GL_PROJECTION);
 *     glLoadIdentity();
 *     glMatrixMode(GL_MODELVIEW);
 *     glLoadIdentity();
 *
 *     camera->display(camera, &viewfrustum, scene);
 *
 *     glFlush();
 *     glutSwapBuffers();
 * }
 * \endcode
 *
 * \section usage_animation Animation
 * To get a time based animation, you have to repeatedly update your scene
 * representation:
 * -# update the scene graph (using an increasing time)
 * -# mark all nodes as updated
 * -# trigger redisplay
 *
 * \note You should call the \c clean method \b after calling \c update to allow
 * external changes, for example from keyboard  handler functions, to propagate
 * up the scene graph.
 *
 * Example:
 * \code
 * void animate(int ignore) {
 *     float now;
 *
 *     now = (float)glutGet(GLUT_ELAPSED_TIME) / 1000.0;
 *
 *     scene->update(scene, now);
 *     scene->clean(scene);
 *
 *     glutPostRedisplay();
 * }
 * \endcode
 */

/**
 * \page style Coding Style
 *
 * \section style_indention Sourcecode Indention
 * - Use space for indention (no tabs)
 * - Block indention is 4 spaces
 * - No space after parenthesis
 * - No space after function names
 * - No line break before braces
 *
 * Example:
 * \code
 * void foo(float x, float y) {
 *     if (x > y) {
 *         bar(x);
 *     } else {
 *         bar(y);
 *     }
 * }
 * \endcode
 *
 * \section style_naming Naming Conventions
 * Classes are named Lsg<real class name>. Class names start with a capital
 * letter. If multiple words form a class name, they are combined with every
 * word starting with a capital letter.
 *
 * Class methods are named <Classname>_<method name>. Method names start with a
 * lower-case letter. If multiple words form a method name, all except the first
 * start with a capital letter.
 *
 * Examples:
 * - Classes
 *   - LsgObject
 *   - LsgNode
 *   - LsgHTerrain
 *   - LsgMD2Model
 * - Methods
 *   - LsgObject_destroy
 *   - LsgNode_display
 *   - LsgList_hasNext
 *
 * \section style_classes Classes
 * Classes mostly consist of two files, a header and a source file. Extremely
 * large classes my use more than one source file. The filenames should not
 * contain the \a lsg prefix.
 *
 * The header file defines the class structure and all non-static function
 * prototypes. For any virtual method that is not overriden, a define mapping
 * the method to the parent classes implementation, should be included.
 * 
 */

/**
 * \page extending Extending the Scene Graph
 *
 * \section extending_struct Class Struct
 * A class is defined by a \c typedef to an (if possible) anonymous \c struct.
 * The first struct member must be the parent class and should be named \c
 * super. Following are the classes fields and possibly newly defined virtual
 * methods.
 *
 * Virtual methods are defined as function pointers in the class \c struct.
 *
 * Example:
 * \code
 * typedef struct {
 *     LsgNode super;
 *     void (*foobar)(float x);
 *     int visible;
 * } LsgSample;
 * \endcode
 *
 * \section extending_constructor The Constructor
 * The constructor for a scene graph class is divided into two functions. The
 * first is responsible for allocating memory for a new class instance, the
 * second for initializing the newly allocated memory.
 *
 * This division is necessary to allow the initializer being reused in
 * descendant classes. Also it allows the creation of abstract classes by
 * omitting the memory allocating part of the constructor.
 *
 * \subsection extending_create The Memory Allocator
 * The memory allocator is quite trivial and looks almost the same for every
 * class. It does the following three steps:
 * -# allocate memory for the new instance
 * -# call the initializer passing the new instance and all parameters
 * -# return the new instance
 * 
 * \note This method should return \c NULL if an error is encountered while
 * initializing the instance.
 *
 * Example:
 * \code
 * LsgSample* LsgSample_create(void) {
 *     LsgSample* self = (LsgSample*)malloc(sizeof(LsgSample));
 *
 *     LsgSample_init(self);
 *
 *     return self;
 * }
 * \endcode
 *
 * \subsection extending_init The Initializer
 * The initializer is the part of the constructor that does the actual work. It
 * is responsible for correctly initializing the memory and setting the right
 * virtual method pointers. The initializer method can roughly be divided into
 * three sections:
 * -# call the parent classes initializer
 * -# set any overridden virtual method
 * -# initialize members
 *
 * Example:
 * \code
 * void LsgSample_init(LsgSample* self) {
 *     LsgNode_init(&self->super);
 *
 *     ((LsgObject*)self)->destroy = (void (*)(LsgObject*))LsgSample_destroy;
 *     ((LsgNode*)self)->display   = (void (*)(LsgNode*, LsgFrustum*))LsgSample_display;
 *
 *     self->foobar = LsgSample_foobar;
 *     self->show = 1;
 * }
 * \endcode
 *
 * \section extending_destroy The Destructor
 * The virtual destructor method is called by \c LsgObject_free to free any
 * allocated resources prior to destroying an object instance. The general
 * structure of  the destructor method is:
 * -# free any allocated resources
 * -# call the parent classes destructor
 *
 * Example:
 * \code
 * void LsgSample_destroy(LsgSample* self) {
 *     // free any allocated resources
 *
 *     LsgNode_destroy(&self->super);
 * }
 * \endcode
 *
 * \section extending_display The Display Method
 * The method of the most interest is probably the virtual display method. It
 * is called whenever the scene is rendered to screen (or selection buffer for
 * that matter).
 *
 * The second parameter defines the current view frustum in object coordinates.
 * You can use it to speed up rendering if part of the node are outside the
 * visible area.
 *
 * \warning Be careful to always restore the OpenGL state before returning from
 * this method. Failing to do so may affect the bahavior (or the look) of any
 * node displayed afterwards.
 *
 * \note You should use \c glPushAttrib and \c glPopAttrib to save and restore
 * the OpenGL state rather then \c glGet or \c glIsEnabled. The latter may
 * require the rendering pipeline to be flushed in order to determine the
 * current state, which can have an impact on the display performance.
 *
 * Example:
 * \code
 * void LsgSample_display(LsgSample* self, Frustum* frustum) {
 *     glPushAttrib(GL_ENABLE_BIT);
 *
 *     glDisable(GL_LIGHTING);
 *     glDisable(GL_TEXTURE_2D);
 *
 *     glBegin(GL_LINE_STRIP);
 *     glVertex2f(-1.0, -1.0);
 *     glVertex2f(-1.0,  1.0);
 *     glVertex2f( 1.0,  1.0);
 *     glVertex2f( 1.0, -1.0);
 *     glVertex2f(-1.0, -1.0);
 *     glEnd();
 *
 *     glPopAttrib();
 *
 *     // not strictly necessary; displays a neat bounding box if node.c has
 *     // been compiled with -DDEBUG_BBOX
 *     LsgNode_display(&self->super);
 * }
 * \endcode
 *
 * \section extending_update The Update Method
 * The update method provides the framework for any time based behavior.
 *
 * \note Don't forget to set the dirty flag when changing the objects bounding
 * box.
 *
 * Example:
 * \code
 * void LsgSample_update(LsgSample* self, float now) {
 *     // hide the object after 60 seconds
 *     self->visible = now < 60.0;
 *
 *     LsgNode_update(&self->super);
 * }
 * \endcode
 *
 * \section extending_clean The Clean Method
 * The clean method is responsible for resetting the dirty flag. It does not
 * need to be overridden other than for propagating the method call to sub nodes.
 *
 * Example (LsgGroup):
 * \code
 * void LsgGroup_clean(LsgGroup* self) {
 *    LsgIterator* it;
 *
 *    it = LsgIterator_create(self->children);
 *    while (LsgIterator_hasNext(it)) {
 *        LsgNode* child = (LsgNode*)LsgIterator_next(it);
 *        child->clean(child);
 *    }
 *    LsgObject_free((LsgObject*)it);
 *
 *    LsgNode_clean(&self->super);
 * }
 * \endcode
 */
 
/**
 * \defgroup scene      Scene Representation
 */

/**
 * \ingroup  scene
 * \defgroup geometry   Geometry
 */
 
/**
 * \ingroup  scene
 * \defgroup particle   Particle Systems
 */
 
/**
 * \defgroup util       Utilities
 */

#include <lescegra/util.h>
#include <lescegra/sg.h>
#include <lescegra/particle.h>

#endif

---

(c) 2003, by Enno Cramer
generated on 13 Jul 2003
lescegra - doxygen