[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [59246] trunk/blender/source/blender: Add comments for outliner's treestore and treehash (no functional changes)

[Sv. Lockal]

Revision: 59246
          http://projects.blender.org/scm/viewvc.php?view=rev&root=bf-blender&revision=59246
Author:   lockal
Date:     2013-08-18 20:07:49 +0000 (Sun, 18 Aug 2013)
Log Message:
-----------
Add comments for outliner's treestore and treehash (no functional changes)

Modified Paths:
--------------
    trunk/blender/source/blender/editors/space_outliner/outliner_tree.c
    trunk/blender/source/blender/makesdna/DNA_space_types.h

Modified: trunk/blender/source/blender/editors/space_outliner/outliner_tree.c
===================================================================
--- trunk/blender/source/blender/editors/space_outliner/outliner_tree.c	2013-08-18 19:47:33 UTC (rev 59245)
+++ trunk/blender/source/blender/editors/space_outliner/outliner_tree.c	2013-08-18 20:07:49 UTC (rev 59246)
@@ -151,7 +151,8 @@
 }
 
 /* This function hashes only by type, nr and id, while cmp function also compares 'used' flag;
- * This is done to skip full treehash rebuild in outliner_storage_cleanup */
+ * This is done to skip full treehash rebuild in outliner_storage_cleanup;
+ * In general hashing by type, nr and id should be enough to distribute elements in buckets uniformly */
 static unsigned int tse_hash(const void *ptr)
 {
 	const TreeStoreElem *tse = (const TreeStoreElem *)ptr;
@@ -194,6 +195,8 @@
 	}
 	if (soops->treehash == NULL) {
 		soops->treehash = BLI_ghash_new(tse_hash, tse_cmp, "treehash");
+		
+		/* treehash elements are not required to be unique; see soops->treehash comment */
 		BLI_ghash_flag_set(soops->treehash, GHASH_FLAG_ALLOW_DUPES);
 	}
 	
@@ -205,7 +208,8 @@
 		}
 	}
 
-	/* check for unused tree elements is in treestore */
+	/* find any unused tree element in treestore and mark it as used
+	 * (note that there may be multiple unused elements in case of linked objects) */
 	tselem = lookup_treehash(soops->treehash, type, nr, 0, id);
 	if (tselem) {
 		te->store_elem = tselem;

Modified: trunk/blender/source/blender/makesdna/DNA_space_types.h
===================================================================
--- trunk/blender/source/blender/makesdna/DNA_space_types.h	2013-08-18 19:47:33 UTC (rev 59245)
+++ trunk/blender/source/blender/makesdna/DNA_space_types.h	2013-08-18 20:07:49 UTC (rev 59246)
@@ -246,6 +246,13 @@
 	View2D v2d DNA_DEPRECATED;  /* deprecated, copied to region */
 	
 	ListBase tree;
+	
+	/* treestore is an ordered list of TreeStoreElem's from outliner tree;
+	 * Note that treestore may contain duplicate elements if element
+	 * is used multiple times in outliner tree (e. g. linked objects)
+	 * Also note that BLI_mempool can not be read/written in DNA directly,
+	 * therefore readfile.c/writefile.c linearize treestore into TreeStore structure
+	 */
 	struct BLI_mempool *treestore;
 	
 	/* search stuff */
@@ -253,7 +260,12 @@
 	struct TreeStoreElem search_tse;
 
 	short flag, outlinevis, storeflag, search_flags;
-	struct GHash *treehash;  /* note, allows duplicates */
+	
+	/* search index for every element in treestore;
+	 * It is ok for treehash to contain duplicates, because the semantics of its usage
+	 * allows duplicates (see check_persistent)
+	 */
+	struct GHash *treehash;
 } SpaceOops;