This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
mapExpression.h
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_PCP_MAP_EXPRESSION_H
8#define PXR_USD_PCP_MAP_EXPRESSION_H
9
10#include "pxr/pxr.h"
11#include "pxr/usd/pcp/api.h"
12#include "pxr/usd/pcp/mapFunction.h"
13
14#include "pxr/base/tf/delegatedCountPtr.h"
15
16#include <tbb/spin_mutex.h>
17
18#include <atomic>
19#include <memory>
20
21PXR_NAMESPACE_OPEN_SCOPE
22
39{
40public:
43
48 PCP_API
49 const Value & Evaluate() const;
50
52 PcpMapExpression() noexcept = default;
53
54 ~PcpMapExpression() noexcept = default;
55
57 void Swap(PcpMapExpression &other) noexcept {
58 _node.swap(other._node);
59 }
60
62 bool IsNull() const noexcept {
63 return !_node;
64 }
65
68
70 PCP_API
72
74 PCP_API
75 static PcpMapExpression Constant( const Value & constValue );
76
80 class Variable {
81 Variable(Variable const &) = delete;
82 Variable &operator=(Variable const &) = delete;
83 public:
84 Variable() = default;
85 virtual ~Variable();
87 virtual const Value & GetValue() const = 0;
90 virtual void SetValue(Value && value) = 0;
93 virtual PcpMapExpression GetExpression() const = 0;
94 };
95
97 typedef std::unique_ptr<Variable> VariableUniquePtr;
98
105 PCP_API
106 static VariableUniquePtr NewVariable(Value && initialValue);
107
110 PCP_API
112
114 PCP_API
116
119 PCP_API
121
123 bool IsConstantIdentity() const {
124 return _node && _node->key.op == _OpConstant &&
125 _node->key.valueForConstant.IsIdentity();
126 }
127
129
134
137 bool IsIdentity() const {
138 return Evaluate().IsIdentity();
139 }
140
143 SdfPath MapSourceToTarget(const SdfPath &path) const {
144 return Evaluate().MapSourceToTarget(path);
145 }
146
149 SdfPath MapTargetToSource(const SdfPath &path) const {
150 return Evaluate().MapTargetToSource(path);
151 }
152
155 return Evaluate().GetTimeOffset();
156 }
157
160 std::string GetString() const {
161 return Evaluate().GetString();
162 }
163
165
166private:
167 // Allow Pcp_Statistics access to internal data for diagnostics.
168 friend class Pcp_Statistics;
169 friend struct Pcp_VariableImpl;
170
171 class _Node;
172 using _NodeRefPtr = TfDelegatedCountPtr<_Node>;
173
174 explicit PcpMapExpression(const _NodeRefPtr & node) : _node(node) {}
175
176private: // data
177 enum _Op {
178 _OpConstant,
179 _OpVariable,
180 _OpInverse,
181 _OpCompose,
182 _OpAddRootIdentity
183 };
184
185 class _Node {
186 _Node(const _Node&) = delete;
187 _Node& operator=(const _Node&) = delete;
188
189 // Ref-counting ops manage _refCount.
190 // Need to friend them here to have access to _refCount.
191 friend PCP_API void TfDelegatedCountIncrement(_Node*);
192 friend PCP_API void TfDelegatedCountDecrement(_Node*) noexcept;
193 public:
194 // The Key holds all the state needed to uniquely identify
195 // this (sub-)expression.
196 struct Key {
197 const _Op op;
198 const _NodeRefPtr arg1, arg2;
199 const Value valueForConstant;
200
201 Key( _Op op_,
202 const _NodeRefPtr & arg1_,
203 const _NodeRefPtr & arg2_,
204 const Value & valueForConstant_ )
205 : op(op_)
206 , arg1(arg1_)
207 , arg2(arg2_)
208 , valueForConstant(valueForConstant_)
209 {}
210 inline size_t GetHash() const;
211 bool operator==(const Key &key) const;
212 };
213
214 // The Key of a node is const, and established when it is created.
215 const Key key;
216
217 // Whether or not the expression tree up to and including this node
218 // will always include an identity mapping.
219 const bool expressionTreeAlwaysHasIdentity;
220
221 // Factory method to create new nodes.
222 static _NodeRefPtr
223 New( _Op op,
224 const _NodeRefPtr & arg1 = _NodeRefPtr(),
225 const _NodeRefPtr & arg2 = _NodeRefPtr(),
226 const Value & valueForConstant = Value() );
227 ~_Node();
228
229 // Evaluate (and internally cache) the value of this node.
230 const Value & EvaluateAndCache() const;
231
232 // For _OpVariable nodes, sets the variable's value.
233 void SetValueForVariable(Value &&newValue);
234
235 // For _OpVariable nodes, returns the variable's value.
236 const Value & GetValueForVariable() const {
237 return _valueForVariable;
238 }
239
240 private:
241 explicit _Node( const Key &key_ );
242 void _Invalidate();
243 Value _EvaluateUncached() const;
244
245 // Helper to determine if the expression tree indicated by key
246 // will always contains the root identity.
247 static bool _ExpressionTreeAlwaysHasIdentity(const Key& key);
248
249 // Registry of node instances, identified by Key.
250 // Note: variable nodes are not tracked by the registry.
251 struct _NodeMap;
252 static TfStaticData<_NodeMap> _nodeRegistry;
253
254 mutable std::atomic<int> _refCount;
255 mutable Value _cachedValue;
256 mutable std::set<_Node*> _dependentExpressions;
257 Value _valueForVariable;
258 mutable tbb::spin_mutex _mutex;
259 mutable std::atomic<bool> _hasCachedValue;
260 };
261
262 // Need to friend them here to have visibility to private class _Node.
263 friend PCP_API void TfDelegatedCountIncrement(_Node*);
264 friend PCP_API void TfDelegatedCountDecrement(_Node*) noexcept;
265
266 _NodeRefPtr _node;
267};
268
269PXR_NAMESPACE_CLOSE_SCOPE
270
271#endif // PXR_USD_PCP_MAP_EXPRESSION_H
A Variable is a mutable memory cell that holds a value.
Definition: mapExpression.h:80
virtual PcpMapExpression GetExpression() const =0
Return an expression representing the value of this variable.
virtual const Value & GetValue() const =0
Return the current value.
virtual void SetValue(Value &&value)=0
Mutate the variable to have the new value.
An expression that yields a PcpMapFunction value.
Definition: mapExpression.h:39
SdfPath MapTargetToSource(const SdfPath &path) const
Map a path in the target namespace to the source.
bool IsIdentity() const
Return true if the evaluated map function is the identity function.
bool IsConstantIdentity() const
Return true if the map function is the constant identity function.
bool IsNull() const noexcept
Return true if this is a null expression.
Definition: mapExpression.h:62
void Swap(PcpMapExpression &other) noexcept
Swap this expression with the other.
Definition: mapExpression.h:57
static PCP_API PcpMapExpression Identity()
Return an expression representing PcpMapFunction::Identity().
static PCP_API PcpMapExpression Constant(const Value &constValue)
Create a new constant.
std::unique_ptr< Variable > VariableUniquePtr
Variables are held by reference.
Definition: mapExpression.h:97
PCP_API PcpMapExpression Inverse() const
Create a new PcpMapExpression representing the inverse of f.
std::string GetString() const
Returns a string representation of this mapping for debugging purposes.
PCP_API const Value & Evaluate() const
Evaluate this expression, yielding a PcpMapFunction value.
PCP_API PcpMapExpression AddRootIdentity() const
Return a new expression representing this expression with an added (if necessary) mapping from </> to...
PCP_API PcpMapExpression Compose(const PcpMapExpression &f) const
Create a new PcpMapExpression representing the application of f's value, followed by the application ...
const SdfLayerOffset & GetTimeOffset() const
The time offset of the mapping.
static PCP_API VariableUniquePtr NewVariable(Value &&initialValue)
Create a new variable.
PcpMapFunction Value
The value type of PcpMapExpression is a PcpMapFunction.
Definition: mapExpression.h:42
SdfPath MapSourceToTarget(const SdfPath &path) const
Map a path in the source namespace to the target.
PcpMapExpression() noexcept=default
Default-construct a NULL expression.
A function that maps values from one namespace (and time domain) to another.
Definition: mapFunction.h:65
PCP_API SdfPath MapSourceToTarget(const SdfPath &path) const
Map a path in the source namespace to the target.
PCP_API bool IsIdentity() const
Return true if the map function is the identity function.
PCP_API std::string GetString() const
Returns a string representation of this mapping for debugging purposes.
PCP_API SdfPath MapTargetToSource(const SdfPath &path) const
Map a path in the target namespace to the source.
const SdfLayerOffset & GetTimeOffset() const
The time offset of the mapping.
Definition: mapFunction.h:206
Represents a time offset and scale between layers.
Definition: layerOffset.h:44
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:274
Stores a pointer to a ValueType which uses TfDelegatedCountIncrement and TfDelegatedCountDecrement to...
void swap(TfDelegatedCountPtr &other) noexcept
Swap this object's held pointer with other's.
Create or return a previously created object instance of global data.
Definition: staticData.h:96