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