include/gdb/surfMgr.h

Go to the documentation of this file.

/*********************************************************************
** Copyright (c) 1999 MAK Technologies, Inc.
** All rights reserved.
*********************************************************************/
/*********************************************************************
** $RCSfile: surfMgr.h,v $ $Revision: 1.13 $ $State: Exp $
*********************************************************************/

// \file surfMgr.h
// \brief Contains the DtSurfaceManager class declaration.

#ifndef surfMgr_H_
#define surfMgr_H_

#include "gdb/gdbDefines.h"
#include "geometry/surface.h"
#include <map>


#define DEFAULT_SURF_MGR_EXPANSION_AMOUNT 10000


// Make an explicit type for the surface IDs so that we can be sure 
// we're working with the appropriate identifiers
typedef unsigned int DtSurfaceID;

//
// DtSurfaceManager manages the surfaces of the 
// loaded terrain file for the terrain database.
class DT_DLL_gdb DtSurfaceManager
{
public:

   // This map keeps count of how many terrain elements have a certain soil type
   typedef unsigned int NumElementsWithSurface;
   typedef std::map<DtSurface::DtCharacteristics, NumElementsWithSurface> DtSurfaceToTerrainElementCountMap;


   // default constructor
   DtSurfaceManager();

   // additional constructor with number of 
   // surfaces to expect to manage
   DtSurfaceManager(unsigned int numSurfaces);

   // destructor
   virtual ~DtSurfaceManager();

   // copy constructor
   DtSurfaceManager(const DtSurfaceManager& orig);

   // assignment operator
   DtSurfaceManager& operator=(const DtSurfaceManager& orig);

   // accessor function
   // If the surface manager is managing a surface with the specified ID,
   // then this function sets surf to a COPY of the managed surface and returns true. 
   // If the given surfaceID is not a surface being managed, then the function
   // returns false
   virtual bool surface(DtSurfaceID surfID, DtSurface& surf) const;

   // Provided for performance reasons.  
   // ASSUMES that the ID provided is valid.
   virtual DtSurface& surface(DtSurfaceID surfID) const;

   // Adds a surface to be managed.  
   // If allowDuplicates is true, then the surface manager will add the 
   // surface even if it be considered a duplicate of an existing 
   // managed surface.  surfID will be set to a new associated surface ID.  
   // If allowDuplicate is false, surfID will be set to the ID of the first 
   // surface it finds that passes the equality criteria.  If it doesn't find
   // an equal surface, it adds it as a new surface and sets surfID to the 
   // associated ID.
   // If for some reason, it cannot add the surface at all, it returns false and
   // leaves surfID untouched.
   virtual bool addSurface(const DtSurface& surfaceToAdd,
                           DtSurfaceID& surfID,
                           bool allowDuplicates = false);

   // Analyzes the managed surfaces and removes multiple instances of 
   // the same surface where the same is defined by the fitness function.
   // All duplicate surfaces will be collapsed and mapped to one surface ID.
   // If the manager cannot remove the duplicates for any reason, it returns 
   // false.
   // Otherwise, it removes the duplicates and sets oldIDToNewIDMapping[OldID]
   // to be a the new surface ID that is associated with the original ID's surface.
   // This function guarantees that all original IDs will be valid indices into
   // the oldIDToNewIDMapping.  The user is responsible for deleting the memory
   // allocated by this function for oldIDToNewIDMapping. (use delete[]).
   virtual bool removeDuplicates(int& numDuplicates,
                                 int& numEntries, 
                                 DtSurfaceID*& oldIDToNewIDMapping);

   // Returns the number of surfaces currently managed 
   virtual unsigned int numberOfSurfaces() const;

   // Determines if a given surface ID is valid.  Returns true if the
   // ID maps to a managed surface and false if it doesn't.
   virtual  bool  isValidID(DtSurfaceID surfID) const;

   // debugging aid
   // prints out the current state of the Surface Manager
   virtual  void dump() const;

   // If numSurfaces is greater than the current number of surfaces managed,
   // the the vertex manager increases its storage to be able to handle the
   // specified number of surfaces.  This is useful when a large number of 
   // surfaces will be given to the manager as it will reduce the number
   // of memory operations the manager needs to use to grow to accomodate
   // the new surfaces as well as reduces the likelyhood that the system will
   // run out of memory.
   // Returns true if the operation was a success or if the number specified
   // is smaller than the amount already capable of being managed.
   // If the manager cannot be expanded due to lack of memory,
   // it throws a std::bad_alloc exception.    
   // \throws std::bad_alloc
   virtual bool expandToManage(unsigned int numSurfaces);

   // updates the surface type given in the key by the amount given in numElements
   virtual void updateSurfaceTerrainElementMap(DtSurfaceID key, unsigned int numElements);

   // Gets the number of elements that are referencing the specified surface.
   virtual bool numTerrainElements(DtSurfaceID surfID, unsigned int& numTerrainElements);

   virtual DtSurfaceToTerrainElementCountMap& surfaceToTerrainElementCountMap();

   // Returns the size (in bytes) of this object
   virtual int sizeInBytes() const;

protected:
   // tests the invariants of the class.  
   // Should be called first in every const public member 
   // function and both first and last in every other function
   bool testInvariant() const;

   // Adds the surface and sets surfID to be the 
   // associated surfID.  If it fails to add the surface - most likely
   // a memory issue - it returns false.
   bool addNewSurface(const DtSurface& surfaceToAdd, DtSurfaceID& surfID);

   // Looks for a duplicate surface of the specified surface 
   // in the managed surfaces.  If it finds one, it returns true 
   // and sets managedSurfID to the associated surfID.  If not, 
   // it returns false and leaves managedSurfID untouched.
   // Does NOT sort - performance for large numbers of surfaces may be
   // very slow.  (O(n^2))
   bool isDuplicate(const DtSurface& surface, DtSurfaceID& managedSurfID) const;
   bool isDuplicate(const DtSurfaceID& comparisonSurfID, 
                    DtSurfaceID& managedSurfID) const;

   // Expands the surface manager's array of surfaces by the amount 
   // specified.  If no amount is specified, then expands by the default 
   // amount.  Maintains the order of the surfaces managed.
   // \throws std::bad_alloc if there is not enough memory to expand the array
   virtual  bool  expandSurfaceArray(unsigned int numToExpandBy = DEFAULT_SURF_MGR_EXPANSION_AMOUNT);

   unsigned int   myNumberOfSurfaces;
   unsigned int   myMaxNumberOfSurfaces;

   // Dynamically allocated array of surfaces. 
   DtSurface*  mySurfaceArray; 

   // For keeping record of how many things are referencing the surfaces.  
   DtSurfaceToTerrainElementCountMap mySurfaceToNumElementsMap;
};

#endif