HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
stagePopulationMask.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_STAGE_POPULATION_MASK_H
25 #define PXR_USD_USD_STAGE_POPULATION_MASK_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/usd/usd/api.h"
29 #include "pxr/usd/sdf/path.h"
30 
31 #include <iosfwd>
32 #include <vector>
33 
35 
36 
37 /// \class UsdStagePopulationMask
38 ///
39 /// This class represents a mask that may be applied to a UsdStage to limit the
40 /// set of UsdPrim s it populates. This is useful in cases where clients have a
41 /// large scene but only wish to view or query a single or a handful of objects.
42 /// For example, suppose we have a city block with buildings, cars, crowds of
43 /// people, and a couple of main characters. Some tasks might only require
44 /// looking at a single main character and perhaps a few props. We can create a
45 /// population mask with the paths to the character and props of interest and
46 /// open a UsdStage with that mask. Usd will avoid populating the other objects
47 /// in the scene, saving time and memory. See UsdStage::OpenMasked() for more.
48 ///
49 /// A mask is defined by a set of SdfPath s with the following qualities: they
50 /// are absolute prim paths (or the absolute root path), and no path in the set
51 /// is an ancestor path of any other path in the set other than itself. For
52 /// example, the set of paths ['/a/b', '/a/c', '/x/y'] is a valid mask, but the
53 /// set of paths ['/a/b', '/a/b/c', '/x/y'] is redundant, since '/a/b' is an
54 /// ancestor of '/a/b/c'. The path '/a/b/c' may be removed. The GetUnion() and
55 /// Add() methods ensure that no redundant paths are added.
56 ///
57 /// Default-constructed UsdStagePopulationMask s are considered empty
58 /// (IsEmpty()) and include no paths. A population mask containing
59 /// SdfPath::AbsoluteRootPath() includes all paths.
61 {
62 public:
63  /// Return a mask that includes all paths. This is the mask that contains
64  /// the absolute root path.
66  All() {
68  }
69 
70  /// Construct an empty mask that includes no paths.
71  UsdStagePopulationMask() = default;
72 
77 
78  /// Construct a mask from the range of paths [f, l). All paths in the range
79  /// must be absolute prim paths or the absolute root path. (See
80  /// SdfPath::IsAbsolutePath, SdfPath::IsAbsoluteRootOrPrimPath).
81  template <class Iter>
82  explicit UsdStagePopulationMask(Iter f, Iter l) : _paths(f, l) {
83  _ValidateAndNormalize();
84  }
85 
86  /// Construct a mask from \p paths. All paths must be absolute prim paths
87  /// or the absolute root path. (See SdfPath::IsAbsolutePath,
88  /// SdfPath::IsAbsoluteRootOrPrimPath).
89  explicit UsdStagePopulationMask(std::vector<SdfPath> const &paths) :
90  UsdStagePopulationMask(std::vector<SdfPath>(paths)) {};
91 
92  /// Construct a mask from \p paths. All paths must be absolute prim paths
93  /// or the absolute root path. (See SdfPath::IsAbsolutePath,
94  /// SdfPath::IsAbsoluteRootOrPrimPath).
95  USD_API
96  explicit UsdStagePopulationMask(std::vector<SdfPath> &&paths);
97 
98  /// Return a mask that is the union of \p l and \p r.
99  USD_API
102 
103  /// Return a mask that is the union of this and \p other.
104  USD_API
106 
107  /// Return a mask that is the union of this and a mask containing the single
108  /// \p path.
109  USD_API
111 
112  /// Return a mask that is the intersection of \p l and \p r.
113  USD_API
116  UsdStagePopulationMask const &r);
117 
118  /// Return a mask that is the intersection of this and \p other.
119  USD_API
121  GetIntersection(UsdStagePopulationMask const &other) const;
122 
123  /// Return true if this mask is a superset of \p other. That is, if this
124  /// mask includes at least every path that \p other includes.
125  USD_API
126  bool Includes(UsdStagePopulationMask const &other) const;
127 
128  /// Return true if this mask includes \p path. This is true if \p path is
129  /// one of the paths in this mask, or if it is either a descendant or an
130  /// ancestor of one of the paths in this mask.
131  USD_API
132  bool Includes(SdfPath const &path) const;
133 
134  /// Return true if this mask includes \p path and all paths descendant to
135  /// \p path. For example, consider a mask containing the path '/a/b'.
136  /// Then the following holds:
137  ///
138  /// \code
139  /// mask.Includes('/a') -> true
140  /// mask.Includes('/a/b') -> true
141  /// mask.IncludesSubtree('/a') -> false
142  /// mask.IncludesSubtree('/a/b') -> true
143  /// \endcode
144  USD_API
145  bool IncludesSubtree(SdfPath const &path) const;
146 
147  /// Return true if this mask contains no paths. Empty masks include no
148  /// paths.
149  bool IsEmpty() const {
150  return _paths.empty();
151  }
152 
153  /// Return true if this mask includes any child prims beneath \p path,
154  /// false otherwise. If only specific child prims beneath \p path are
155  /// included, the names of those children will be returned in \p childNames.
156  /// If all child prims beneath \p path are included, \p childNames will
157  /// be empty.
158  USD_API
159  bool GetIncludedChildNames(SdfPath const &path,
160  std::vector<TfToken> *childNames) const;
161 
162  /// Return the set of paths that define this mask.
163  USD_API
164  std::vector<SdfPath> GetPaths() const;
165 
166  /// Assign this mask to be its union with \p other and return a reference to
167  /// this mask.
169  *this = GetUnion(other);
170  return *this;
171  }
172 
173  /// Assign this mask to be its union with \p path and return a reference to
174  /// this mask.
176  *this = GetUnion(path);
177  return *this;
178  }
179 
180  /// Return true if this mask is equivalent to \p other.
181  bool operator==(UsdStagePopulationMask const &other) const {
182  return _paths == other._paths;
183  }
184 
185  /// Return true if this mask is not equivalent to \p other.
186  bool operator!=(UsdStagePopulationMask const &other) const {
187  return !(*this == other);
188  }
189 
190  /// Swap the content of this mask with \p other.
192  _paths.swap(other._paths);
193  }
194 
195 private:
196  friend USD_API size_t hash_value(UsdStagePopulationMask const &);
197 
198  USD_API void _ValidateAndNormalize();
199 
200  std::vector<SdfPath> _paths;
201 };
202 
203 /// Stream a text representation of a mask.
204 USD_API
205 std::ostream &operator<<(std::ostream &, UsdStagePopulationMask const &);
206 
207 /// Swap the contents of masks \p l and \p r.
209 {
210  l.swap(r);
211 }
212 
213 USD_API
214 size_t hash_value(UsdStagePopulationMask const &);
215 
217 
218 #endif // PXR_USD_USD_STAGE_POPULATION_MASK_H
void swap(ArAssetInfo &lhs, ArAssetInfo &rhs)
Definition: assetInfo.h:61
UsdStagePopulationMask(Iter f, Iter l)
static SDF_API const SdfPath & AbsoluteRootPath()
#define USD_API
Definition: api.h:40
USD_API bool GetIncludedChildNames(SdfPath const &path, std::vector< TfToken > *childNames) const
UsdStagePopulationMask & Add(SdfPath const &path)
GLsizei const GLchar *const * path
Definition: glcorearb.h:3340
UsdStagePopulationMask()=default
Construct an empty mask that includes no paths.
USD_API std::ostream & operator<<(std::ostream &, UsdStagePopulationMask const &)
Stream a text representation of a mask.
GLdouble l
Definition: glew.h:9164
USD_API std::vector< SdfPath > GetPaths() const
Return the set of paths that define this mask.
static USD_API UsdStagePopulationMask Union(UsdStagePopulationMask const &l, UsdStagePopulationMask const &r)
Return a mask that is the union of l and r.
USD_API UsdStagePopulationMask GetUnion(UsdStagePopulationMask const &other) const
Return a mask that is the union of this and other.
bool operator!=(UsdStagePopulationMask const &other) const
Return true if this mask is not equivalent to other.
UsdStagePopulationMask & operator=(UsdStagePopulationMask const &)=default
Definition: path.h:288
friend USD_API size_t hash_value(UsdStagePopulationMask const &)
UsdStagePopulationMask & Add(UsdStagePopulationMask const &other)
void swap(UsdStagePopulationMask &other)
Swap the content of this mask with other.
UsdStagePopulationMask(std::vector< SdfPath > const &paths)
USD_API UsdStagePopulationMask GetIntersection(UsdStagePopulationMask const &other) const
Return a mask that is the intersection of this and other.
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1375
USD_API size_t hash_value(UsdStagePopulationMask const &)
bool operator==(UsdStagePopulationMask const &other) const
Return true if this mask is equivalent to other.
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
static UsdStagePopulationMask All()
GLfloat f
Definition: glcorearb.h:1925
USD_API bool IncludesSubtree(SdfPath const &path) const
static USD_API UsdStagePopulationMask Intersection(UsdStagePopulationMask const &l, UsdStagePopulationMask const &r)
Return a mask that is the intersection of l and r.
GLboolean r
Definition: glcorearb.h:1221
USD_API bool Includes(UsdStagePopulationMask const &other) const
GLenum const void * paths
Definition: glew.h:13872