HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
dirtyList.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_IMAGING_HD_DIRTY_LIST_H
25 #define PXR_IMAGING_HD_DIRTY_LIST_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/imaging/hd/api.h"
29 #include "pxr/imaging/hd/version.h"
31 #include "pxr/imaging/hd/types.h"
32 
33 #include <memory>
34 
36 
37 class HdRenderIndex;
38 
39 using HdDirtyListSharedPtr = std::shared_ptr<class HdDirtyList>;
40 
41 /// \class HdDirtyList
42 ///
43 /// Used for faster iteration of dirty rprims, filtered by mask.
44 ///
45 /// GetDirtyRprims implicitly refresh and cache the list if needed.
46 /// The returning prims list will be used for sync.
47 ///
48 /// DirtyList construction can expensive. We have 3 layer
49 /// versioning to make it efficient.
50 ///
51 /// 1. Nothing changed since last time (super fast),
52 /// no prims need to be synced.
53 /// DirtyList returns empty vector GetDirtyRprims.
54 /// This can be detected by HdChangeTracker::GetSceneStateVersion.
55 /// It's incremented when any change made on any prim.
56 ///
57 /// 2. Constantly updating Prims in a stable set (fast)
58 /// when munging or playing back, the same set of prims are being updated,
59 /// while the remaining prims (could be huge -- for example a large set)
60 /// are static.
61 /// Those animating prims can be distinguished by the Varying bit. The Varying
62 /// bit is set on a prim when any dirty bit is set, and stays even after clean
63 /// the dirty bit until HdChangeTracker::ResetVaryingState clears out.
64 ///
65 /// DirtyList caches those prims in a list at the first time (described in 3.),
66 /// and returns the list for the subsequent queries. Since that list is
67 /// conservatively picked by the Varying bit instead of the actual DirtyBits
68 /// needed for various reprs, consumer of DirtyList needs to check the
69 /// dirtybits again (this is a common pattern in HdRprim, HdMesh and other).
70 ///
71 /// 3. Varying state changed (medium cost)
72 /// when a exisitng prim newly starts updating (start munging), or when
73 /// a majority of the dirtylist stop updating, we need to reconstruct
74 /// the dirtylist. HdChangeTracker::GetVaryingStateVersion() tells the
75 /// right timing to refresh, by comparing the cached version number in
76 /// the dirtylist.
77 ///
78 /// To construct a dirtylist, the Varying bit is checked instead of other
79 /// dirtybits, since effective dirtybits may differ over prims, by prim
80 /// type (mesh vs curve) or by per-prim repr style (flat vs smooth)
81 ///
82 /// example: [x]=Varying [x*]=Dirty,Varying
83 ///
84 /// say in change tracker:
85 /// A B C D E [F*] [G] [H*] [I*] [J] [K] L M N ...
86 /// then the dirtylist will be:
87 /// F*, G, H*, I*, J, K
88 ///
89 /// Note that G, J and K are not dirty, but it exists in the dirtylist.
90 /// This optimization gives the maximum efficiency when all of Varying
91 /// prims are being updated.
92 ///
93 /// 4. Initial creation, filter changes (most expensive)
94 /// If we fail to early out all the above condition, such as when we add
95 /// new prims or switch the render tag set, all prims should be
96 /// passed down to HdRenderIndex::Sync, except ones we know that are
97 /// completely clean. Although it requires to sweep all prims in the
98 /// render index, this traversal has already been optimized
99 /// using the Gather utility.
100 ///
101 class HdDirtyList {
102 public:
103  HD_API
104  HdDirtyList(HdRprimCollection const& collection,
106  HD_API
107  ~HdDirtyList();
108 
109  /// Returns a reference of dirty ids.
110  /// If the change tracker hasn't changed any state since the last time
111  /// GetDirtyRprims gets called, it simply returns an empty list.
112  /// Otherwise depending on what changed, it will return a list of
113  /// prims to be synced.
114  /// Therefore, it is expected that GetDirtyRprims is called only once
115  /// per render index sync.
116  HD_API
117  SdfPathVector const& GetDirtyRprims();
118 
119  /// Update the tracking state for this HdDirtyList with the new collection,
120  /// if the update cannot be applied, return false.
121  HD_API
122  bool ApplyEdit(HdRprimCollection const& newCollection);
123 
124 private:
125  HdRprimCollection _collection;
126  SdfPathVector _dirtyIds;
127  HdRenderIndex &_renderIndex;
128 
129  unsigned int _sceneStateVersion;
130  unsigned int _rprimIndexVersion;
131  unsigned int _renderTagVersion;
132  unsigned int _varyingStateVersion;
133 };
134 
135 
137 
138 #endif // PXR_IMAGING_HD_DIRTY_LIST_H
HD_API HdDirtyList(HdRprimCollection const &collection, HdRenderIndex &index)
HD_API ~HdDirtyList()
#define HD_API
Definition: api.h:40
HD_API SdfPathVector const & GetDirtyRprims()
std::vector< class SdfPath > SdfPathVector
A vector of SdfPaths.
Definition: path.h:209
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1375
GLuint index
Definition: glcorearb.h:785
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
HD_API bool ApplyEdit(HdRprimCollection const &newCollection)
std::shared_ptr< class HdDirtyList > HdDirtyListSharedPtr
Definition: dirtyList.h:39