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_DEPENDENCY_H
25 #define PXR_USD_PCP_DEPENDENCY_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/usd/pcp/api.h"
29 #include "pxr/usd/pcp/mapFunction.h"
30 #include "pxr/usd/sdf/path.h"
31 
32 #include <vector>
33 
34 PXR_NAMESPACE_OPEN_SCOPE
35 
36 class PcpNodeRef;
37 
38 /// \enum PcpDependencyType
39 ///
40 /// A classification of PcpPrimIndex->PcpSite dependencies
41 /// by composition structure.
42 ///
43 enum PcpDependencyType {
44     /// No type of dependency.
45     PcpDependencyTypeNone = 0,
46 
47     /// The root dependency of a cache on its root site.
48     /// This may be useful to either include, as when invalidating
49     /// caches in response to scene edits, or to exclude, as when
50     /// scanning dependency arcs to compensate for a namespace edit.
51     PcpDependencyTypeRoot = (1 << 0),
52 
53     /// Purely direct dependencies involve only arcs introduced
54     /// directly at this level of namespace.
55     PcpDependencyTypePurelyDirect = (1 << 1),
56 
57     /// Partly direct dependencies involve at least one arc introduced
58     /// directly at this level of namespace; they may also involve
59     /// ancestral arcs along the chain as well.
60     PcpDependencyTypePartlyDirect = (1 << 2),
61 
62     /// Ancestral dependencies involve only arcs from ancestral
63     /// levels of namespace, and no direct arcs.
64     PcpDependencyTypeAncestral = (1 << 3),
65 
66     /// Virtual dependencies do not contribute scene description,
67     /// yet represent sites whose scene description (or ancestral
68     /// scene description) informed the structure of the cache.
69     ///
70     /// One case of this is when a reference or payload arc
71     /// does not specify a prim, and the target layerStack does
72     /// not provide defaultPrim metadata either.  In that case
73     /// a virtual dependency to the root of that layer stack will
74     /// represent the latent dependency on that site's metadata.
75     ///
76     /// Another case of this is "spooky ancestral" dependencies from
77     /// relocates. These are referred to as "spooky" dependencies
78     /// because they can be seen as a form of action-at-a-distance. They
79     /// only occur as a result of relocation arcs.
80     PcpDependencyTypeVirtual = (1 << 4),
81     PcpDependencyTypeNonVirtual = (1 << 5),
82 
83     /// Combined mask value representing both pure and partly direct
84     /// deps.
85     PcpDependencyTypeDirect =
86         PcpDependencyTypePartlyDirect
87         | PcpDependencyTypePurelyDirect,
88 
89     /// Combined mask value representing any kind of dependency,
90     /// except virtual ones.
91     PcpDependencyTypeAnyNonVirtual =
92         PcpDependencyTypeRoot
93         | PcpDependencyTypeDirect
94         | PcpDependencyTypeAncestral
95         | PcpDependencyTypeNonVirtual,
96 
97     /// Combined mask value representing any kind of dependency.
98     PcpDependencyTypeAnyIncludingVirtual =
99         PcpDependencyTypeAnyNonVirtual
100         | PcpDependencyTypeVirtual,
101 };
102 
103 /// A typedef for a bitmask of flags from PcpDependencyType.
104 typedef unsigned int PcpDependencyFlags;
105 
106 /// Description of a dependency.
107 struct PcpDependency {
108     /// The path in this PcpCache's root layer stack that depends
109     /// on the site.
110     SdfPath indexPath;
111     /// The site path.  When using recurseDownNamespace, this may
112     /// be a path beneath the initial sitePath.
113     SdfPath sitePath;
114     /// The map function that applies to values from the site.
115     PcpMapFunction mapFunc;
116 
117     bool operator==(const PcpDependency &rhs) const {
118         return indexPath == rhs.indexPath &&
119             sitePath == rhs.sitePath &&
120             mapFunc == rhs.mapFunc;
121     }
122     bool operator!=(const PcpDependency &rhs) const {
123         return !(*this == rhs);
124     }
125 };
126 
127 typedef std::vector<PcpDependency> PcpDependencyVector;
128 
129 /// Returns true if this node introduces a dependency in its
130 /// PcpPrimIndex, false otherwise.  This is equivalent to
131 /// PcpClassifyNodeDependency(n) != PcpDependencyTypeNone, but
132 /// is faster.
133 PCP_API
134 bool PcpNodeIntroducesDependency(const PcpNodeRef &n);
135 
136 /// Classify the dependency represented by a node, by analyzing
137 /// its structural role in its PcpPrimIndex.  Returns a
138 /// bitmask of flags from PcpDependencyType.
139 PCP_API
140 PcpDependencyFlags PcpClassifyNodeDependency(const PcpNodeRef &n);
141 
142 PCP_API
143 std::string PcpDependencyFlagsToString(const PcpDependencyFlags flags);
144 
145 PXR_NAMESPACE_CLOSE_SCOPE
146 
147 #endif // PXR_USD_PCP_DEPENDENCY_H
148