HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
editTarget.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 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_EDIT_TARGET_H
25 #define PXR_USD_USD_EDIT_TARGET_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/usd/usd/api.h"
31 #include "pxr/usd/pcp/node.h"
32 #include "pxr/usd/sdf/layer.h"
33 #include "pxr/usd/sdf/path.h"
34 #include "pxr/usd/sdf/primSpec.h"
35 
37 
38 
40 
41 /// \class UsdEditTarget
42 ///
43 /// Defines a mapping from scene graph paths to Sdf spec paths in a
44 /// SdfLayer where edits should be directed, or up to where to perform partial
45 /// composition.
46 ///
47 /// A UsdEditTarget can represent an arbitrary point in a composition graph for
48 /// the purposes of placing edits and resolving values. This enables editing
49 /// and resolving across references, classes, variants, and payloads.
50 ///
51 /// In the simplest case, an EditTarget represents a single layer in a stage's
52 /// local LayerStack. In this case, the mapping that transforms scene graph
53 /// paths to spec paths in the layer is the identity function. That is, the
54 /// UsdAttribute path '/World/Foo.avar' would map to the SdfPropertySpec path
55 /// '/World/Foo.avar'.
56 ///
57 /// For a more complex example, suppose '/World/Foo' in 'Shot.usda' is a
58 /// reference to '/Model' in 'Model.usda'. One can construct a UsdEditTarget
59 /// that maps scene graph paths from the 'Shot.usda' stage across the reference
60 /// to the appropriate paths in the 'Model.usda' layer. For example, the
61 /// UsdAttribute '/World/Foo.avar' would map to the SdfPropertySpec
62 /// '/Model.avar'. Paths in the stage composed at 'Shot.usda' that weren't
63 /// prefixed by '/World/Foo' would not have a valid mapping to 'Model.usda'.
64 ///
65 /// EditTargets may also work for any other kind of arc or series of arcs.
66 /// This allows for editing across variants, classes, and payloads, or in a
67 /// variant on the far side of a reference, for example.
68 ///
69 /// In addition to mapping scene paths to spec paths for editing, EditTargets
70 /// may also be used to identify points in the composition graph for partial
71 /// composition. Though it doesn't currently exist, a UsdCompose API that takes
72 /// UsdEditTarget arguments may someday be provided.
73 ///
74 /// For convenience and deployment ease, SdfLayerHandles will implicitly convert
75 /// to UsdEditTargets. A UsdEditTarget constructed in this way means direct
76 /// opinions in a layer in a stage's local LayerStack.
77 ///
79 {
80 public:
81 
82  /// Construct a null EditTarget. A null EditTarget will return paths
83  /// unchanged when asked to map paths.
84  USD_API
85  UsdEditTarget();
86 
87  /// Constructor. Allow implicit conversion from SdfLayerHandle.
88  /// EditTargets constructed in this way specify layers in the scene's local
89  /// LayerStack. This lets clients pass layers directly in this common case
90  /// without explicitly having to construct a \a UsdEditTarget instance.
91  /// To automatically supply the appropriate layer offset for the given
92  /// layer, see UsdStage::GetEditTargetForLayer().
93  USD_API
94  UsdEditTarget(const SdfLayerHandle &layer,
96 
97  /// Convenience implicit conversion from SdfLayerRefPtr. See above
98  /// constructor for more information.
99  USD_API
100  UsdEditTarget(const SdfLayerRefPtr &layer,
102 
103  /// Construct an EditTarget with \a layer and \a node. The mapping
104  /// will be used to map paths from the scene into the \a layer's namespace
105  /// given the \a PcpNodeRef \a node's mapping.
106  USD_API
107  UsdEditTarget(const SdfLayerHandle &layer, const PcpNodeRef &node);
108 
109  /// Convenience constructor taking SdfLayerRefPtr. See above
110  /// constructor for more information.
111  USD_API
112  UsdEditTarget(const SdfLayerRefPtr &layer, const PcpNodeRef &node);
113 
114  /// Convenience constructor for editing a direct variant in a local
115  /// LayerStack. The \p varSelPath must be a prim variant selection path
116  /// (see SdfPath::IsPrimVariantSelectionPath()).
117  USD_API
118  static UsdEditTarget
119  ForLocalDirectVariant(const SdfLayerHandle &layer,
120  const SdfPath &varSelPath);
121 
122  /// Equality comparison.
123  USD_API
124  bool operator==(const UsdEditTarget &other) const;
125 
126  /// Inequality comparison.
127  bool operator!=(const UsdEditTarget &other) const {
128  return !(*this == other);
129  }
130 
131  /// Return true if this EditTarget is null. Null EditTargets map
132  /// paths unchanged, and have no layer or LayerStack identifier.
133  bool IsNull() const { return *this == UsdEditTarget(); }
134 
135  /// Return true if this EditTarget is valid, false otherwise. Edit
136  /// targets are considered valid when they have a layer.
137  bool IsValid() const { return _layer; }
138 
139  /// Return the layer this EditTarget contains.
140  const SdfLayerHandle &GetLayer() const & { return _layer; }
141  SdfLayerHandle GetLayer() && { return std::move(_layer); }
142 
143  /// Map the provided \a scenePath into a SdfSpec path for the
144  /// EditTarget's layer, according to the EditTarget's mapping. Null edit
145  /// targets and EditTargets for which \a IsLocalLayer are true return
146  /// scenePath unchanged.
147  USD_API
148  SdfPath MapToSpecPath(const SdfPath &scenePath) const;
149 
150  /// Convenience function for getting the PrimSpec in the edit
151  /// target's layer for \a scenePath. This is equivalent to
152  /// target.GetLayer()->GetPrimAtPath(target.MapToSpecPath(scenePath)) if
153  /// target has a valid layer. If this target IsNull or there is no valid
154  /// mapping from \a scenePath to a SdfPrimSpec path in the layer, return
155  /// null.
156  USD_API
157  SdfPrimSpecHandle
158  GetPrimSpecForScenePath(const SdfPath &scenePath) const;
159 
160  USD_API
161  SdfPropertySpecHandle
162  GetPropertySpecForScenePath(const SdfPath &scenePath) const;
163 
164  USD_API
165  SdfSpecHandle
166  GetSpecForScenePath(const SdfPath &scenePath) const;
167 
168  /// Returns the PcpMapFunction representing the map from source
169  /// specs (including any variant selections) to the stage.
170  const PcpMapFunction &
171  GetMapFunction() const { return _mapping; }
172 
173  /// Return a new EditTarget composed over \a weaker. This is
174  /// typically used to make an EditTarget "explicit". For example, an edit
175  /// target with a layer but with no mapping and no LayerStack identifier
176  /// indicates a layer in the local LayerStack of a composed scene.
177  /// However, an EditTarget with the same layer but an explicit identity
178  /// mapping and the LayerStack identifier of the composed scene may be
179  /// desired. This can be obtained by composing a partial (e.g. layer only)
180  /// EditTarget over an explicit EditTarget with layer, mapping and layer
181  /// stack identifier.
182  USD_API
183  UsdEditTarget ComposeOver(const UsdEditTarget &weaker) const;
184 
185 private:
186 
187  UsdEditTarget(const SdfLayerHandle &layer,
188  const PcpMapFunction &mapping);
189 
190  SdfLayerHandle _layer;
191  PcpMapFunction _mapping;
192 };
193 
194 
196 
197 #endif // PXR_USD_USD_EDIT_TARGET_H
USD_API SdfPath MapToSpecPath(const SdfPath &scenePath) const
bool IsValid() const
Definition: editTarget.h:137
#define USD_API
Definition: api.h:40
USD_API SdfSpecHandle GetSpecForScenePath(const SdfPath &scenePath) const
PXR_NAMESPACE_OPEN_SCOPE TF_DECLARE_WEAK_PTRS(UsdStage)
bool operator!=(const UsdEditTarget &other) const
Inequality comparison.
Definition: editTarget.h:127
GLenum GLuint GLint GLint layer
Definition: glcorearb.h:1299
GLintptr offset
Definition: glcorearb.h:665
USD_API UsdEditTarget ComposeOver(const UsdEditTarget &weaker) const
bool IsNull() const
Definition: editTarget.h:133
const PcpMapFunction & GetMapFunction() const
Definition: editTarget.h:171
USD_API SdfPrimSpecHandle GetPrimSpecForScenePath(const SdfPath &scenePath) const
static USD_API UsdEditTarget ForLocalDirectVariant(const SdfLayerHandle &layer, const SdfPath &varSelPath)
Definition: path.h:290
USD_API SdfPropertySpecHandle GetPropertySpecForScenePath(const SdfPath &scenePath) const
const SdfLayerHandle & GetLayer() const &
Return the layer this EditTarget contains.
Definition: editTarget.h:140
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
USD_API UsdEditTarget()
SdfLayerHandle GetLayer()&&
Definition: editTarget.h:141
USD_API bool operator==(const UsdEditTarget &other) const
Equality comparison.