HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
relationshipSpec.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 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_SDF_RELATIONSHIP_SPEC_H
8 #define PXR_USD_SDF_RELATIONSHIP_SPEC_H
9 
10 /// \file sdf/relationshipSpec.h
11 
12 #include "pxr/pxr.h"
13 #include "pxr/usd/sdf/api.h"
16 #include "pxr/usd/sdf/types.h"
17 
19 
20 /// \class SdfRelationshipSpec
21 ///
22 /// A property that contains a reference to one or more SdfPrimSpec instances.
23 ///
24 /// A relationship may refer to one or more target prims or attributes.
25 /// All targets of a single relationship are considered to be playing the same
26 /// role. Note that \c role does not imply that the target prims or attributes
27 /// are of the same \c type.
28 ///
29 /// Relationships may be annotated with relational attributes.
30 /// Relational attributes are named SdfAttributeSpec objects containing
31 /// values that describe the relationship. For example, point weights are
32 /// commonly expressed as relational attributes.
33 ///
35 {
36  SDF_DECLARE_SPEC(SdfRelationshipSpec, SdfPropertySpec);
37 
38 public:
41 
42  ///
43  /// \name Spec creation
44  /// @{
45 
46  /// Creates a new prim relationship instance.
47  ///
48  /// Creates and returns a new relationship for the given prim.
49  /// The \p owner will own the newly created relationship.
50  SDF_API
51  static SdfRelationshipSpecHandle
52  New(const SdfPrimSpecHandle& owner,
53  const std::string& name,
54  bool custom = true,
56 
57  /// @}
58 
59  /// \name Relationship targets
60  /// @{
61 
62  /// Returns the relationship's target path list editor.
63  ///
64  /// The list of the target paths for this relationship may be modified
65  /// through the proxy.
66  SDF_API
68 
69  /// Returns true if the relationship has any target paths.
70  SDF_API
71  bool HasTargetPathList() const;
72 
73  /// Clears the list of target paths on this relationship.
74  SDF_API
75  void ClearTargetPathList() const;
76 
77  /// Updates the specified target path.
78  ///
79  /// Replaces the path given by \p oldPath with the one specified by
80  /// \p newPath. Relational attributes are updated if necessary.
81  SDF_API
82  void ReplaceTargetPath(const SdfPath& oldPath, const SdfPath& newPath);
83 
84  /// Removes the specified target path.
85  ///
86  /// Removes the given target path and any relational attributes for the
87  /// given target path. If \p preserveTargetOrder is \c true, Erase() is
88  /// called on the list editor instead of RemoveItemEdits(). This preserves
89  /// the ordered items list.
90  SDF_API
91  void RemoveTargetPath(const SdfPath& path, bool preserveTargetOrder = false);
92 
93  /// @}
94 
95  /// Get whether loading the target of this relationship is necessary
96  /// to load the prim we're attached to
97  SDF_API
98  bool GetNoLoadHint(void) const;
99 
100  /// Set whether loading the target of this relationship is necessary
101  /// to load the prim we're attached to
102  SDF_API
103  void SetNoLoadHint(bool noload);
104 
105 private:
106  SdfPath _CanonicalizeTargetPath(const SdfPath& path) const;
107 
108  SdfPath _MakeCompleteTargetSpecPath(const SdfPath& srcPath) const;
109 
110  SdfSpecHandle _GetTargetSpec(const SdfPath& path) const;
111 
112  // Allow access to _GetTarget() for the relational attribute c'tor
113  friend class SdfAttributeSpec;
114 
115  // Allow access to retrieve relationship spec for this API object.
117 };
118 
119 /// Convenience function to create a relationshipSpec on a primSpec at the
120 /// given path, and any necessary parent primSpecs, in the given layer.
121 ///
122 /// If a relationshipSpec already exists at the given path, author
123 /// variability and custom according to passed arguments and return
124 /// a relationship spec handle.
125 ///
126 /// Any newly created prim specs have SdfSpecifierOver and an empty type (as if
127 /// created by SdfJustCreatePrimInLayer()). relPath must be a valid prim
128 /// property path (see SdfPath::IsPrimPropertyPath()). Return false and issue
129 /// an error if we fail to author the required scene description.
130 SDF_API
131 SdfRelationshipSpecHandle
133  const SdfLayerHandle &layer,
134  const SdfPath &relPath,
136  bool isCustom = false);
137 
138 /// Convenience function to create a relationshipSpec on a primSpec at the
139 /// given path, and any necessary parent primSpecs, in the given layer.
140 ///
141 /// If a relationshipSpec already exists at the given path, author
142 /// variability and custom according to passed arguments and return
143 /// a relationship spec handle.
144 ///
145 /// Any newly created prim specs have SdfSpecifierOver and an empty type (as if
146 /// created by SdfJustCreatePrimInLayer()). relPath must be a valid prim
147 /// property path (see SdfPath::IsPrimPropertyPath()). Return false and issue
148 /// an error if we fail to author the required scene description.
149 ///
150 /// Differs only from SdfCreateRelationshipInLayer only in that a
151 /// bool, not a handle, is returned.
152 SDF_API
153 bool
155  const SdfLayerHandle &layer,
156  const SdfPath &relPath,
158  bool isCustom = false);
159 
161 
162 #endif // PXR_USD_SDF_RELATIONSHIP_SPEC_H
SDF_API SdfRelationshipSpecHandle SdfCreateRelationshipInLayer(const SdfLayerHandle &layer, const SdfPath &relPath, SdfVariability variability=SdfVariabilityVarying, bool isCustom=false)
SDF_API bool GetNoLoadHint(void) const
SDF_API SdfTargetsProxy GetTargetPathList() const
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
SdfRelationshipSpec This
friend class Sdf_PyRelationshipAccess
static SDF_API SdfRelationshipSpecHandle New(const SdfPrimSpecHandle &owner, const std::string &name, bool custom=true, SdfVariability variability=SdfVariabilityUniform)
SdfPropertySpec Parent
GLenum GLuint GLint GLint layer
Definition: glcorearb.h:1299
SDF_API void ClearTargetPathList() const
Clears the list of target paths on this relationship.
GLuint const GLchar * name
Definition: glcorearb.h:786
SDF_API bool HasTargetPathList() const
Returns true if the relationship has any target paths.
Definition: path.h:273
SdfVariability
Definition: types.h:156
SDF_API void ReplaceTargetPath(const SdfPath &oldPath, const SdfPath &newPath)
#define SDF_API
Definition: api.h:23
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
SDF_API void RemoveTargetPath(const SdfPath &path, bool preserveTargetOrder=false)
SDF_API bool SdfJustCreateRelationshipInLayer(const SdfLayerHandle &layer, const SdfPath &relPath, SdfVariability variability=SdfVariabilityVarying, bool isCustom=false)
SDF_API void SetNoLoadHint(bool noload)