HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
resolveTarget.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_USD_USD_RESOLVE_TARGET_H
8 #define PXR_USD_USD_RESOLVE_TARGET_H
9 
10 #include "pxr/pxr.h"
11 #include "pxr/usd/usd/api.h"
12 #include "pxr/usd/pcp/node.h"
13 #include "pxr/usd/pcp/primIndex.h"
15 
16 #include <memory>
17 
19 
21 
22 /// \class UsdResolveTarget
23 ///
24 /// Defines a subrange of nodes and layers within a prim's prim index to
25 /// consider when performing value resolution for the prim's attributes.
26 /// A resolve target can then be passed to UsdAttributeQuery during its
27 /// construction to have all of the queries made by the UsdAttributeQuery use
28 /// the resolve target's subrange for their value resolution.
29 ///
30 /// Resolve targets can be created via methods on UsdPrimCompositionQueryArc to
31 /// to limit value resolution to a subrange of the prim's composed specs that
32 /// are \ref UsdPrimCompositionQueryArc::MakeResolveTargetUpTo "no stronger that arc",
33 /// or a subrange of specs that is
34 /// \ref UsdPrimCompositionQueryArc::MakeResolveTargetStrongerThan "strictly stronger than that arc"
35 /// (optionally providing a particular layer within the arc's layer stack to
36 /// further limit the range of specs).
37 ///
38 /// Alternatively, resolve targets can also be created via methods on UsdPrim
39 /// that can limit value resolution to either
40 /// \ref UsdPrim::MakeResolveTargetUpToEditTarget "up to" or
41 /// \ref UsdPrim::MakeResolveTargetStrongerThanEditTarget "stronger than"
42 /// the spec that would be edited when setting a value for the prim using the
43 /// given UsdEditTarget.
44 ///
45 /// Unlike UsdEditTarget, a UsdResolveTarget is only relevant to the prim it
46 /// is created for and can only be used in a UsdAttributeQuery for attributes
47 /// on this prim.
48 ///
49 /// \section UsdResolveTarget_Invalidation Invalidation
50 /// This object does not listen for change notification. If a consumer is
51 /// holding on to a UsdResolveTarget, it is their responsibility to dispose
52 /// of it in response to a resync change to the associated prim.
53 /// Failing to do so may result in incorrect values or crashes due to
54 /// dereferencing invalid objects.
55 ///
57 
58 public:
59  UsdResolveTarget() = default;
60 
61  /// Get the prim index of the resolve target.
62  const PcpPrimIndex *GetPrimIndex() const {
63  return _expandedPrimIndex.get();
64  }
65 
66  /// Returns the node that value resolution with this resolve target will
67  /// start at.
68  USD_API
69  PcpNodeRef GetStartNode() const;
70 
71  /// Returns the layer in the layer stack of the start node that value
72  /// resolution with this resolve target will start at.
73  USD_API
74  SdfLayerHandle GetStartLayer() const;
75 
76  /// Returns the node that value resolution with this resolve target will
77  /// stop at when the "stop at" layer is reached.
78  USD_API
79  PcpNodeRef GetStopNode() const;
80 
81  /// Returns the layer in the layer stack of the stop node that value
82  /// resolution with this resolve target will stop at.
83  USD_API
84  SdfLayerHandle GetStopLayer() const;
85 
86  /// Returns true if this is a null resolve target.
87  bool IsNull() const {
88  return !bool(_expandedPrimIndex);
89  }
90 
91 private:
92  // Non-null UsdResolveTargets can only be created by functions in UsdPrim
93  // and UsdPrimCompositionQueryArc.
94  friend class UsdPrim;
96 
97  // Usd_Resolver wants to access the iterators provided by this target.
98  friend class Usd_Resolver;
99 
100  USD_API
102  const std::shared_ptr<PcpPrimIndex> &index,
103  const PcpNodeRef &node,
104  const SdfLayerHandle &layer);
105 
106  USD_API
108  const std::shared_ptr<PcpPrimIndex> &index,
109  const PcpNodeRef &node,
110  const SdfLayerHandle &layer,
111  const PcpNodeRef &stopNode,
112  const SdfLayerHandle &stopLayer);
113 
114  // Resolve targets are created with an expanded prim index either from
115  // a composition query (which owns and holds it) or from a UsdPrim (which
116  // creates it solely to create the resolve target). The expanded prim index
117  // is not otherwise cached, so we have to hold on to it during the lifetime
118  // of the resolve target.
119  std::shared_ptr<PcpPrimIndex> _expandedPrimIndex;
120  PcpNodeRange _nodeRange;
121 
122  PcpNodeIterator _startNodeIt;
123  SdfLayerRefPtrVector::const_iterator _startLayerIt;
124  PcpNodeIterator _stopNodeIt;
125  SdfLayerRefPtrVector::const_iterator _stopLayerIt;
126 };
127 
129 
130 #endif // PXR_USD_USD_RESOLVE_TARGET_H
Definition: layer.h:81
#define USD_API
Definition: api.h:23
USD_API SdfLayerHandle GetStartLayer() const
USD_API PcpNodeRef GetStartNode() const
USD_API SdfLayerHandle GetStopLayer() const
USD_API PcpNodeRef GetStopNode() const
OutGridT const XformOp bool bool
GLenum GLuint GLint GLint layer
Definition: glcorearb.h:1299
Definition: prim.h:116
bool IsNull() const
Returns true if this is a null resolve target.
Definition: resolveTarget.h:87
const PcpPrimIndex * GetPrimIndex() const
Get the prim index of the resolve target.
Definition: resolveTarget.h:62
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
GLuint index
Definition: glcorearb.h:786
UsdResolveTarget()=default
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
PXR_NAMESPACE_OPEN_SCOPE SDF_DECLARE_HANDLES(SdfLayer)