added comments

corrected bad reference in void Grid( const Point3i & _c, CellIterator & first, CellIterator & last )

vcg/space/index/spatial_hashing.h

@@ -20,10 +20,19 @@
 * for more details.                                                         *
 *                                                                           *
 ****************************************************************************/
+
+// marco
+// added comments
+// corrected bad reference in void Grid( const Point3i & _c, CellIterator & first, CellIterator & last )
+
+
 /****************************************************************************
 History
 
 $Log: not supported by cvs2svn $
+Revision 1.20  2006/07/26 08:12:56  pietroni
+added InitEmpty Function
+
 Revision 1.19  2006/07/10 12:43:13  turini
 explicit cast in _IsInHtable() to resolve a warning
 
@@ -144,6 +153,12 @@ namespace vcg{
 
 		//type of container of pointer to object in a Cell
 		//typedef typename std::pair<ObjType*,int> EntryType ;
+
+		/* EntryType is the entry data tyep stored into a cell.
+		 * It is composed by:
+		 *   - a ObjType* pointer, pointing to the simplex to spatially index
+		 *   - an integer (temporal mark ??? ) ???
+		 */
 		class  EntryType : public std::pair<ObjType*,int>
 		{
 		public:
@@ -165,7 +180,7 @@ namespace vcg{
 		{
 		protected:
 
-			Point3i cell_n;//cell number
+			Point3i cell_n;		// cell index
 
 		public:
 
@@ -189,7 +204,7 @@ namespace vcg{
 			///find the simplex into the cell
 			bool Find(ObjType* sim,IteMap &I)
 			{
-				for (I=_entries.begin();I<_entries.end();I++)
+				for (I=_entries.begin();I != _entries.end();I++)
 					if ((*I).first==sim)
 						return true;
 				return false;
@@ -216,10 +231,10 @@ namespace vcg{
 
 		}; // end struct Cell
 
-		//hash table definition
-		typedef typename STDEXT::hash_multimap<int,Cell> Htable;
 		//record of the hash table
 		typedef typename std::pair<int,Cell> HRecord;
+		//hash table definition
+		typedef typename STDEXT::hash_multimap<int,Cell> Htable;
 		//iterator to the hash table
 		typedef typename Htable::iterator IteHtable;
 
@@ -252,15 +267,28 @@ namespace vcg{
 			int count = (int) hash_table.count(h);
 			if (count==0)///in this case there is no entry for that key
 				return false;
-			else
+
-			{
 			std::pair<IteHtable, IteHtable> p = hash_table.equal_range(h);
 			IteHtable i = p.first;
 
-				while((i != p.second)&&((*i).second.CellN()!=cell))++i;
+			bool found = false;
-
+			if ( ((*i).second.CellN() == cell) )
-				if (i==p.second)///the scan is terminated and we have not found the right cell
+				found = true;
+			else 
 			{
+				do {
+					i++;
+					if ((*i).second.CellN() == cell)
+					{
+						found = true;
+						break;
+					}
+				} while (i != p.second);
+			}
+
+			if (!found) /// the scan is terminated and 
+			{
+				// we have not found the right cell
 				conflicts++;
 				return false;
 			}
@@ -270,7 +298,6 @@ namespace vcg{
 				return true;
 			}
 		}
-		}
 
 		virtual void _UpdateHMark(ObjType* s){(void)s;}
 
@@ -280,10 +307,16 @@ namespace vcg{
 		{
 			IteHtable I;
 			if (!_IsInHtable(cell,I))
+			{
+				entry_inserted++;
 				_InsertNewHentry(s,cell);
+			}
 			else///there is the entry specified by the iterator I so update only the temporary mark
+			{
+				entry_updated++;
 				(*I).second.Update(s,tempMark);
 			}
+		}
 
 		// hashing
 		const int Hash(Point3i p) const
@@ -294,6 +327,7 @@ namespace vcg{
 
 	public:
 
+		int entry_inserted, entry_updated;
 		/////We need some extra space for numerical precision.
 		//template <class Box3Type>
 		// void SetBBox( const Box3Type & b )
@@ -337,6 +371,9 @@ namespace vcg{
 			assert((grid_size.V(0)>0)&&(grid_size.V(1)>0)&&(grid_size.V(2)>0));
 			siz=grid_size;
 
+			// voxel[i] is the lenght of the edge i of the cell
+			// siz[i] is the number of cells in direction i
+			// dim[i] is the spatial dimension of the grid
 			voxel[0] = dim[0] / siz[0];
 			voxel[1] = dim[1] / siz[1];
 			voxel[2] = dim[2] / siz[2];
@@ -354,7 +391,13 @@ namespace vcg{
 			Point3i &siz = this->siz;
 			CoordType &voxel = this->voxel;
 
+			entry_inserted = 0;
+			entry_updated = 0;
+
 			int _size = std::distance<OBJITER>(_oBegin,_oEnd);
+
+			HashSpace = _size;
+
 			if(!_bbox.IsNull()) this->bbox=_bbox;
 			else
 			{
@@ -396,19 +439,36 @@ namespace vcg{
 			Grid(vcg::Point3i(x,y,z),first,last);
 		}
 
-		///return the simplexes on a specified cell
+		/* return the simplexes on a specified cell
+		 *
+		 * @param _c is the 3D integer index of the cell [IN]
+		 * @param first is the pointer to the first entry stored into the cell _c
+		 * @param second is the pointer to the last entry stored into the cell _c
+		 * @note an entry is a pair composed by the simplex (e.g., a vertex, a face, ...) indexed by the grid and 
+		 *       an integer representing a temporal time stamp
+		 * @note the time stamp is not used here, it is used in the dynamic version of the spatial hashing
+		 */
 		void Grid( const Point3i & _c, CellIterator & first, CellIterator & last )
 		{
 			IteHtable I;
 			if (_IsInHtable(_c,I))//if there is the cell then
-			{	///return pointers to first and last element cell elems
+			{
-				first= &*(*I).second._entries.begin();
+				// (*I) is the pair<int, cell> corresponding to _c
-				last=  &*(*I).second._entries.end();
+				// (*I).second is the cell
+				// (*I).second._entries is the vector of simplices stored into the cell
+				// (*I).second._entries.begin() is the pointer to the first entry
+				// *(*I).second._entries.begin() is the pointer to the pointer to the first entry
+				// &*(*I).second._entries.begin() is the address of the pointer to the pointer to the first entry (hooray)
+
+				// WARNING : (*I).second._entries.end() does not point to an entry, it is just a marker to end 
+				//			 of the vector
+				first = &(*(*I).second._entries.begin());
+				last=  &*((*I).second._entries.end() - 1);
 			}
 			else
 			{	///return 2 equals pointers
-				first=&*(*hash_table.begin()).second._entries.begin();
+				first =&(*(*hash_table.begin()).second._entries.begin());
-				last= &*(*hash_table.begin()).second._entries.begin();
+				last = &(*((*hash_table.begin()).second._entries.begin() ));
 			}
 		}