HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
sceneIndex.h
Go to the documentation of this file.
1 //
2 // Copyright 2021 Pixar
3 //
4 // Licensed under the terms set forth in the LICENSE.txt file available at
5 // https://openusd.org/license.
6 //
7 #ifndef PXR_IMAGING_HD_SCENE_INDEX_H
8 #define PXR_IMAGING_HD_SCENE_INDEX_H
9 
10 #include "pxr/pxr.h"
11 
12 #include <set>
13 #include <unordered_map>
14 
16 #include "pxr/base/tf/singleton.h"
18 
19 
20 #include "pxr/usd/sdf/path.h"
21 
22 #include "pxr/imaging/hd/api.h"
26 
28 
29 
30 ///
31 /// Small struct representing a 'prim' in the Hydra scene index. A prim is
32 /// represented by a container data source which contains a tree of properties.
33 ///
35 {
37  HdContainerDataSourceHandle dataSource;
38 };
39 
40 ///
41 /// \class HdSceneIndexBase
42 ///
43 /// Abstract interface to scene data. This class can be queried for scene
44 /// data directly, and it can also register observers to be notified about
45 /// scene changes (see HdSceneIndexObserver).
46 ///
47 class HdSceneIndexBase : public TfRefBase, public TfWeakBase
48 {
49 public:
50  HD_API
52 
53  HD_API
54  ~HdSceneIndexBase() override;
55 
56  // ------------------------------------------------------------------------
57  // Scene Observer API
58  // ------------------------------------------------------------------------
59 
60  /// Adds an observer to this scene index. The given observer will be sent
61  /// notices for prims added, removed, or dirtied after it is added as an
62  /// observer. It will not be sent notices for prims already in the scene
63  /// index; the calling code is responsible for updating observer state
64  /// if the scene index has already been populated. This function is not
65  /// threadsafe.
66  HD_API
67  void AddObserver(const HdSceneIndexObserverPtr &observer);
68 
69  /// Removes an observer from this scene index; the given observer will no
70  /// longer be forwarded notices. Note that the observer won't get any
71  /// notices as a result of being detached from this scene index. If
72  /// \p observer is not registered on this scene index, this call does
73  /// nothing. This function is not threadsafe.
74  HD_API
75  void RemoveObserver(const HdSceneIndexObserverPtr &observer);
76 
77  // ------------------------------------------------------------------------
78  // Scene Data API
79  // ------------------------------------------------------------------------
80 
81  /// Returns a pair of (prim type, datasource) for the object at
82  /// \p primPath. If no such object exists, the type will be the empty
83  /// token and the datasource will be null. This function is expected to
84  /// be threadsafe.
85  virtual HdSceneIndexPrim GetPrim(const SdfPath &primPath) const = 0;
86 
87  /// Returns the paths of all scene index prims located immediately below
88  /// \p primPath. This function can be used to traverse
89  /// the scene by recursing from \p SdfPath::AbsoluteRootPath(); such a
90  /// traversal is expected to give the same set of prims as the
91  /// flattening of the scene index's \p PrimsAdded and \p PrimsRemoved
92  /// messages. This function is expected to be threadsafe.
93  virtual SdfPathVector GetChildPrimPaths(const SdfPath &primPath) const = 0;
94 
95  /// A convenience function: look up the object at \p primPath, and if
96  /// successful return the datasource at \p locator within that prim. This
97  /// is equivalent to calling \p GetPrim(primPath), and then calling
98  /// \p HdContainerDataSource::Get(prim.dataSource, locator).
99  HdDataSourceBaseHandle GetDataSource(
100  const SdfPath &primPath,
101  const HdDataSourceLocator &locator) const
102  {
104  GetPrim(primPath).dataSource, locator);
105  }
106 
107  // ------------------------------------------------------------------------
108  // System-wide API
109  // ------------------------------------------------------------------------
110 
111  /// Sends a message with optional arguments to this and any upstream input
112  /// scene indices. Scene indices may implement _SystemMessage to provide
113  /// custom handling. See systemMessages.h for common message definitions.
114  HD_API
115  void SystemMessage(
116  const TfToken &messageType,
117  const HdDataSourceBaseHandle &args);
118 
119  // ------------------------------------------------------------------------
120  // User Interface Utilities
121  // ------------------------------------------------------------------------
122 
123  /// Returns a value previously set by SetDisplayName. If no value (or an
124  /// empty string) was last set, this returns a symbol-demangled version of
125  /// the class type itself. This is in service of user interfaces with views
126  /// of scene index chains or graphs.
127  HD_API
128  std::string GetDisplayName() const;
129 
130  /// Allows for scene index instances to be identified in a more contextually
131  /// relevant way. This is in service of user interfaces with views of scene
132  /// index chains or graphs.
133  HD_API
134  void SetDisplayName(const std::string &n);
135 
136  /// Adds a specified tag token to a scene index instance. This is in service
137  /// of user interfaces which want to filter views of a scene index chain
138  /// or graph.
139  HD_API
140  void AddTag(const TfToken &tag);
141 
142  /// Removes a specified tag token to a scene index instance.
143  /// This is in service of user interfaces which want to filter views of a
144  /// scene index chain or graph.
145  HD_API
146  void RemoveTag(const TfToken &tag);
147 
148  /// Returns true if a specified tag token has been added to a scene index
149  /// instance. This is in service of user interfaces which want to filter
150  /// views of a scene index chain or graph.
151  HD_API
152  bool HasTag(const TfToken &tag) const;
153 
154  /// Returns all tag tokens currently added to a scene index instance. This
155  /// is in service of user interfaces which want to filter views of a scene
156  /// index chain or graph.
157  HD_API
158  TfTokenVector GetTags() const;
159 
160 protected:
161 
162  /// Notify attached observers of prims added to the scene. The set of
163  /// scene prims compiled from added/removed notices should match the set
164  /// from a traversal based on \p GetChildPrimPaths. Each prim has a path
165  /// and type. It's possible for \p PrimsAdded to be called for prims that
166  /// already exist; in that case, observers should be sure to update the
167  /// prim type, in case it changed, and resync the prim. This function is
168  /// not threadsafe; some observers expect it to be called from a single
169  /// thread.
170  HD_API
171  void _SendPrimsAdded(
173 
174  /// Notify attached observers of prims removed from the scene. Note that
175  /// this message is considered hierarchical: if \p /Path is removed,
176  /// \p /Path/child is considered removed as well. This function is not
177  /// threadsafe; some observers expect it to be called from a single thread.
178  HD_API
179  void _SendPrimsRemoved(
181 
182  /// Notify attached observers of datasource invalidations from the scene.
183  /// This message is not considered hierarchical on \p primPath; if
184  /// \p /Path is dirtied, \p /Path/child is not necessarily dirtied.
185  /// However, locators are considered hierarchical: if \p primvars is
186  /// dirtied on a prim, \p primvars/color is considered dirtied as well.
187  /// This function is not threadsafe; some observers expect it to be called
188  /// from a single thread.
189  HD_API
190  void _SendPrimsDirtied(
192 
193 
194  /// Notify attached observers of prims (and their descendents) which have
195  /// been renamed or reparented.
196  /// This function is not threadsafe; some observers expect it to be called
197  /// from a single thread.
198  HD_API
199  void _SendPrimsRenamed(
201 
202 
203  /// Returns whether the scene index has any registered observers; this
204  /// information can be used to skip work preparing notices when there are
205  /// no observers.
206  HD_API
207  bool _IsObserved() const;
208 
209  /// Implement in order to react directly to system messages sent from
210  /// downstream.
211  HD_API
212  virtual void _SystemMessage(
213  const TfToken &messageType,
214  const HdDataSourceBaseHandle &args);
215 
216 private:
217  void _RemoveExpiredObservers();
218 
219  // Scoped (RAII) helper to manage tracking recursion depth,
220  // and to remove expired observers after completing delivery.
221  struct _NotifyScope;
222 
223  // Registered observers, in order of registration.
224  using _Observers = std::vector<HdSceneIndexObserverPtr>;
225  _Observers _observers;
226 
227  // Count of in-flight observer notifications
228  int _notifyDepth;
229 
230  // Flag hinting that expired observers may exist.
231  bool _shouldRemoveExpiredObservers;
232 
233  // User-visible label for this scene index
234  std::string _displayName;
235 
236  // Tags used to categorize this scene index
238  _TagSet _tags;
239 };
240 
241 
242 ///
243 /// \class HdSceneIndexNameRegistry
244 ///
245 /// A registry containing named instances of Hydra indexes. Scene Indexes
246 /// are not automatically registered here, and must be manually added
247 /// (generally by the application).
248 ///
250  : public TfSingleton<HdSceneIndexNameRegistry>
251 {
253 
254  HdSceneIndexNameRegistry() = default;
255 
256 public:
257 
258  /// Returns the singleton-instance of this registry.
259  ///
260  HD_API
263  }
264 
265  /// Registers an \p instance of a scene index with a given \p name.
266  ///
267  HD_API
269  const std::string &name, HdSceneIndexBasePtr instance);
270 
271  /// Returns the names of all registered scene indexes.
272  ///
273  HD_API
274  std::vector<std::string> GetRegisteredNames();
275 
276  /// Returns the scene index that was registered with the given \p name.
277  ///
278  HD_API
279  HdSceneIndexBaseRefPtr GetNamedSceneIndex(const std::string &name);
280 
281 private:
282 
283  using _NamedInstanceMap =
284  std::unordered_map<std::string, HdSceneIndexBasePtr>;
285 
286  _NamedInstanceMap _namedInstances;
287 };
288 
290 
291 #endif // PXR_IMAGING_HD_SCENE_INDEX_H
HD_API void SetDisplayName(const std::string &n)
static T & GetInstance()
Definition: singleton.h:120
HD_API void _SendPrimsRemoved(const HdSceneIndexObserver::RemovedPrimEntries &entries)
HD_API void RegisterNamedSceneIndex(const std::string &name, HdSceneIndexBasePtr instance)
HD_API void SystemMessage(const TfToken &messageType, const HdDataSourceBaseHandle &args)
TfToken primType
Definition: sceneIndex.h:36
#define HD_API
Definition: api.h:23
static HD_API HdSceneIndexNameRegistry & GetInstance()
Definition: sceneIndex.h:261
HD_API void _SendPrimsRenamed(const HdSceneIndexObserver::RenamedPrimEntries &entries)
HD_API void _SendPrimsDirtied(const HdSceneIndexObserver::DirtiedPrimEntries &entries)
virtual HD_API void _SystemMessage(const TfToken &messageType, const HdDataSourceBaseHandle &args)
virtual HdDataSourceBaseHandle Get(const TfToken &name)=0
HD_API ~HdSceneIndexBase() override
virtual SdfPathVector GetChildPrimPaths(const SdfPath &primPath) const =0
HD_API std::string GetDisplayName() const
GLdouble n
Definition: glcorearb.h:2008
Definition: token.h:70
HD_API void RemoveObserver(const HdSceneIndexObserverPtr &observer)
std::vector< class SdfPath > SdfPathVector
HdContainerDataSourceHandle dataSource
Definition: sceneIndex.h:37
HD_API void AddObserver(const HdSceneIndexObserverPtr &observer)
HD_API TfTokenVector GetTags() const
HD_API HdSceneIndexBase()
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:440
HdDataSourceBaseHandle GetDataSource(const SdfPath &primPath, const HdDataSourceLocator &locator) const
Definition: sceneIndex.h:99
GLuint const GLchar * name
Definition: glcorearb.h:786
Definition: path.h:273
HD_API void AddTag(const TfToken &tag)
HD_API void _SendPrimsAdded(const HdSceneIndexObserver::AddedPrimEntries &entries)
HD_API void RemoveTag(const TfToken &tag)
virtual HdSceneIndexPrim GetPrim(const SdfPath &primPath) const =0
HD_API HdSceneIndexBaseRefPtr GetNamedSceneIndex(const std::string &name)
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
**If you just want to fire and args
Definition: thread.h:618
HD_API bool _IsObserved() const
HD_API bool HasTag(const TfToken &tag) const
HD_API std::vector< std::string > GetRegisteredNames()