SkRTree.h revision 8f8c25eabb97da8eda488895f04f2d12cb5ea4cf 
1
2/*
3 * Copyright 2012 Google Inc.
4 *
5 * Use of this source code is governed by a BSD-style license that can be
6 * found in the LICENSE file.
7 */
8
9#ifndef SkRTree_DEFINED
10#define SkRTree_DEFINED
11
12#include "SkRect.h"
13#include "SkTDArray.h"
14#include "SkChunkAlloc.h"
15#include "SkBBoxHierarchy.h"
16
17/**
18 * An R-Tree implementation. In short, it is a balanced n-ary tree containing a hierarchy of
19 * bounding rectangles.
20 *
21 * Much like a B-Tree it maintains balance by enforcing minimum and maximum child counts, and
22 * splitting nodes when they become overfull. Unlike B-trees, however, we're using spatial data; so
23 * there isn't a canonical ordering to use when choosing insertion locations and splitting
24 * distributions. A variety of heuristics have been proposed for these problems; here, we're using
25 * something resembling an R*-tree, which attempts to minimize area and overlap during insertion,
26 * and aims to minimize a combination of margin, overlap, and area when splitting.
27 *
28 * One detail that is thus far unimplemented that may improve tree quality is attempting to remove
29 * and reinsert nodes when they become full, instead of immediately splitting (nodes that may have
30 * been placed well early on may hurt the tree later when more nodes have been added; removing
31 * and reinserting nodes generally helps reduce overlap and make a better tree). Deletion of nodes
32 * is also unimplemented.
33 *
34 * For more details see:
35 *
36 *  Beckmann, N.; Kriegel, H. P.; Schneider, R.; Seeger, B. (1990). "The R*-tree:
37 *      an efficient and robust access method for points and rectangles"
38 *
39 * It also supports bulk-loading from a batch of bounds and values; if you don't require the tree
40 * to be usable in its intermediate states while it is being constructed, this is significantly
41 * quicker than individual insertions and produces more consistent trees.
42 */
43class SkRTree : public SkBBoxHierarchy {
44public:
45    SK_DECLARE_INST_COUNT(SkRTree)
46
47    /**
48     * Create a new R-Tree with specified min/max child counts.
49     * The child counts are valid iff:
50     * - (max + 1) / 2 >= min (splitting an overfull node must be enough to populate 2 nodes)
51     * - min < max
52     * - min > 0
53     * - max < SK_MaxU16
54     * If you have some prior information about the distribution of bounds you're expecting, you
55     * can provide an optional aspect ratio parameter. This allows the bulk-load algorithm to create
56     * better proportioned tiles of rectangles.
57     */
58    static SkRTree* Create(int minChildren, int maxChildren, SkScalar aspectRatio = 1,
59            bool orderWhenBulkLoading = true);
60    virtual ~SkRTree();
61
62    /**
63     * Insert a node, consisting of bounds and a data value into the tree, if we don't immediately
64     * need to use the tree; we may allow the insert to be deferred (this can allow us to bulk-load
65     * a large batch of nodes at once, which tends to be faster and produce a better tree).
66     *  @param opIndex The data value
67     *  @param bounds The corresponding bounding box
68     *  @param defer Can this insert be deferred? (this may be ignored)
69     */
70    virtual void insert(unsigned opIndex, const SkRect& bounds, bool defer = false) SK_OVERRIDE;
71
72    /**
73     * If any inserts have been deferred, this will add them into the tree
74     */
75    virtual void flushDeferredInserts() SK_OVERRIDE;
76
77    /**
78     * Given a query rectangle, populates the passed-in array with the elements it intersects
79     */
80    virtual void search(const SkRect& query, SkTDArray<unsigned>* results) const SK_OVERRIDE;
81
82    void clear();
83    // Return the depth of the tree structure.
84    int getDepth() const { return this->isEmpty() ? 0 : fRoot.fChild.subtree->fLevel + 1; }
85    // Insertion count (not overall node count, which may be greater).
86    int getCount() const { return fCount; }
87
88private:
89    bool isEmpty() const { return 0 == this->getCount(); }
90
91    struct Node;
92
93    /**
94     * A branch of the tree, this may contain a pointer to another interior node, or a data value
95     */
96    struct Branch {
97        union {
98            Node* subtree;
99            unsigned opIndex;
100        } fChild;
101        SkIRect fBounds;
102    };
103
104    /**
105     * A node in the tree, has between fMinChildren and fMaxChildren (the root is a special case)
106     */
107    struct Node {
108        uint16_t fNumChildren;
109        uint16_t fLevel;
110        bool isLeaf() { return 0 == fLevel; }
111        // Since we want to be able to pick min/max child counts at runtime, we assume the creator
112        // has allocated sufficient space directly after us in memory, and index into that space
113        Branch* child(size_t index) {
114            return reinterpret_cast<Branch*>(this + 1) + index;
115        }
116    };
117
118    typedef int32_t SkIRect::*SortSide;
119
120    // Helper for sorting our children arrays by sides of their rects
121    struct RectLessThan {
122        RectLessThan(SkRTree::SortSide side) : fSide(side) { }
123        bool operator()(const SkRTree::Branch lhs, const SkRTree::Branch rhs) const {
124            return lhs.fBounds.*fSide < rhs.fBounds.*fSide;
125        }
126    private:
127        const SkRTree::SortSide fSide;
128    };
129
130    struct RectLessX {
131        bool operator()(const SkRTree::Branch lhs, const SkRTree::Branch rhs) {
132            return ((lhs.fBounds.fRight - lhs.fBounds.fLeft) >> 1) <
133                   ((rhs.fBounds.fRight - lhs.fBounds.fLeft) >> 1);
134        }
135    };
136
137    struct RectLessY {
138        bool operator()(const SkRTree::Branch lhs, const SkRTree::Branch rhs) {
139            return ((lhs.fBounds.fBottom - lhs.fBounds.fTop) >> 1) <
140                   ((rhs.fBounds.fBottom - lhs.fBounds.fTop) >> 1);
141        }
142    };
143
144    SkRTree(int minChildren, int maxChildren, SkScalar aspectRatio, bool orderWhenBulkLoading);
145
146    /**
147     * Recursively descend the tree to find an insertion position for 'branch', updates
148     * bounding boxes on the way up.
149     */
150    Branch* insert(Node* root, Branch* branch, uint16_t level = 0);
151
152    int chooseSubtree(Node* root, Branch* branch);
153    SkIRect computeBounds(Node* n);
154    int distributeChildren(Branch* children);
155    void search(Node* root, const SkIRect query, SkTDArray<unsigned>* results) const;
156
157    /**
158     * This performs a bottom-up bulk load using the STR (sort-tile-recursive) algorithm, this
159     * seems to generally produce better, more consistent trees at significantly lower cost than
160     * repeated insertions.
161     *
162     * This consumes the input array.
163     *
164     * TODO: Experiment with other bulk-load algorithms (in particular the Hilbert pack variant,
165     * which groups rects by position on the Hilbert curve, is probably worth a look). There also
166     * exist top-down bulk load variants (VAMSplit, TopDownGreedy, etc).
167     */
168    Branch bulkLoad(SkTDArray<Branch>* branches, int level = 0);
169
170    void validate() const;
171    int validateSubtree(Node* root, SkIRect bounds, bool isRoot = false) const;
172
173    const int fMinChildren;
174    const int fMaxChildren;
175    const size_t fNodeSize;
176
177    // This is the count of data elements (rather than total nodes in the tree)
178    int fCount;
179
180    Branch fRoot;
181    SkChunkAlloc fNodes;
182    SkTDArray<Branch> fDeferredInserts;
183    SkScalar fAspectRatio;
184    bool fSortWhenBulkLoading;
185
186    Node* allocateNode(uint16_t level);
187
188    typedef SkBBoxHierarchy INHERITED;
189};
190
191#endif
192