include/gdb/specMgr.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2008 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/
/*******************************************************************************
** $RCSfile: specMgr.h,v $ $Revision: 1.17 $ $State: Exp $
*******************************************************************************/
#ifndef specMgr_H_
#define specMgr_H_

//
// \file specMgr.h
// \brief Contains the DtSpecificationManager class declaration and related functionality.
//

#include "gdb/gdbDefines.h"
#include <vlutil/vlConfig.h>
#include <vector>
#include <stdio.h>

//forward declarations
class DtSpecification;

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

//
// DtSpecificationManager manages the specifications of the loaded terrain file 
// for the terrain database.
class DT_DLL_gdb DtSpecificationManager
{
public:

   // default constructor
   DtSpecificationManager();

   // additional constructor with number of 
   // specifications to expect to manage
   DtSpecificationManager(unsigned int numSpecifications);

   // destructor
   virtual ~DtSpecificationManager();

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

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

   // accessor function
   // If the specification manager is managing a specification with the 
   // given ID, then this function sets spec to the managed specification 
   // and returns true. 
   // If the specification is not being managed, then the function
   // returns false
   virtual bool specification(DtSpecificationID specID, 
      DtSpecification& spec) const;

   // Returns a reference to the managed specification..  
   // ASSUMES that the ID provided is valid.
   virtual DtSpecification& specification(DtSpecificationID specID);
   virtual const DtSpecification& specification(DtSpecificationID specID) const;

   // @return The specification ID that will be assigned to the next specification
   // to be added to the manager.  This is useful when planning on associating many
   // objects with a single specification.  The next ID can be gotten, and then used
   // while the specification is still being modified.  
   //
   // @note Users must be @b very careful in using this.  If the ID is to be used, the
   // user must ensure that no specifications are added to the manager before
   // their intended specification is, or the nextID will @b not be the one 
   // previously given.
   virtual DtSpecificationID nextID() const;


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

   // Analyzes the managed specifications and removes multiple instances of 
   // the same specification.  All duplicate specifications will be collapsed 
   // and mapped to one specification 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 specification ID that is associated with the original 
   // ID's specification.  This function guarantees that all original IDs will 
   // be valid indices into the oldIDToNewIDMapping.  The caller is responsible 
   // for deleting the memory allocated by this function for 
   // oldIDToNewIDMapping. (use delete[]).
   virtual bool removeDuplicates(int& numDuplicates,
                                 int& numEntries, 
                                 DtSpecificationID* oldIDToNewIDMapping);

   // \return A boolean indicating whether or not a specification like the specified
   // one already exists in the manager.  If so, the function returns true and 
   // the specID parameter is set to that specification's ID.  Otherwise, false
   // is returned.  
   //
   // @note A specification is "like" another if the spec is a superset of the
   // other specified specification.
   virtual bool aSpecificationLike(const DtSpecification& specification, 
                                   DtSpecificationID& specID) const;

   // Function to merge the contents of another specification manager
   // with this manager.  Creates copies of all the specifications in the manager to merge
   // in this manager.
   // \param specMgrToMerge A reference to a constant specification manager to merge in.
   // \param specificationIDMap A reference to a pointer to a specificationID.  This will
   //                           be allocated by the function and returned to the user who
   //                           will be responsible for deleting the memory when appropriate.
   //                           This array will contain the new specificationIDs mapped by the
   //                           old specification IDs.  i.e. map[oldID] = newID.
   // 
   // \return True if the merging is successful.
   // \return False otherwise
   virtual bool merge(const DtSpecificationManager& specMgrToMerge, 
                      DtSpecificationID*& specificationIDMap);

   // Returns the current number of specifications managed
   virtual unsigned int numberOfSpecifications() const;

   // Determines if a given specification ID is valid.  Returns true if the
   // ID is associated with a managed specification and false if it doesn't.
   virtual bool isValidID(DtSpecificationID specID) const;

   // debugging aid
   virtual void dump() const;

   // dumps the specification manager's content into a text  file so it can be 
   // viewed graphically using GraphViz.
   virtual void dump(FILE* fp) const;

   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 addNewSpecification(const DtSpecification& specificationToAdd, 
                            DtSpecificationID& specID);

   // 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.
   bool isDuplicate(const DtSpecification& specification, 
                    DtSpecificationID& managedSpecID) const;

   // Dynamically allocated array of Specifications. 
   std::vector<DtSpecification>  mySpecifications; 
};

#endif