HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
primCompositionQuery.h
Go to the documentation of this file.
1 //
2 // Copyright 2019 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_USD_USD_PRIM_COMPOSITION_QUERY_H
25 #define PXR_USD_USD_PRIM_COMPOSITION_QUERY_H
26 
27 /// \file usd/primCompositionQuery.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/usd/api.h"
31 #include "pxr/usd/usd/prim.h"
32 
33 #include "pxr/usd/pcp/node.h"
34 #include "pxr/usd/pcp/primIndex.h"
35 
36 #include <memory>
37 
39 
40 /// \class UsdPrimCompositionQueryArc
41 ///
42 /// This represents a composition arc that is returned by a
43 /// UsdPrimCompositionQuery. It contains the node in the composition graph that
44 /// is the target of this arc as well as access to information about how the
45 /// arc was introduced to the composition graph.
46 ///
47 /// \section UsdQueryRootArc Root Arc
48 /// If this arc's \ref GetArcType "arc type" is \ref PcpArcType "PcpArcTypeRoot",
49 /// then this arc represents the root node of the graph. The composition graph's
50 /// root arc is not an authored arc; it exists to target the root node of the
51 /// graph which represents any local opinions that may be defined for the prim
52 /// in the root layer stack.
54 {
55 public:
56  ~UsdPrimCompositionQueryArc() = default;
57 
58  /// \name Target and Introducing Nodes
59  /// These functions access either the target or the introducing nodes in
60  /// the composition graph that this arc represents. The returned node from
61  /// GetTargetNode(), along with a layer obtained from the layer stack
62  /// accessible through the node's GetLayerStack() function, can be used to
63  /// create a \ref UsdEditTarget to direct edits to the target of the arc.
64  /// The same can be done with the introducing node but there are additional
65  /// functions below that are more convenient for directly editing the
66  /// included arcs.
67  ///
68  /// It is important to be aware that the nodes returned by GetTargetNode()
69  /// and GetIntroducingNode() are only valid through the collective lifetime
70  /// of the UsdCompositionQuery and all the UsdPrimCompositionQueryArcs the
71  /// query returns. After the query and all the arcs have gone out of scope
72  /// every PcpNodeRef returned by these two functions will become immediately
73  /// invalid and its behavior will be undefined.
74  /// @{
75 
76  /// Returns the targeted node of this composition arc.
77  USD_API
78  PcpNodeRef GetTargetNode() const;
79 
80  /// Returns the node that introduces this arc into composition graph. This
81  /// is the node where the authored composition opinion exists and is not
82  /// necessarily the target node's parent. If this arc is the
83  /// \ref UsdQueryRootArc "root arc" then this function returns the same
84  /// node as GetTargetNode which is the root node of the composition graph.
85  USD_API
87 
88  /// @}
89 
90  /// \name Arc Target Details
91  /// @{
92 
93  /// Returns the root layer of the layer stack that holds the prim spec
94  /// targeted by this composition arc.
95  USD_API
96  SdfLayerHandle GetTargetLayer() const;
97 
98  /// Returns the path of the prim spec that is targeted by this composition
99  /// arc in the target layer stack.
100  USD_API
101  SdfPath GetTargetPrimPath() const;
102 
103  /// Creates and returns a resolve target that, when passed to a
104  /// UsdAttributeQuery for one of this prim's attributes, causes value
105  /// resolution to only consider node sites weaker than this arc, up to and
106  /// and including this arc's site itself.
107  ///
108  /// If \p subLayer is provided, it must be a layer in this arc's layer stack
109  /// and it will further limit value resolution to only the weaker layers up
110  /// to and including \p subLayer within this layer stack. (This is only with
111  /// respect to this arc; all layers will still be considered in the arcs
112  /// weaker than this arc).
113  USD_API
115  const SdfLayerHandle &subLayer = nullptr) const;
116 
117  /// Creates and returns a resolve target that, when passed to a
118  /// UsdAttributeQuery for one of this prim's attributes, causes value
119  /// resolution to only consider node sites stronger than this arc, not
120  /// including this arc itself (unless \p subLayer is provided).
121  ///
122  /// If \p subLayer is provided, it must be a layer in this arc's layer stack
123  /// and it will cause value resolution to additionally consider layers in
124  /// this arc but only if they are stronger than subLayer within this arc's
125  /// layer stack.
126  USD_API
128  const SdfLayerHandle &subLayer = nullptr) const;
129 
130  /// @}
131 
132  /// \name Arc Editing
133  /// This set of functions returns information about where the specific
134  /// opinions are authored that cause this arc to be included in the
135  /// composition graph. They can be used to edit the composition arcs
136  /// themselves.
137  /// @{
138 
139  /// Returns the specific layer in the layer stack that adds this arc to the
140  /// composition graph. This layer combined with the path returned from
141  /// GetIntroducingPrimPath can be used to find the prim spec which owns
142  /// the field that ultimately causes this arc to exist. If this arc is
143  /// the \ref UsdQueryRootArc "root arc" of the composition graph, it is not
144  /// an authored composition arc and this returns a null layer handle.
145  USD_API
146  SdfLayerHandle GetIntroducingLayer() const;
147 
148  /// Returns the path of the prim that introduces this arc to the composition
149  /// graph within the layer in which the composition opinion is authored.
150  /// This path combined with the layer returned from GetIntroducingLayer
151  /// can be used to find the prim spec which owns the field that ultimately
152  /// causes this arc to exist. If this arc is the
153  /// \ref UsdQueryRootArc "root arc" of the composition graph, it is not an
154  /// authored composition arc and this returns an empty path.
155  USD_API
157 
158  /// Gets the list editor and authored SdfReference value that introduces
159  /// this arc to the composition graph for reference arcs. If this arc's
160  /// type is reference, \p editor will be set to the reference list editor
161  /// of the introducing prim spec and \p ref will be set to the authored
162  /// value of the SdfReference in the reference list.
163  ///
164  /// This returns true if the \ref GetArcType "arc type" is
165  /// \ref PcpArcType "reference" and there are no errors; it returns false
166  /// for all other arc types.
167  USD_API
169  SdfReference *ref) const;
170 
171  /// Gets the list editor and authored SdfPayload value that introduces
172  /// this arc to the composition graph for payload arcs. If this arc's
173  /// type is payload, \p editor will be set to the payload list editor
174  /// of the introducing prim spec and \p payload will be set to the authored
175  /// value of the SdfPayload in the payload list.
176  ///
177  /// This returns true if the \ref GetArcType "arc type" is
178  /// \ref PcpArcType "payload" and there are no errors; it returns false
179  /// for all other arc types.
180  USD_API
182  SdfPayload *payload) const;
183 
184  /// Gets the list editor and authored SdfPath value that introduced
185  /// this arc to the composition graph for class arcs. If this arc's
186  /// type is inherit or specialize, \p editor will be set to the
187  /// corresponding path list editor of the introducing prim spec and \p path
188  /// will be set to the authored value of the SdfPath in the path list.
189  ///
190  /// This returns true if the \ref GetArcType "arc type" is either
191  /// \ref PcpArcType "inherit" or \ref PcpArcType "specialize" and
192  /// there are no errors; it returns false for all other arc types.
193  USD_API
195  SdfPath *path) const;
196 
197  /// Gets the list editor and authored string value that introduces
198  /// this arc to the composition graph for variant arcs. If this arc's
199  /// type is variant, \p editor will be set to the name list editor
200  /// of the introducing prim spec and \p name will be set to the authored
201  /// value of the variant set name in the name list.
202  ///
203  /// This returns true if the \ref GetArcType "arc type" is
204  /// \ref PcpArcType "variant" and there are no errors; it returns false
205  /// for all other arc types.
206  USD_API
208  std::string *name) const;
209 
210  /// @}
211 
212  /// \name Arc classification
213  /// Queries about the arc that are useful for classifying the arc for
214  /// filtering.
215  /// @{
216 
217  /// Returns the arc type.
218  USD_API
219  PcpArcType GetArcType() const;
220 
221  /// Returns whether this arc was implicitly added to this prim meaning it
222  /// exists because of the introduction of another composition arc. These
223  /// will typically exist due to inherits or specializes that are authored
224  /// across a reference.
225  USD_API
226  bool IsImplicit() const;
227 
228  /// Returns whether this arc is ancestral, i.e. it exists because it was
229  /// composed in by a namespace parent's prim index.
230  USD_API
231  bool IsAncestral() const;
232 
233  /// Returns whether the target node of this arc contributes any local spec
234  /// opinions that are composed for the prim.
235  USD_API
236  bool HasSpecs() const;
237 
238  /// Returns whether the composition opinion that introduces this arc
239  /// is authored in the root layer stack. This returns true for any arcs
240  /// where the composition opinion can be authored in the root layer stack.
241  /// This is always true for the root arc.
242  USD_API
243  bool IsIntroducedInRootLayerStack() const;
244 
245  /// Returns whether the composition opinion that introduces this arc is
246  /// authored directly on the prim's prim spec within the root layer stack.
247  /// This is always true for the root arc.
248  USD_API
249  bool IsIntroducedInRootLayerPrimSpec() const;
250 
251  /// @}
252 
253 private:
254  // These will only be created by a UsdPrimCompositionQuery itself.
257 
258  PcpNodeRef _node;
259  PcpNodeRef _originalIntroducedNode;
260  PcpNodeRef _introducingNode;
261 
262  std::shared_ptr<PcpPrimIndex> _primIndex;
263 };
264 
265 /// \class UsdPrimCompositionQuery
266 ///
267 /// Object for making optionally filtered composition queries about a prim.
268 /// It creates a list of strength ordering UsdPrimCompositionQueryArc that
269 /// can be filtered by a combination of criteria and returned.
270 ///
271 /// \section Invalidation
272 /// This object does not listen for change notification. If a consumer is
273 /// holding on to a UsdPrimCompositionQuery, it is their responsibility to
274 /// dispose of it in response to a resync change to the associated prim.
275 /// Failing to do so may result in incorrect values or crashes due to
276 /// dereferencing invalid objects.
278 {
279 public:
280  /// Choices for filtering composition arcs based on arc type
281  enum class ArcTypeFilter
282  {
283  All = 0,
284 
285  // Single arc types
286  Reference,
287  Payload,
288  Inherit,
289  Specialize,
290  Variant,
291 
292  // Related arc types
295 
296  // Inverse of related arc types
299  NotVariant
300  };
301 
302  /// Choices for filtering composition arcs on dependency type. This can
303  /// be direct (arc introduced at the prim's level in namespace) or ancestral
304  /// (arc introduced by a namespace parent of the prim).
306  {
307  All = 0,
308 
309  Direct,
310  Ancestral
311  };
312 
313  /// Choices for filtering composition arcs based on where the arc is
314  /// introduced.
316  {
317  All = 0,
318 
319  // Indicates that we only want arcs that are authored somewhere in the
320  // root layer stack.
322 
323  // Indicates that we only want arcs that are authored directly in the
324  // in the prim's prim spec in the root layer stack.
326  };
327 
328  /// Choices for filtering composition arcs on whether the node contributes
329  /// specs to the prim.
330  enum class HasSpecsFilter
331  {
332  All = 0,
333 
334  HasSpecs,
335  HasNoSpecs
336  };
337 
338  /// Aggregate filter for filtering composition arcs by the previously
339  /// defined criteria.
340  struct Filter
341  {
342  /// Filters by arc type
344 
345  /// Filters by dependency type, direct or ancestral.
347 
348  /// Filters by where the arc is introduced
350 
351  /// Filters by whether the arc provides specs for the prim.
353 
354  Filter() {};
355 
356  bool operator==(const Filter &rhs) {
358  arcTypeFilter == rhs.arcTypeFilter &&
361  };
362 
363  bool operator!=(const Filter &rhs) {
364  return !(*this == rhs);
365  };
366  };
367 
368  /// Returns a prim composition query for the given \p prim with a preset
369  /// filter that only returns reference arcs that are not ancestral.
370  USD_API
372 
373  /// Returns a prim composition query for the given \p prim with a preset
374  /// filter that only returns inherit arcs that are not ancestral.
375  USD_API
377 
378  /// Returns a prim composition query for the given \p prim with a preset
379  /// filter that only returns direct arcs that were introduced by opinions
380  /// defined in a layer in the root layer stack.
381  USD_API
383 
384  /// Create a prim composition query for the \p with the given option
385  /// \p filter.
386  USD_API
387  UsdPrimCompositionQuery(const UsdPrim & prim,
388  const Filter &filter = Filter());
389 
390  ~UsdPrimCompositionQuery() = default;
391 
392  /// Change the filter for this query.
393  USD_API
394  void SetFilter(const Filter &filter);
395 
396  /// Return a copy of the current filter parameters.
397  USD_API
398  Filter GetFilter() const;
399 
400  /// Return a list of composition arcs for this query's prim using the
401  /// current query filter. The composition arcs are always returned in order
402  /// from strongest to weakest regardless of the filter.
403  USD_API
404  std::vector<UsdPrimCompositionQueryArc> GetCompositionArcs();
405 
406 private:
407  UsdPrim _prim;
408  Filter _filter;
409  std::shared_ptr<PcpPrimIndex> _expandedPrimIndex;
410  std::vector<UsdPrimCompositionQueryArc> _unfilteredArcs;
411 };
412 
413 
415 
416 #endif // PXR_USD_USD_PRIM_COMPOSITION_QUERY_H
417 
#define USD_API
Definition: api.h:40
USD_API bool IsImplicit() const
USD_API PcpNodeRef GetTargetNode() const
Returns the targeted node of this composition arc.
ArcIntroducedFilter arcIntroducedFilter
Filters by where the arc is introduced.
~UsdPrimCompositionQueryArc()=default
bool operator==(const Filter &rhs)
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
USD_API SdfLayerHandle GetIntroducingLayer() const
static USD_API UsdPrimCompositionQuery GetDirectRootLayerArcs(const UsdPrim &prim)
ArcTypeFilter arcTypeFilter
Filters by arc type.
USD_API SdfPath GetTargetPrimPath() const
USD_API SdfLayerHandle GetTargetLayer() const
USD_API bool IsIntroducedInRootLayerPrimSpec() const
bool operator!=(const Filter &rhs)
ArcTypeFilter
Choices for filtering composition arcs based on arc type.
USD_API PcpArcType GetArcType() const
Returns the arc type.
USD_API std::vector< UsdPrimCompositionQueryArc > GetCompositionArcs()
GLint ref
Definition: glcorearb.h:124
USD_API PcpNodeRef GetIntroducingNode() const
static USD_API UsdPrimCompositionQuery GetDirectInherits(const UsdPrim &prim)
HasSpecsFilter hasSpecsFilter
Filters by whether the arc provides specs for the prim.
USD_API UsdResolveTarget MakeResolveTargetUpTo(const SdfLayerHandle &subLayer=nullptr) const
USD_API void SetFilter(const Filter &filter)
Change the filter for this query.
USD_API bool GetIntroducingListEditor(SdfReferenceEditorProxy *editor, SdfReference *ref) const
~UsdPrimCompositionQuery()=default
Definition: prim.h:133
GLuint const GLchar * name
Definition: glcorearb.h:786
Definition: path.h:290
static USD_API UsdPrimCompositionQuery GetDirectReferences(const UsdPrim &prim)
USD_API Filter GetFilter() const
Return a copy of the current filter parameters.
USD_API UsdResolveTarget MakeResolveTargetStrongerThan(const SdfLayerHandle &subLayer=nullptr) const
USD_API SdfPath GetIntroducingPrimPath() const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
USD_API bool IsIntroducedInRootLayerStack() const
USD_API bool HasSpecs() const
USD_API bool IsAncestral() const
DependencyTypeFilter dependencyTypeFilter
Filters by dependency type, direct or ancestral.
USD_API UsdPrimCompositionQuery(const UsdPrim &prim, const Filter &filter=Filter())
GLint GLint GLint GLint GLint GLint GLint GLbitfield GLenum filter
Definition: glcorearb.h:1297
PcpArcType
Definition: types.h:44