HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
constraintTarget.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_GEOM_CONSTRAINT_TARGET_H
25 #define PXR_USD_USD_GEOM_CONSTRAINT_TARGET_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/usd/usdGeom/api.h"
29 #include "pxr/usd/usd/attribute.h"
30 
31 #include <string>
32 
34 
35 
36 class GfMatrix4d;
37 class UsdGeomXformCache;
38 
39 /// \class UsdGeomConstraintTarget
40 ///
41 /// Schema wrapper for UsdAttribute for authoring and introspecting
42 /// attributes that are constraint targets.
43 ///
44 /// Constraint targets correspond roughly to what some DCC's call locators.
45 /// They are coordinate frames, represented as (animated or static) GfMatrix4d
46 /// values. We represent them as attributes in USD rather than transformable
47 /// prims because generally we require no other coordinated information about
48 /// a constraint target other than its name and its matrix value, and because
49 /// attributes are more concise than prims.
50 ///
51 /// Because consumer clients often care only about the identity and value of
52 /// constraint targets and may be able to usefully consume them without caring
53 /// about the actual geometry with which they may logically correspond,
54 /// UsdGeom aggregates all constraint targets onto a model's root prim,
55 /// assuming that an exporter will use property namespacing within the
56 /// constraint target attribute's name to indicate a path to a prim within
57 /// the model with which the constraint target may correspond.
58 ///
59 /// To facilitate instancing, and also position-tweaking of baked assets, we
60 /// stipulate that constraint target values always be recorded in
61 /// <b>model-relative transformation space</b>. In other words, to get the
62 /// world-space value of a constraint target, transform it by the
63 /// local-to-world transformation of the prim on which it is recorded.
64 /// ComputeInWorldSpace() will perform this calculation.
65 ///
66 /// \todo Provide API for extracting prim or property path from a target's
67 /// namespaced name.
68 ///
70 {
71 public:
72 
73  // Default constructor returns an invalid ConstraintTarget. Exists for
74  // container classes
76  {
77  /* NOTHING */
78  }
79 
80  /// Speculative constructor that will produce a valid
81  /// UsdGeomConstraintTarget when \p attr already represents an attribute
82  /// that is a UsdGeomConstraintTarget, and produces an \em invalid
83  /// UsdGeomConstraintTarget otherwise (i.e.
84  /// \ref UsdGeomConstraintTarget_explicit_bool will return false).
85  ///
86  /// Calling \c UsdGeomConstraintTarget::IsValid(attr) will return the
87  /// same truth value as the object returned by this constructor, but if
88  /// you plan to subsequently use the ConstraintTarget anyways, just
89  /// construct the object and bool-evaluate it before proceeding.
91  explicit UsdGeomConstraintTarget(const UsdAttribute &attr);
92 
93  /// Test whether a given UsdAttribute represents valid ConstraintTarget,
94  /// which implies that creating a UsdGeomConstraintTarget from the attribute
95  /// will succeed.
96  ///
97  /// Success implies that \c attr.IsDefined() is true.
99  static bool IsValid(const UsdAttribute &attr);
100 
101  // ---------------------------------------------------------------
102  /// \name UsdAttribute API
103  // ---------------------------------------------------------------
104 
105  /// Allow UsdGeomConstraintTarget to auto-convert to UsdAttribute, so you
106  /// can pass a UsdGeomConstraintTarget to any function that accepts a
107  /// UsdAttribute or const-ref thereto.
108  operator UsdAttribute const& () const { return _attr; }
109 
110  /// Explicit UsdAttribute extractor
111  UsdAttribute const &GetAttr() const { return _attr; }
112 
113  /// Return true if the wrapped UsdAttribute::IsDefined(), and in
114  /// addition the attribute is identified as a ConstraintTarget.
115  bool IsDefined() const { return IsValid(_attr); }
116 
117 
118  /// \anchor UsdGeomConstraintTarget_explicit_bool
119  /// Explicit bool conversion operator. A ConstraintTarget object converts
120  /// to \c true iff it is valid for querying and authoring values and
121  /// metadata (which is identically equivalent to IsDefined()). It converts
122  /// to \c false otherwise.
123  explicit operator bool() const {
124  return IsDefined();
125  }
126 
127  /// Get the attribute value of the ConstraintTarget at \p time
130  const;
131 
132  /// Set the attribute value of the ConstraintTarget at \p time
134  bool Set(const GfMatrix4d& value, UsdTimeCode time = UsdTimeCode::Default())
135  const;
136 
137  /// Get the stored identifier unique to the enclosing model's namespace for
138  /// this constraint target.
139  /// \sa SetIdentifier()
141  TfToken GetIdentifier() const;
142 
143  /// Explicitly sets the stored identifier to the given string. Clients are
144  /// responsible for ensuring the uniqueness of this identifier within the
145  /// enclosing model's namespace.
147  void SetIdentifier(const TfToken &identifier);
148 
149  /// Returns the fully namespaced constraint attribute name, given the
150  /// constraint name.
152  static TfToken GetConstraintAttrName(const std::string &constraintName);
153 
154  /// Computes the value of the constraint target in world space.
155  ///
156  /// If a valid UsdGeomXformCache is provided in the argument \p xfCache,
157  /// it is used to evaluate the CTM of the model to which the constraint
158  /// target belongs.
159  ///
160  /// To get the constraint value in model-space (or local space), simply
161  /// use UsdGeomConstraintTarget::Get(), since the authored values must
162  /// already be in model-space.
163  ///
166  UsdGeomXformCache *xfCache=NULL) const;
167 
168 private:
169 
170  UsdAttribute _attr;
171 };
172 
173 
175 
176 #endif // USD_CONSTRAINT_TARGET_H
static constexpr UsdTimeCode Default()
Definition: timeCode.h:112
GT_API const UT_StringHolder time
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
USDGEOM_API void SetIdentifier(const TfToken &identifier)
USDGEOM_API bool Set(const GfMatrix4d &value, UsdTimeCode time=UsdTimeCode::Default()) const
Set the attribute value of the ConstraintTarget at time.
USDGEOM_API TfToken GetIdentifier() const
static USDGEOM_API bool IsValid(const UsdAttribute &attr)
Definition: token.h:87
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
USDGEOM_API bool Get(GfMatrix4d *value, UsdTimeCode time=UsdTimeCode::Default()) const
Get the attribute value of the ConstraintTarget at time.
#define USDGEOM_API
Definition: api.h:40
Definition: core.h:1131
static USDGEOM_API TfToken GetConstraintAttrName(const std::string &constraintName)
UsdAttribute const & GetAttr() const
Explicit UsdAttribute extractor.
USDGEOM_API GfMatrix4d ComputeInWorldSpace(UsdTimeCode time=UsdTimeCode::Default(), UsdGeomXformCache *xfCache=NULL) const