HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
layerStack.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_PCP_LAYER_STACK_H
25 #define PXR_USD_PCP_LAYER_STACK_H
26 
27 /// \file pcp/layerStack.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/pcp/api.h"
31 #include "pxr/usd/pcp/errors.h"
34 #include "pxr/usd/sdf/layerTree.h"
36 
37 #include <tbb/spin_mutex.h>
38 #include <iosfwd>
39 #include <memory>
40 #include <string>
41 #include <unordered_set>
42 #include <vector>
43 
45 
48 TF_DECLARE_WEAK_AND_REF_PTRS(Pcp_LayerStackRegistry);
49 
50 class ArResolverContext;
51 class Pcp_LayerStackRegistry;
52 class Pcp_MutedLayers;
55 class PcpLifeboat;
56 
57 /// \class PcpLayerStack
58 ///
59 /// Represents a stack of layers that contribute opinions to composition.
60 ///
61 /// Each PcpLayerStack is identified by a PcpLayerStackIdentifier. This
62 /// identifier contains all of the parameters needed to construct a layer stack,
63 /// such as the root layer, session layer, and path resolver context.
64 ///
65 /// PcpLayerStacks are constructed and managed by a Pcp_LayerStackRegistry.
66 ///
67 class PcpLayerStack : public TfRefBase, public TfWeakBase {
68  PcpLayerStack(const PcpLayerStack&) = delete;
69  PcpLayerStack& operator=(const PcpLayerStack&) = delete;
70 
71 public:
72  // See Pcp_LayerStackRegistry for creating layer stacks.
73  PCP_API
74  virtual ~PcpLayerStack();
75 
76  /// Returns the identifier for this layer stack.
77  PCP_API
79 
80  /// Returns the layers in this layer stack in strong-to-weak order.
81  /// Note that this is only the *local* layer stack -- it does not
82  /// include any layers brought in by references inside prims.
83  PCP_API
84  const SdfLayerRefPtrVector& GetLayers() const;
85 
86  /// Returns only the session layers in the layer stack in strong-to-weak
87  /// order.
88  PCP_API
89  SdfLayerHandleVector GetSessionLayers() const;
90 
91  /// Returns the layer tree representing the structure of this layer
92  /// stack.
93  PCP_API
94  const SdfLayerTreeHandle& GetLayerTree() const;
95 
96  /// Returns the layer offset for the given layer, or NULL if the layer
97  /// can't be found or is the identity.
98  PCP_API
99  const SdfLayerOffset* GetLayerOffsetForLayer(const SdfLayerHandle&) const;
100 
101  /// Return the layer offset for the given layer, or NULL if the layer
102  /// can't be found or is the identity.
103  PCP_API
105 
106  /// Returns the layer offset for the layer at the given index in this
107  /// layer stack. Returns NULL if the offset is the identity.
108  PCP_API
109  const SdfLayerOffset* GetLayerOffsetForLayer(size_t layerIdx) const;
110 
111  /// Returns the set of layers that were muted in this layer
112  /// stack.
113  PCP_API
114  const std::set<std::string>& GetMutedLayers() const;
115 
116  /// Return the list of errors local to this layer stack.
118  return _localErrors ? *_localErrors.get() : PcpErrorVector();
119  }
120 
121  /// Returns true if this layer stack contains the given layer, false
122  /// otherwise.
123  PCP_API
124  bool HasLayer(const SdfLayerHandle& layer) const;
125  PCP_API
126  bool HasLayer(const SdfLayerRefPtr& layer) const;
127 
128  /// Return the composed expression variables for this layer stack.
130  { return *_expressionVariables; }
131 
132  /// Return the set of expression variables used during the computation
133  /// of this layer stack. For example, this may include the variables
134  /// used in expression variable expressions in sublayer asset paths.
135  const std::unordered_set<std::string>&
137  { return _expressionVariableDependencies; }
138 
139  /// Return the time codes per second value of the layer stack. This is
140  /// usually the same as the computed time codes per second of the root layer
141  /// but may be computed from the session layer when its present.
142  double GetTimeCodesPerSecond() const { return _timeCodesPerSecond; }
143 
144  /// Returns relocation source-to-target mapping for this layer stack.
145  ///
146  /// This map combines the individual relocation entries found across
147  /// all layers in this layer stack; multiple entries that affect a single
148  /// prim will be combined into a single entry. For instance, if this
149  /// layer stack contains relocations { /A: /B } and { /A/C: /A/D }, this
150  /// map will contain { /A: /B } and { /B/C: /B/D }. This allows consumers
151  /// to go from unrelocated namespace to relocated namespace in a single
152  /// step.
153  PCP_API
155 
156  /// Returns relocation target-to-source mapping for this layer stack.
157  ///
158  /// See GetRelocatesSourceToTarget for more details.
159  PCP_API
161 
162  /// Returns incremental relocation source-to-target mapping for this layer
163  /// stack.
164  ///
165  /// This map contains the individual relocation entries found across
166  /// all layers in this layer stack; it does not combine ancestral
167  /// entries with descendant entries. For instance, if this
168  /// layer stack contains relocations { /A: /B } and { /A/C: /A/D }, this
169  /// map will contain { /A: /B } and { /A/C: /A/D }.
170  PCP_API
172 
173  /// Returns incremental relocation target-to-source mapping for this layer
174  /// stack.
175  ///
176  /// See GetIncrementalRelocatesTargetToSource for more details.
177  PCP_API
179 
180  /// Returns a list of paths to all prims across all layers in this
181  /// layer stack that contained relocates.
182  PCP_API
184 
185  /// Apply the changes in \p changes. This blows caches. It's up to
186  /// the client to pull on those caches again as needed.
187  ///
188  /// Objects that are no longer needed and would be destroyed are
189  /// retained in \p lifeboat and won't be destroyed until \p lifeboat is
190  /// itself destroyed. This gives the client control over the timing
191  /// of the destruction of those objects. Clients may choose to pull
192  /// on the caches before destroying \p lifeboat. That may cause the
193  /// caches to again retain the objects, meaning they won't be destroyed
194  /// when \p lifeboat is destroyed.
195  ///
196  /// For example, if blowing a cache means an SdfLayer is no longer
197  /// needed then \p lifeboat will hold an SdfLayerRefPtr to that layer.
198  /// The client can then pull on that cache, which could cause the
199  /// cache to hold an SdfLayerRefPtr to the layer again. If so then
200  /// destroying \p changes will not destroy the layer. In any case,
201  /// we don't destroy the layer and then read it again. However, if
202  /// the client destroys \p lifeboat before pulling on the cache then
203  /// we would destroy the layer then read it again.
204  PCP_API
205  void Apply(const PcpLayerStackChanges& changes, PcpLifeboat* lifeboat);
206 
207  /// Return a PcpMapExpression representing the relocations that affect
208  /// namespace at and below the given path. The value of this
209  /// expression will continue to track the effective relocations if
210  /// they are changed later.
211  PCP_API
213 
214 private:
215  // Only a registry can create a layer stack.
217  // PcpCache needs access to check the _registry.
218  friend class PcpCache;
219  // Needs access to _sublayerSourceInfo
220  friend bool Pcp_NeedToRecomputeDueToAssetPathChange(const PcpLayerStackPtr&);
221 
222  // Construct a layer stack for the given \p identifier that will be
223  // installed into \p registry. This installation is managed by
224  // \p registry and does not occur within the c'tor. See comments on
225  // _registry for more details.
226  PcpLayerStack(const PcpLayerStackIdentifier &identifier,
227  const Pcp_LayerStackRegistry &registry);
228 
229  void _BlowLayers();
230  void _BlowRelocations();
231  void _Compute(const std::string &fileFormatTarget,
232  const Pcp_MutedLayers &mutedLayers);
233 
234  SdfLayerTreeHandle _BuildLayerStack(
235  const SdfLayerHandle & layer,
236  const SdfLayerOffset & offset,
237  double layerTcps,
238  const ArResolverContext & pathResolverContext,
239  const SdfLayer::FileFormatArguments & layerArgs,
240  const std::string & sessionOwner,
241  const Pcp_MutedLayers & mutedLayers,
242  SdfLayerHandleSet *seenLayers,
243  PcpErrorVector *errors);
244 
245 private:
246  /// The identifier that uniquely identifies this layer stack.
247  const PcpLayerStackIdentifier _identifier;
248 
249  /// The registry (1:1 with a PcpCache) this layer stack belongs to. This
250  /// may not be set, particularly when a registry is creating a layer stack
251  /// but before it's been installed in the registry.
252  Pcp_LayerStackRegistryPtr _registry;
253 
254  /// Data representing the computed layer stack contents.
255  ///
256  /// This is built by examining the session and root layers for
257  /// sublayers, resolving their asset paths with the path resolver context,
258  /// and recursively building up the layer stack.
259  ///
260  /// Note that this is only the *local* layer stack -- it does not
261  /// include any layers brought in by references inside prims.
262 
263  /// Retained references to the layers in the stack,
264  /// in strong-to-weak order.
265  SdfLayerRefPtrVector _layers;
266 
267  /// The corresponding map functions for each entry in 'layers'.
268  /// Each map function contains a time offset that should be applied
269  /// to its corresponding layer.
270  std::vector<PcpMapFunction> _mapFunctions;
271 
272  /// Stores the computed time codes per second value of the layer stack which
273  /// has some special logic when a session layer is present.
274  double _timeCodesPerSecond;
275 
276  /// The tree structure of the layer stack.
277  /// Stored separately because this is needed only occasionally.
278  SdfLayerTreeHandle _layerTree;
279 
280  /// Tracks information used to compute sublayer asset paths.
281  struct _SublayerSourceInfo {
282  _SublayerSourceInfo() = default;
283  _SublayerSourceInfo(
284  const SdfLayerHandle& layer_,
285  const std::string& authoredSublayerPath_,
286  const std::string& computedSublayerPath_)
287  : layer(layer_)
288  , authoredSublayerPath(authoredSublayerPath_)
289  , computedSublayerPath(computedSublayerPath_) { }
290 
291  SdfLayerHandle layer;
292  std::string authoredSublayerPath;
293  std::string computedSublayerPath;
294  };
295 
296  /// List of source info for sublayer asset path computations.
297  std::vector<_SublayerSourceInfo> _sublayerSourceInfo;
298 
299  /// Set of asset paths that were muted in this layer stack.
300  std::set<std::string> _mutedAssetPaths;
301 
302  /// The errors, if any, discovered while computing this layer stack.
303  /// NULL if no errors were found (the expected common case).
304  std::unique_ptr<PcpErrorVector> _localErrors;
305 
306  /// Pre-computed table of local relocates.
307  SdfRelocatesMap _relocatesSourceToTarget;
308  SdfRelocatesMap _relocatesTargetToSource;
309  SdfRelocatesMap _incrementalRelocatesSourceToTarget;
310  SdfRelocatesMap _incrementalRelocatesTargetToSource;
311 
312  /// A map of PcpMapExpressions::Variable instances used to represent
313  /// the current value of relocations given out by
314  /// GetExpressionForRelocatesAtPath(). This map is used to update
315  /// those values when relocations change.
317  SdfPath::FastLessThan> _RelocatesVarMap;
318  _RelocatesVarMap _relocatesVariables;
319  tbb::spin_mutex _relocatesVariablesMutex;
320 
321  /// List of all prim spec paths where relocations were found.
322  SdfPathVector _relocatesPrimPaths;
323 
324  /// Composed expression variables.
325  std::shared_ptr<PcpExpressionVariables> _expressionVariables;
326 
327  /// Set of expression variables this layer stack depends on.
328  std::unordered_set<std::string> _expressionVariableDependencies;
329 
330  bool _isUsd;
331 };
332 
333 PCP_API
334 std::ostream& operator<<(std::ostream&, const PcpLayerStackPtr&);
335 PCP_API
336 std::ostream& operator<<(std::ostream&, const PcpLayerStackRefPtr&);
337 
338 /// Compose the relocation arcs in the given stack of layers,
339 /// putting the results into the given sourceToTarget and targetToSource
340 /// maps.
341 void
343  const SdfLayerRefPtrVector & layers,
344  SdfRelocatesMap *relocatesSourceToTarget,
345  SdfRelocatesMap *relocatesTargetToSource,
346  SdfRelocatesMap *incrementalRelocatesSourceToTarget,
347  SdfRelocatesMap *incrementalRelocatesTargetToSource,
348  SdfPathVector *relocatesPrimPaths);
349 
350 // Returns true if \p layerStack should be recomputed due to changes to
351 // any computed asset paths that were used to find or open layers
352 // when originally composing \p layerStack. This may be due to scene
353 // description changes or external changes to asset resolution that
354 // may affect the computation of those asset paths.
355 bool
356 Pcp_NeedToRecomputeDueToAssetPathChange(const PcpLayerStackPtr& layerStack);
357 
358 // Returns true if the \p layerStack should be recomputed because
359 // \p changedLayer has had changes that would cause the layer stack to have
360 // a different computed overall time codes per second value.
361 bool
363  const PcpLayerStackPtr& layerStack, const SdfLayerHandle &changedLayer);
364 
365 /// Returns true when the environment variable has been set to disable the
366 /// behavior where differing time codes per second metadata in layers sublayered
367 /// or referenced by another layer are used to apply a layer offset scale to the
368 /// map function.
369 PCP_API
370 bool
372 
374 
375 #endif // PXR_USD_PCP_LAYER_STACK_H
Definition: layer.h:97
virtual PCP_API ~PcpLayerStack()
PCP_API const SdfRelocatesMap & GetRelocatesTargetToSource() const
PCP_API const SdfLayerOffset * GetLayerOffsetForLayer(const SdfLayerHandle &) const
PCP_API std::ostream & operator<<(std::ostream &, const PcpLayerStackPtr &)
PCP_API const PcpLayerStackIdentifier & GetIdentifier() const
Returns the identifier for this layer stack.
friend bool Pcp_NeedToRecomputeDueToAssetPathChange(const PcpLayerStackPtr &)
std::map< SdfPath, SdfPath > SdfRelocatesMap
A map of source SdfPaths to target SdfPaths for relocation.
Definition: types.h:284
PCP_API SdfLayerHandleVector GetSessionLayers() const
PCP_API const SdfRelocatesMap & GetIncrementalRelocatesSourceToTarget() const
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
std::map< std::string, std::string > FileFormatArguments
Definition: layer.h:123
void Pcp_ComputeRelocationsForLayerStack(const SdfLayerRefPtrVector &layers, SdfRelocatesMap *relocatesSourceToTarget, SdfRelocatesMap *relocatesTargetToSource, SdfRelocatesMap *incrementalRelocatesSourceToTarget, SdfRelocatesMap *incrementalRelocatesTargetToSource, SdfPathVector *relocatesPrimPaths)
PCP_API const SdfRelocatesMap & GetRelocatesSourceToTarget() const
Definition: cache.h:93
std::set< SdfHandleTo< SdfLayer >::Handle > SdfLayerHandleSet
PCP_API void Apply(const PcpLayerStackChanges &changes, PcpLifeboat *lifeboat)
PXR_NAMESPACE_OPEN_SCOPE TF_DECLARE_REF_PTRS(SdfLayer)
friend class Pcp_LayerStackRegistry
Definition: layerStack.h:216
TF_DECLARE_WEAK_AND_REF_PTRS(PcpLayerStack)
GLenum GLuint GLint GLint layer
Definition: glcorearb.h:1299
PCP_API const SdfRelocatesMap & GetIncrementalRelocatesTargetToSource() const
GLintptr offset
Definition: glcorearb.h:665
std::vector< TfRefPtr< SdfLayer > > SdfLayerRefPtrVector
double GetTimeCodesPerSecond() const
Definition: layerStack.h:142
PCP_API const SdfPathVector & GetPathsToPrimsWithRelocates() const
PcpErrorVector GetLocalErrors() const
Return the list of errors local to this layer stack.
Definition: layerStack.h:117
bool Pcp_NeedToRecomputeDueToAssetPathChange(const PcpLayerStackPtr &layerStack)
std::unique_ptr< Variable > VariableUniquePtr
Variables are held by reference.
Definition: path.h:290
std::vector< class SdfPath > SdfPathVector
A vector of SdfPaths.
Definition: path.h:211
const std::unordered_set< std::string > & GetExpressionVariableDependencies() const
Definition: layerStack.h:136
std::vector< PcpErrorBasePtr > PcpErrorVector
Definition: errors.h:78
PCP_API bool PcpIsTimeScalingForLayerTimeCodesPerSecondDisabled()
PCP_API bool HasLayer(const SdfLayerHandle &layer) const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
PCP_API const SdfLayerRefPtrVector & GetLayers() const
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
const PcpExpressionVariables & GetExpressionVariables() const
Return the composed expression variables for this layer stack.
Definition: layerStack.h:129
PCP_API const std::set< std::string > & GetMutedLayers() const
PCP_API PcpMapExpression GetExpressionForRelocatesAtPath(const SdfPath &path)
bool Pcp_NeedToRecomputeLayerStackTimeCodesPerSecond(const PcpLayerStackPtr &layerStack, const SdfLayerHandle &changedLayer)
PCP_API const SdfLayerTreeHandle & GetLayerTree() const
#define PCP_API
Definition: api.h:40