HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
xformCache.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_XFORM_CACHE_H
25 #define PXR_USD_USD_GEOM_XFORM_CACHE_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/usd/usdGeom/api.h"
30 #include "pxr/usd/usd/prim.h"
31 
33 
34 #include "pxr/base/gf/matrix4d.h"
35 #include "pxr/base/tf/hash.h"
36 #include "pxr/base/tf/hashmap.h"
37 #include "pxr/base/tf/token.h"
38 
40 
41 
42 /// \class UsdGeomXformCache
43 ///
44 /// A caching mechanism for transform matrices. For best performance, this
45 /// object should be reused for multiple CTM queries.
46 ///
47 /// Instances of this type can be copied, though using Swap() may result in
48 /// better performance.
49 ///
50 /// It is valid to cache prims from multiple stages in a single XformCache.
51 ///
52 /// WARNING: this class does not automatically invalidate cached values based
53 /// on changes to the stage from which values were cached. Additionally, a
54 /// separate instance of this class should be used per-thread, calling the Get*
55 /// methods from multiple threads is not safe, as they mutate internal state.
56 ///
58 {
59 public:
60  /// Construct a new XformCache for the specified \p time.
62  explicit UsdGeomXformCache(const UsdTimeCode time);
63 
64  /// Construct a new XformCache for UsdTimeCode::Default().
67 
68  /// Compute the transformation matrix for the given \p prim, including the
69  /// transform authored on the Prim itself, if present.
70  ///
71  /// \note This method may mutate internal cache state and is not thread
72  /// safe.
75 
76  /// Compute the transformation matrix for the given \p prim, but do NOT
77  /// include the transform authored on the prim itself.
78  ///
79  /// \note This method may mutate internal cache state and is not thread
80  /// safe.
83 
84  /// Returns the local transformation of the prim. Uses the cached
85  /// XformQuery to compute the result quickly. The \p resetsXformStack
86  /// pointer must be valid. It will be set to true if \p prim resets
87  /// the transform stack.
88  /// The result of this call is cached.
91  bool *resetsXformStack);
92 
93  /// Returns the result of concatenating all transforms beneath \p ancestor
94  /// that affect \p prim. This includes the local transform of \p prim
95  /// itself, but not the local transform of \p ancestor. If \p ancestor is
96  /// not an ancestor of \p prim, the resulting transform is the
97  /// local-to-world transformation of \p prim.
98  /// The \p resetXformTsack pointer must be valid. If any intermediate prims
99  /// reset the transform stack, \p resetXformStack will be set to true.
100  /// Intermediate transforms are cached, but the result of this call itself
101  /// is not cached.
104  const UsdPrim &ancestor,
105  bool *resetXformStack);
106 
107  /// Whether the attribute named \p attrName, belonging to the
108  /// given \p prim affects the local transform value at the prim.
109  ///
110  /// \note This method may mutate internal cache state and is not thread
111  /// safe.
114  const TfToken &attrName);
115 
116  /// Whether the local transformation value at the prim may vary over time.
117  ///
118  /// \note This method may mutate internal cache state and is not thread
119  /// safe.
121  bool TransformMightBeTimeVarying(const UsdPrim &prim);
122 
123  /// Whether the xform stack is reset at the given prim.
124  ///
125  /// \note This method may mutate internal cache state and is not thread
126  /// safe.
128  bool GetResetXformStack(const UsdPrim &prim);
129 
130  /// Clears all pre-cached values.
132  void Clear();
133 
134  /// Use the new \p time when computing values and may clear any existing
135  /// values cached for the previous time. Setting \p time to the current time
136  /// is a no-op.
138  void SetTime(UsdTimeCode time);
139 
140  /// Get the current time from which this cache is reading values.
141  UsdTimeCode GetTime() { return _time; }
142 
143  /// Swap the contents of this XformCache with \p other.
145  void Swap(UsdGeomXformCache& other);
146 
147 private:
148 
149  // Traverses backwards the hierarchy starting from prim
150  // all the way to the root and computes the ctm
151  GfMatrix4d const* _GetCtm(const UsdPrim& prim);
152 
153  // Map of cached values.
154  struct _Entry {
155  _Entry() = default;
156  _Entry(const UsdGeomXformable::XformQuery & query_,
157  const GfMatrix4d& ctm_,
158  bool ctmIsValid_)
159  : query(query_)
160  , ctm(ctm_)
161  , ctmIsValid(ctmIsValid_)
162  { }
163 
165  GfMatrix4d ctm;
166  bool ctmIsValid;
167  };
168 
169  // Helper function to get or create a new entry for a prim in the ctm cache.
170  _Entry * _GetCacheEntryForPrim(const UsdPrim &prim);
171 
172  typedef TfHashMap<UsdPrim, _Entry, TfHash> _PrimHashMap;
173  _PrimHashMap _ctmCache;
174 
175  // The time at which this stack is querying and caching attribute values.
176  UsdTimeCode _time;
177 };
178 
179 #define USDGEOM_XFORM_CACHE_API_VERSION 1
180 
181 
183 
184 #endif // PXR_USD_USD_GEOM_XFORM_CACHE_H
GLenum query
Definition: glad.h:2772
USDGEOM_API GfMatrix4d GetLocalTransformation(const UsdPrim &prim, bool *resetsXformStack)
GT_API const UT_StringHolder time
UsdTimeCode GetTime()
Get the current time from which this cache is reading values.
Definition: xformCache.h:141
USDGEOM_API void SetTime(UsdTimeCode time)
USDGEOM_API bool GetResetXformStack(const UsdPrim &prim)
Definition: token.h:87
USDGEOM_API void Clear()
Clears all pre-cached values.
USDGEOM_API bool TransformMightBeTimeVarying(const UsdPrim &prim)
USDGEOM_API GfMatrix4d GetLocalToWorldTransform(const UsdPrim &prim)
Definition: prim.h:133
USDGEOM_API UsdGeomXformCache()
Construct a new XformCache for UsdTimeCode::Default().
USDGEOM_API GfMatrix4d GetParentToWorldTransform(const UsdPrim &prim)
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
USDGEOM_API GfMatrix4d ComputeRelativeTransform(const UsdPrim &prim, const UsdPrim &ancestor, bool *resetXformStack)
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
USDGEOM_API bool IsAttributeIncludedInLocalTransform(const UsdPrim &prim, const TfToken &attrName)
#define USDGEOM_API
Definition: api.h:40
USDGEOM_API void Swap(UsdGeomXformCache &other)
Swap the contents of this XformCache with other.