teengine.h

海量地形数据漫游系统,对于OPENGL开发人员具有一定的参考

//##################################################
//# $Id: TeEngine.h 28 2005-08-28 10:37:47Z peciva $

#ifndef TE_ENGINE_H
#define TE_ENGINE_H

/*****************************************************************************\
 *
 * TeEngine.h
 *
 * TeEngine - terrain engine class
 *
 * Authors: Martin Havl龛ek (xhavli15 AT stud.fit.vutbr.cz)
 *          PCJohn (peciva AT fit.vutbr.cz)
 * Contributors: 
 *
 * ----------------------------------------------------------------------------
 *
 * THIS SOFTWARE IS NOT COPYRIGHTED
 *
 * This source code is offered for use in the public domain.
 * You may use, modify or distribute it freely.
 *
 * This source code is distributed in the hope that it will be useful but
 * WITHOUT ANY WARRANTY.  ALL WARRANTIES, EXPRESS OR IMPLIED ARE HEREBY
 * DISCLAIMED.  This includes but is not limited to warranties of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 *
 * If you find the source code useful, authors will kindly welcome
 * if you give them credit and keep their names with their source code.
 *
\*****************************************************************************/

/**
 * TeEngine class header file.
 *
 * \file TeEngine.h
 * \author Martin Havl龛ek (martyn AT seznam.cz)
 * \author PCJohn (peciva AT fit.vutbr.cz)
 */

#include <Inventor/lists/SbList.h>
#include <Inventor/SbTime.h>
#include <Inventor/SbBSPTree.h>

#include "generators/TeGenerator.h"
#include "generators/TeFaultFormation.h"
#include "generators/TeLinearFilter.h"
#include "objects/TeObject.h"
#include "TeHeightMap.h"
#include "TePatch.h"

class SoNode;
class SoSeparator;
class SoPerspectiveCamera;

/**
 * Class that represents 3D engine.
 *
 * Terrain Engine is responsible for several things:
 * \li TePatch object cannot exist without an engine, engine manages the patch
 *     hierarchy and provides high-level patch requests.
 * \li Engine manages scene objects and theirs cameras. According to the
 *     visible area, engine schedules generator tasks and provides pre-
 *     generating of patches that can be visible in the near future.
 * \li Scene graph managing is one of the most important engine features.
 *     Engine has to be able to keep scene graph as small as possible, but
 *     all visible things has to be there.
 * \li Engine provides comfortable way how to control patches generating
 *     by setting attributes of the generators and makes the choice of
 *     used algorithms possible.
 *
 * This engine is suitable for two completely different tasks:
 * \li It can be used only as a "patches database" to obtain landscape of
 *     any size. Using getPatch() and generateHMap() methods all desired
 *     patches can be created.
 * \li But the main feature of the engine is to provide dynamically
 *     growing terrain according to attached cameras needs. This is done
 *     by continuously calling timeTick() method from the application that
 *     uses the engine to create "continuous pseudo-infinite" terrain.
 */
class TeEngine {

public:

  /** Enumeration of all heightmap generation methods. This corresponds with TeGenerator derived classes in order to use them in the engine. */
  enum GenMethod { FAULT_FORMATION = 0 /**< Fault-formation algorithm; corresponds with TeFaultFormation generator. */
  };

  /** Enumeration of all heightmap filtration methods. This corresponds with TeGenerator derived classes in order to use them in the engine. */
  enum FilterMethod {   NONE = 0, /**< No filtering will be applied. */
                      LINEAR = 1  /**< Linear filter; corresponds with TeLinearFilter generator. */
  };

private:

  /** Struct that holds patch generating task status. \todo Consider creating high-level "TePatchGenerator" that will do this work and make this struct obsolete. */
  struct TeETask {
    /** Enumeration of all possible task states. */
    enum TeETaskStatus {    BM0 = 0, /**< Check if build map 0 is ready. */
                           BM0G = 1, /**< Generator works (build map 0). */
                           BM0F = 2, /**< Filter works (build map 0). */
                            BM1 = 3, /**< Check if build map 1 is ready. */
                           BM1G = 4, /**< Generator works (build map 1). */
                           BM1F = 5, /**< Filter works (build map 1). */
                            BM2 = 6, /**< Check if build map 2 is ready. */
                           BM2G = 7, /**< Generator works (build map 2). */
                           BM2F = 8, /**< Filter works (build map 2). */
                            BM3 = 9, /**< Check if build map 3 is ready. */
                          BM3G = 10, /**< Generator works (build map 3). */
                          BM3F = 11, /**< Filter works (build map 3). */
                            HM = 13, /**< Build heightmap from buildmaps. */
                         GRAPH = 14, /**< Generate patch graph. */
                         SEAMS = 15  /**< Generate graphs of all available seams. */
    };
    TePatch *p; /**< Pointer to the patch being generated. */
    SbVec2f patchPos; /**< Position of the center of the patch in world-space. */
    TeETaskStatus status; /**< Current task status. */
    GenMethod gm; /**< Selected generation method. */
    FilterMethod fm; /**<  Selected filtering method. */
  };

  /** Root of whole patch tree. \sa getRootPatch() */
  TePatch *root;
  /** Level of the root of whole patch tree. \sa getRootLevel() */
  int rootLevel;

  /** Default heightmap resolution. SbVec2s(65,65) by default. \sa getHMapResolution(), getBuildMapResolution() */
  SbVec2s hmapResolution;
  /** Default size of the area occupied by the patch. SbVec2f(64.f,64.f) by default. \sa getPatch0Size() */
  SbVec2f patch0Size;

