HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
variantSets.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_VARIANT_SETS_H
25 #define PXR_USD_USD_VARIANT_SETS_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/usd/usd/api.h"
29 #include "pxr/usd/usd/common.h"
30 #include "pxr/usd/usd/editTarget.h"
31 #include "pxr/usd/usd/prim.h"
32 
34 
35 #include <string>
36 #include <vector>
37 
39 
40 
44 
45 class SdfPath;
46 
47 /// \class UsdVariantSet
48 ///
49 /// A UsdVariantSet represents a single VariantSet in USD
50 /// (e.g. modelingVariant or shadingVariant), which can have multiple
51 /// variations that express different sets of opinions about the scene
52 /// description rooted at the prim that defines the VariantSet.
53 ///
54 /// (More detailed description of variants to follow)
55 ///
57 public:
58  /// Author a variant spec for \a variantName in this VariantSet at the
59  /// stage's current EditTarget, in the position specified by
60  /// \p position. Return true if the spec was successfully authored,
61  /// false otherwise.
62  ///
63  /// This will create the VariantSet itself, if necessary, so as long as
64  /// UsdPrim "prim" is valid, the following should always work:
65  /// \code
66  /// UsdVariantSet vs = prim.GetVariantSet("myVariantSet");
67  /// vs.AddVariant("myFirstVariation");
68  /// vs.SetVariantSelection("myFirstVariation");
69  /// {
70  /// UsdEditContext ctx(vs.GetVariantEditContext());
71  /// // Now all of our subsequent edits will go "inside" the
72  /// // 'myFirstVariation' variant of 'myVariantSet'
73  /// }
74  /// \endcode
75  USD_API
76  bool AddVariant(const std::string& variantName,
78 
79  /// Return the composed variant names for this VariantSet, ordered
80  /// lexicographically.
81  USD_API
82  std::vector<std::string> GetVariantNames() const;
83 
84  /// Returns true if this VariantSet already possesses a variant
85  // named \p variantName in any layer.
86  USD_API
87  bool HasAuthoredVariant(const std::string& variantName) const;
88 
89  /// Return the variant selection for this VariantSet. If there is
90  /// no selection, return the empty string.
91  USD_API
93 
94  /// Returns true if there is a selection authored for this VariantSet
95  /// in any layer.
96  ///
97  /// If requested, the variant selection (if any) will be returned in
98  /// \p value .
99  USD_API
100  bool HasAuthoredVariantSelection(std::string *value = nullptr) const;
101 
102  /// Author a variant selection for this VariantSet, setting it to
103  /// \a variantName in the stage's current EditTarget. If \p variantName
104  /// is empty, clear the variant selection (see ClearVariantSelection).
105  /// Call BlockVariantSelection to explicitly set an empty variant
106  /// selection.
107  ///
108  /// Return true if the selection was successfully authored or cleared,
109  /// false otherwise.
110  USD_API
111  bool SetVariantSelection(const std::string &variantName);
112 
113  /// Clear any selection for this VariantSet from the current EditTarget.
114  /// Return true on success, false otherwise.
115  USD_API
116  bool ClearVariantSelection();
117 
118  /// Block any weaker selections for this VariantSet by authoring an
119  /// empty string at the stage's current EditTarget.
120  /// Return true on success, false otherwise.
121  USD_API
122  bool BlockVariantSelection();
123 
124  /// Return a \a UsdEditTarget that edits the currently selected variant in
125  /// this VariantSet in \a layer. If there is no currently
126  /// selected variant in this VariantSet, return an invalid EditTarget.
127  ///
128  /// If \a layer is unspecified, then we will use the layer of our prim's
129  /// stage's current UsdEditTarget.
130  ///
131  /// Currently, we require \a layer to be in the stage's local LayerStack
132  /// (see UsdStage::HasLocalLayer()), and will issue an error and return
133  /// an invalid EditTarget if \a layer is not. We may relax this
134  /// restriction in the future, if need arises, but it introduces several
135  /// complications in specification and behavior.
136  USD_API
138  GetVariantEditTarget(const SdfLayerHandle &layer = SdfLayerHandle()) const;
139 
140  /// Helper function for configuring a UsdStage's EditTarget to author
141  /// into the currently selected variant. Returns configuration for a
142  /// UsdEditContext
143  ///
144  /// To begin editing into VariantSet \em varSet's currently selected
145  /// variant:
146  ///
147  /// In C++, we would use the following pattern:
148  /// \code
149  /// {
150  /// UsdEditContext ctxt(varSet.GetVariantEditContext());
151  ///
152  /// // All Usd mutation of the UsdStage on which varSet sits will
153  /// // now go "inside" the currently selected variant of varSet
154  /// }
155  /// \endcode
156  ///
157  /// In python, the pattern is:
158  /// \code{.py}
159  /// with varSet.GetVariantEditContext():
160  /// # Now sending mutations to current variant
161  /// \endcode
162  ///
163  /// See GetVariantEditTarget() for discussion of \p layer parameter
164  USD_API
165  std::pair<UsdStagePtr, UsdEditTarget>
166  GetVariantEditContext(const SdfLayerHandle &layer = SdfLayerHandle()) const;
167 
168 
169  /// Return this VariantSet's held prim.
170  UsdPrim const &GetPrim() const { return _prim; }
171 
172 
173  /// Return this VariantSet's name
174  std::string const &GetName() const { return _variantSetName; }
175 
176 
177  /// Is this UsdVariantSet object usable? If not, calling any of
178  /// its other methods is likely to crash.
179  bool IsValid() const {
180  return static_cast<bool>(_prim);
181  }
182 
183  /// Equivalent to IsValid().
184  explicit operator bool() const {
185  return IsValid();
186  }
187 
188 private:
189  UsdVariantSet(const UsdPrim &prim,
190  const std::string &variantSetName)
191  : _prim(prim)
192  , _variantSetName(variantSetName)
193  {
194  }
195 
196  SdfPrimSpecHandle _CreatePrimSpecForEditing();
197  SdfVariantSetSpecHandle _AddVariantSet(UsdListPosition position);
198 
199  UsdPrim _prim;
200  std::string _variantSetName;
201 
202  friend class UsdPrim;
203  friend class UsdVariantSets;
204 };
205 
206 
207 // TODO:
208 // VariantSet Names are stored as SdListOps, but a VariantSet is an actual spec
209 // (like a Prim). Is it important to make that distinction here?
210 
211 /// \class UsdVariantSets
212 ///
213 /// UsdVariantSets represents the collection of
214 /// \ref UsdVariantSet "VariantSets" that are present on a UsdPrim.
215 ///
216 /// A UsdVariantSets object, retrieved from a prim via
217 /// UsdPrim::GetVariantSets(), provides the API for interrogating and modifying
218 /// the composed list of VariantSets active defined on the prim, and also
219 /// the facility for authoring a VariantSet \em selection for any of those
220 /// VariantSets.
221 ///
223 public:
224 
225  /// Find an existing, or create a new VariantSet on the originating UsdPrim,
226  /// named \p variantSetName.
227  ///
228  /// This step is not always necessary, because if this UsdVariantSets
229  /// object is valid, then
230  /// \code
231  /// varSetsObj.GetVariantSet(variantSetName).AddVariant(variantName);
232  /// \endcode
233  /// will always succeed, creating the VariantSet first, if necessary. This
234  /// method exists for situations in which you want to create a VariantSet
235  /// without necessarily populating it with variants.
236  USD_API
237  UsdVariantSet AddVariantSet(const std::string& variantSetName,
239 
240  // TODO: don't we want remove and reorder, clear, etc. also?
241 
242  /// Compute the list of all VariantSets authored on the originating
243  /// UsdPrim. Always return true. Clear the contents of \p names and store
244  /// the result there.
245  USD_API
246  bool GetNames(std::vector<std::string>* names) const;
247 
248  /// Return a list of all VariantSets authored on the originating UsdPrim.
249  USD_API
250  std::vector<std::string> GetNames() const;
251 
252  UsdVariantSet operator[](const std::string& variantSetName) const {
253  return GetVariantSet(variantSetName);
254  }
255 
256  /// Return a UsdVariantSet object for \p variantSetName. This always
257  /// succeeds, although the returned VariantSet will be invalid if
258  /// the originating prim is invalid
259  USD_API
260  UsdVariantSet GetVariantSet(const std::string& variantSetName) const;
261 
262  /// Returns true if a VariantSet named \p variantSetName exists on
263  /// the originating prim.
264  USD_API
265  bool HasVariantSet(const std::string& variantSetName) const;
266 
267  /// Return the composed variant selection for the VariantSet named
268  /// \a variantSetName. If there is no selection, (or \p variantSetName
269  /// does not exist) return the empty string.
270  USD_API
271  std::string GetVariantSelection(const std::string& variantSetName) const;
272 
273  USD_API
274  bool SetSelection(const std::string& variantSetName,
275  const std::string& variantName);
276 
277  /// Returns the composed map of all variant selections authored on the
278  /// the originating UsdPrim, regardless of whether a corresponding
279  /// variant set exists.
280  USD_API
282 
283 
284 private:
285  explicit UsdVariantSets(const UsdPrim& prim)
286  : _prim(prim)
287  {
288  /* NOTHING */
289  }
290 
291  UsdPrim _prim;
292 
293  friend class UsdPrim;
294 };
295 
296 
298 
299 #endif //PXR_USD_USD_VARIANT_SETS_H
USD_API UsdVariantSet GetVariantSet(const std::string &variantSetName) const
USD_API bool SetSelection(const std::string &variantSetName, const std::string &variantName)
Definition: layer.h:97
USD_API bool ClearVariantSelection()
#define USD_API
Definition: api.h:40
std::string const & GetName() const
Return this VariantSet's name.
Definition: variantSets.h:174
USD_API bool BlockVariantSelection()
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
UsdVariantSet operator[](const std::string &variantSetName) const
Definition: variantSets.h:252
std::map< std::string, std::string > SdfVariantSelectionMap
A map of reference variant set names to variants in those sets.
Definition: types.h:275
UsdPrim const & GetPrim() const
Return this VariantSet's held prim.
Definition: variantSets.h:170
USD_API bool HasAuthoredVariant(const std::string &variantName) const
Returns true if this VariantSet already possesses a variant.
GLenum GLuint GLint GLint layer
Definition: glcorearb.h:1299
bool IsValid() const
Definition: variantSets.h:179
USD_API std::string GetVariantSelection(const std::string &variantSetName) const
USD_API std::string GetVariantSelection() const
Definition: prim.h:133
Definition: path.h:290
USD_API std::vector< std::string > GetNames() const
Return a list of all VariantSets authored on the originating UsdPrim.
USD_API bool HasAuthoredVariantSelection(std::string *value=nullptr) const
PXR_NAMESPACE_OPEN_SCOPE SDF_DECLARE_HANDLES(SdfLayer)
USD_API bool HasVariantSet(const std::string &variantSetName) const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
USD_API bool SetVariantSelection(const std::string &variantName)
USD_API UsdVariantSet AddVariantSet(const std::string &variantSetName, UsdListPosition position=UsdListPositionBackOfPrependList)
SIM_API const UT_StringHolder position
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
USD_API std::vector< std::string > GetVariantNames() const
USD_API SdfVariantSelectionMap GetAllVariantSelections() const
Definition: core.h:1131
UsdListPosition
Definition: common.h:88
USD_API bool AddVariant(const std::string &variantName, UsdListPosition position=UsdListPositionBackOfPrependList)
USD_API UsdEditTarget GetVariantEditTarget(const SdfLayerHandle &layer=SdfLayerHandle()) const
USD_API std::pair< UsdStagePtr, UsdEditTarget > GetVariantEditContext(const SdfLayerHandle &layer=SdfLayerHandle()) const