HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
generativeProcedural.h
Go to the documentation of this file.
1 //
2 // Copyright 2022 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_GP_GENERATIVE_PROCEDURAL_H
8 #define PXR_IMAGING_HD_GP_GENERATIVE_PROCEDURAL_H
9 
10 #include "pxr/imaging/hdGp/api.h"
13 
15 
16 #define HDGPGENERATIVEPROCEDURAL_TOKENS \
17  ((generativeProcedural, "hydraGenerativeProcedural")) \
18  ((resolvedGenerativeProcedural, "resolvedHydraGenerativeProcedural")) \
19  ((skippedGenerativeProcedural, "skippedHydraGenerativeProcedural")) \
20  ((proceduralType, "hdGp:proceduralType")) \
21  ((anyProceduralType, "*"))
22 
23 TF_DECLARE_PUBLIC_TOKENS(HdGpGenerativeProceduralTokens,
25 
26 /// \class HdGpGenerativeProcedural
27 ///
28 /// HdGpGenerativeProcedural is the base class for procedurals which have
29 /// full access to an input scene in order to create and update a hierarchy
30 /// of child prims within a hydra scene index.
31 ///
32 /// They are registered for use via a corresponding
33 /// HdGpGenerativeProceduralPlugin.
34 ///
36 {
37 public:
38  HDGP_API
39  HdGpGenerativeProcedural(const SdfPath &proceduralPrimPath);
40 
41  HDGP_API
42  virtual ~HdGpGenerativeProcedural();
43 
44  using DependencyMap =
46 
47  using ChildPrimTypeMap =
49 
50  // Given access to the input scene (specifically the primvars serving as
51  // arguments on the procedural's own prim), return what other data sources
52  // of what other prims we depend upon and should be given the opportunity
53  // to update in response their changes.
54  //
55  // For a single instance, UpdateDependencies will not be called from
56  // multiple threads -- nor concurrent to Update
58  const HdSceneIndexBaseRefPtr &inputScene) = 0;
59 
60  // This is the primary "cook" method called when a procedural is initially
61  // resolved or invalidated. The result is a map of child prim paths and
62  // their hydra scene prim types. Because a cook/recook can add, remove or
63  // dirty child prims, the returned ChildPrimTypeMap must always contain
64  // the full set of child prims. It is interpreted in this way:
65  // 1) Prims which did not exist in the result of
66  // of previous calls to this method will be added.
67  // 2) Prims which existed in the results of previous calls but not in this
68  // result will be removed.
69  // 3) Prims whose type has changed between calls to this method will be
70  // re-added.
71  //
72  // Prims which exist in both (and have not changed type) are not considered
73  // dirty unless added to the outputDirtiedPrims vector. Because each entry
74  // in that vector contains an HdDataSourceLocatorSet, invalidation can be
75  // as broad or specific as possible. In order to reduce the amount of
76  // bookkeeping for the procedural itself, previousResult contains the
77  // result of the previous call to this method.
78  //
79  // dirtiedDependencies contains the prim paths and locator sets of
80  // declared dependencies which have been dirtied since the last cook. For
81  // initial cooks (and in response to things like removal of prims previously
82  // dependeded upon), the full set of declared dependencies is sent here. A
83  // procedural may choose to cache values previously queried from the input
84  // scene and invalidate based on the contents of dirtiedDependencies.
85  //
86  // NOTE: For initial cooks, changes to the procedural's own prim will not
87  // be included within dirtiedDependencies. (TODO: reconsider this.)
88  //
89  // ALSO NOTE: Because this method is responsible only for describing the
90  // presence and type (and potential dirtiness) of its child
91  // prims -- and not the data sources for those prims -- it may
92  // choose to defer some computation of values to happen within
93  // data sources returned by GetChildPrim.
94  //
95  // For a single instance, Update will not be called from
96  // multiple threads -- nor concurrent to UpdateDependencies
97  virtual ChildPrimTypeMap Update(
98  const HdSceneIndexBaseRefPtr &inputScene,
99  const ChildPrimTypeMap &previousResult,
100  const DependencyMap &dirtiedDependencies,
101  HdSceneIndexObserver::DirtiedPrimEntries *outputDirtiedPrims) = 0;
102 
103  // Returns the type and prim-level data source for a child prim previously
104  // added or invalidated from the Update method.
105  //
106  // This should expect to be called from multiple threads
108  const HdSceneIndexBaseRefPtr &inputScene,
109  const SdfPath &childPrimPath) = 0;
110 
111  // Returns a locator which can be used in the UpdateDependencies result to
112  // declare a dependency on the set of immediate children for a prim path.
114 
115 
116  // ------------------------------------------------------------------------
117  // Asynchronous API
118  // ------------------------------------------------------------------------
119 
120  // Called to inform a procedural instance whether asychronous evaluation
121  // is possible.
122  //
123  // If asyncEnabled is true, a procedural which makes use of asynchronous
124  // processing should return true to indicate that it wants to receive
125  // AsyncUpdate calls. If asyncEnabled is false, the procedural is expected
126  // to do its work as normal.
127  //
128  // Procedurals which have previously declined async updates (or have
129  // indicated that they are finished via a return value from AsyncUpdate)
130  // are given an opportunity begin asynchronous processing (via receiving
131  // another call to this method) following any call to UpdateDependencies.
132  virtual bool AsyncBegin(bool asyncEnabled);
133 
134 
136  {
137  Continuing = 0, // nothing new, continue checking
138  Finished, // nothing new, stop checking
139  ContinuingWithNewChanges, // new stuff, but continue checking
140  FinishedWithNewChanges, // new stuff, but stop checking
141  };
142 
143  // When asynchronous evaluation is enabled, a procedural will be polled (
144  // at a frequency determined by the host application) to discover any
145  // changes to child prim state.
146  //
147  // This is similar to the standard Update call but differs in these ways:
148  // 1) The input scene is not provided. Any information needed from it for
149  // the sake of asychronous processing should be retrieved during the
150  // standard Update call.
151  // 2) Filling in the provided outputPrimTypes is equivalent to the return
152  // value of the standard Update. If no child prim presence or type
153  // changes (or dirtying) are available, no action is required.
154  // 3) It should not be used to do significant work but rather just to
155  // synchronize the results of work completed by threads or processes
156  // managed by the procedural.
157  //
158  // Changes are only considered following a return value of
159  // ContinuingWithNewChanges or FinishedWithNewChanges. In that case,
160  // outputPrimTypes must be filled in full (similar to the result of standard
161  // Update). As with Update, the previous child prim type map is provided
162  // for convenience.
163  //
164  // Return values of Finished or FinishedWithNewChanges will prevent this
165  // method from being called again until another call to AsyncBegin(true)
166  // returns a true value. This allows a procedural to indicate when it is
167  // finished and then restarted itself in response to declared dependenices
168  // changing. Should a procedural wish to continue receiving the AsyncUpdate
169  // call regardless of whether declared dependencies are dirtied, it should
170  // return Continuing or ContinuingWithNewChanges;
171  virtual AsyncState AsyncUpdate(
172  const ChildPrimTypeMap &previousResult,
173  ChildPrimTypeMap *outputPrimTypes,
174  HdSceneIndexObserver::DirtiedPrimEntries *outputDirtiedPrims);
175 
176 
177 
178 protected:
179  HDGP_API
181 
182 private:
183  const SdfPath _proceduralPrimPath;
184 };
185 
187 
188 #endif
#define HDGP_API
Definition: api.h:23
virtual HDGP_API ~HdGpGenerativeProcedural()
#define HDGPGENERATIVEPROCEDURAL_TOKENS
TF_DECLARE_PUBLIC_TOKENS(HdGpGenerativeProceduralTokens, HDGPGENERATIVEPROCEDURAL_TOKENS)
HDGP_API HdGpGenerativeProcedural(const SdfPath &proceduralPrimPath)
virtual HdSceneIndexPrim GetChildPrim(const HdSceneIndexBaseRefPtr &inputScene, const SdfPath &childPrimPath)=0
virtual ChildPrimTypeMap Update(const HdSceneIndexBaseRefPtr &inputScene, const ChildPrimTypeMap &previousResult, const DependencyMap &dirtiedDependencies, HdSceneIndexObserver::DirtiedPrimEntries *outputDirtiedPrims)=0
Definition: path.h:273
static const HdDataSourceLocator & GetChildNamesDependencyKey()
virtual DependencyMap UpdateDependencies(const HdSceneIndexBaseRefPtr &inputScene)=0
TfDenseHashMap< SdfPath, TfToken, TfHash > ChildPrimTypeMap
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
virtual AsyncState AsyncUpdate(const ChildPrimTypeMap &previousResult, ChildPrimTypeMap *outputPrimTypes, HdSceneIndexObserver::DirtiedPrimEntries *outputDirtiedPrims)
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
virtual bool AsyncBegin(bool asyncEnabled)
HDGP_API const SdfPath & _GetProceduralPrimPath()