Add comments for outliner's treestore and treehash (no functional changes)
authorSv. Lockal <lockalsash@gmail.com>
Sun, 18 Aug 2013 20:07:49 +0000 (20:07 +0000)
committerSv. Lockal <lockalsash@gmail.com>
Sun, 18 Aug 2013 20:07:49 +0000 (20:07 +0000)
source/blender/editors/space_outliner/outliner_tree.c
source/blender/makesdna/DNA_space_types.h

index 404821900df88d35ccf516eccf0d0d20574a6d4f..2a6320b83b11b8f827afb25f48959e509c6bbc6f 100644 (file)
@@ -151,7 +151,8 @@ static void outliner_storage_cleanup(SpaceOops *soops)
 }
 
 /* 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 @@ static void check_persistent(SpaceOops *soops, TreeElement *te, ID *id, short ty
        }
        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 @@ static void check_persistent(SpaceOops *soops, TreeElement *te, ID *id, short ty
                }
        }
 
-       /* 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;
index 85655ce09bda07bcf2bb8e3c59003862386b407c..3e1196fb45aea2aa697609acf24a911c3a6b5273 100644 (file)
@@ -246,6 +246,13 @@ typedef struct SpaceOops {
        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 @@ typedef struct SpaceOops {
        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;