  // instances of all usable generators, corresponds with GenMethod and
  // FilterMethod enums above
  /** Instance of the fault-formation generator. \todo This attribute is temporarily public, should be private and accesible using some get...() method. */
  public:  TeFaultFormation faultFormation;
  private:
  /** Instance of the linear filter generator. */
  TeLinearFilter linearFilter;

  /** Currently used generator. This attribute is used for polymorph calls. */
  TeGenerator *generator;

  // currently selected generators (these will be used for next task)
  /** Currently selected generation method. \sa getCurrGen(), setCurrGen() */
  GenMethod currGen;
  /** Currently selected filtration method. \sa getCurrFilter(), setCurrFilter() */
  FilterMethod currFilter;

  /** Scheduled tasks queue. It holds all the tasks that are currently under construction. Task at the front of the queue gets CPU-time and has the chance to be finished. \sa schedule(), done() */
  SbList<TeETask> taskQueue;

  /** List that holds pointers of attached objects. \sa addObject(), getObject(), removeObject() */
  SbList<TeObject *> objectList;

  /** Currently active object. This is the object, that manages main camera, HUD camera and handles input events. This pointer is used for polymorph calls. */
  TeObject *activeObject;

  /** Whole scene root. Aditional patches are always added as a children of this root. \sa setSceneRoot(), getSceneRoot(), addNode(), removeNode() */
  SoSeparator *sceneRoot;
  /** Camera that will be used to view the scene. It will be managed by the active object. \sa setSceneCamera(), getSceneCamera() */
  SoPerspectiveCamera *sceneCamera;

  /** HUD static geometry root. \sa setHUDRoot(), getHUDRoot() */
  SoSeparator *HUDRoot;
  /** Camera for displaying HUD. It will be managed by the active object. \sa setHUDCamera(), getHUDCamera() */
  SoPerspectiveCamera *HUDCamera;

  /** List of already generated patches. \sa isReady() \todo Is this necessary? Try to use getPatch() with TePatch::DONT_CREATE policy instead. */
  SbBSPTree patchReadyTree;

  /** List of scheduled patches. It is probably faster than searching in the taskQueue. \sa isScheduled() */
  SbBSPTree patchScheduledTree;

  // patch status queries
  SbBool isReady(SbVec2f patchPos);
  SbBool isScheduled(SbVec2f patchPos);

  // patch generation scheduling
  void schedule(SbVec2f patchPos);
  void done();
  void prepareNeighbours(SbVec2f patchPos);

  // additional useful routines
  SbVec2f computePatchPosUnderPoint(SbVec3f pt);
  SbVec2f computeNeighbourPos(SbVec2f patchPos, TePatch::Direction which);
  TePatch::Direction computePosInsidePatch(SbVec2f patchPos, SbVec3f pt);

public:

  // update scene graph to match object needs
  void updateGraph(TeObject *obj);

  TeEngine(SbVec2s hmapResolution = SbVec2s(65,65),
           SbVec2f patch0Size = SbVec2f(64.f,64.f));
  ~TeEngine();

  // data for explorer
  /** Current FPS number. \todo This is temporary solution. Consider doing its job some other way. */
  float fps;
  /** Current number of tasks in the queue. \todo This is temporary solution. Consider doing its job some other way. */
  unsigned int tasksInQueue;
  /** Total number of already generated patches. \todo This is temporary solution. Consider doing its job some other way. */
  unsigned int patchesNum;

  // default sizes
  const SbVec2s& getHMapResolution() const;
  SbVec2s getBuildMapResolution() const;
  const SbVec2f& getPatch0Size() const;

  // generators selecting
  GenMethod getCurrGen();
  void setCurrGen(GenMethod m);
  FilterMethod getCurrFilter();
  void setCurrFilter(FilterMethod m);

  // objects stuff
  void addObject(TeObject *obj);
  TeObject *getObject(int idx);
  void removeObject(TeObject *obj);
  void setActiveObject(TeObject *obj);
  TeObject *getActiveObject();

  // scene
  void setSceneRoot(SoSeparator *sep);
  SoSeparator* getSceneRoot();
  void addNode(SoNode *node);
  void removeNode(SoNode *node);
  void removePatch(TePatch *p);

  // HUD
  void setHUDRoot(SoSeparator *sep);
  SoSeparator* getHUDRoot();

  // cameras stuff
  void setSceneCamera(SoPerspectiveCamera *c);
  SoPerspectiveCamera *getSceneCamera();
  void setHUDCamera(SoPerspectiveCamera *c);
  SoPerspectiveCamera *getHUDCamera();

  TePatch* getPatch(const SbVec2f &pos, const int level = 0, 
                    TePatch::PatchMissedPolicy policy = TePatch::CREATE);

  TePatch* getRootPatch();
  int getRootLevel() const;
  void advanceRootToPos(const SbVec2f &pos);

  // generate heightmap
  TeHeightMap* generateHMap(const SbVec2s &res);

  // Fault-Formation generator calls
  TeHeightMap* generateHMapFF();
  TeHeightMap* generateHMapFF(const SbVec2s &res);
  TeHeightMap* generateHMapFF(const SbVec2s &res,
                              const unsigned int seed, const int num_faults,
                              const float min_delta, const float max_delta);

  // init function
  void initialize();

  // time-tick function (called by timer in application that uses TeEngine)
  void timeTick(const SbTime delta);

  // generator tick function, called when scheduled task is waiting
  // in taskQueue
  // TRUE means "task is done, get result and start new one"
  SbBool genTick();

  /** Internal function. \todo More detailed documentation. */
  void onRootDestroy()  { root = NULL; }
};


#endif /* TE_ENGINE_H */