HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
listAPI.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 USDLUX_GENERATED_LISTAPI_H
25 #define USDLUX_GENERATED_LISTAPI_H
26 
27 /// \file usdLux/listAPI.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/usdLux/api.h"
32 #include "pxr/usd/usd/prim.h"
33 #include "pxr/usd/usd/stage.h"
34 #include "pxr/usd/usdLux/tokens.h"
35 
36 #include "pxr/base/vt/value.h"
37 
38 #include "pxr/base/gf/vec3d.h"
39 #include "pxr/base/gf/vec3f.h"
40 #include "pxr/base/gf/matrix4d.h"
41 
42 #include "pxr/base/tf/token.h"
43 #include "pxr/base/tf/type.h"
44 
46 
47 class SdfAssetPath;
48 
49 // -------------------------------------------------------------------------- //
50 // LISTAPI //
51 // -------------------------------------------------------------------------- //
52 
53 /// \class UsdLuxListAPI
54 ///
55 ///
56 /// \deprecated
57 /// Use LightListAPI instead
58 ///
59 ///
60 /// For any described attribute \em Fallback \em Value or \em Allowed \em Values below
61 /// that are text/tokens, the actual token is published and defined in \ref UsdLuxTokens.
62 /// So to set an attribute to the value "rightHanded", use UsdLuxTokens->rightHanded
63 /// as the value.
64 ///
66 {
67 public:
68  /// Compile time constant representing what kind of schema this class is.
69  ///
70  /// \sa UsdSchemaKind
72 
73  /// Construct a UsdLuxListAPI on UsdPrim \p prim .
74  /// Equivalent to UsdLuxListAPI::Get(prim.GetStage(), prim.GetPath())
75  /// for a \em valid \p prim, but will not immediately throw an error for
76  /// an invalid \p prim
77  explicit UsdLuxListAPI(const UsdPrim& prim=UsdPrim())
78  : UsdAPISchemaBase(prim)
79  {
80  }
81 
82  /// Construct a UsdLuxListAPI on the prim held by \p schemaObj .
83  /// Should be preferred over UsdLuxListAPI(schemaObj.GetPrim()),
84  /// as it preserves SchemaBase state.
85  explicit UsdLuxListAPI(const UsdSchemaBase& schemaObj)
86  : UsdAPISchemaBase(schemaObj)
87  {
88  }
89 
90  /// Destructor.
92  virtual ~UsdLuxListAPI();
93 
94  /// Return a vector of names of all pre-declared attributes for this schema
95  /// class and all its ancestor classes. Does not include attributes that
96  /// may be authored by custom/extended methods of the schemas involved.
98  static const TfTokenVector &
99  GetSchemaAttributeNames(bool includeInherited=true);
100 
101  /// Return a UsdLuxListAPI holding the prim adhering to this
102  /// schema at \p path on \p stage. If no prim exists at \p path on
103  /// \p stage, or if the prim at that path does not adhere to this schema,
104  /// return an invalid schema object. This is shorthand for the following:
105  ///
106  /// \code
107  /// UsdLuxListAPI(stage->GetPrimAtPath(path));
108  /// \endcode
109  ///
110  USDLUX_API
111  static UsdLuxListAPI
112  Get(const UsdStagePtr &stage, const SdfPath &path);
113 
114 
115  /// Returns true if this <b>single-apply</b> API schema can be applied to
116  /// the given \p prim. If this schema can not be a applied to the prim,
117  /// this returns false and, if provided, populates \p whyNot with the
118  /// reason it can not be applied.
119  ///
120  /// Note that if CanApply returns false, that does not necessarily imply
121  /// that calling Apply will fail. Callers are expected to call CanApply
122  /// before calling Apply if they want to ensure that it is valid to
123  /// apply a schema.
124  ///
125  /// \sa UsdPrim::GetAppliedSchemas()
126  /// \sa UsdPrim::HasAPI()
127  /// \sa UsdPrim::CanApplyAPI()
128  /// \sa UsdPrim::ApplyAPI()
129  /// \sa UsdPrim::RemoveAPI()
130  ///
131  USDLUX_API
132  static bool
133  CanApply(const UsdPrim &prim, std::string *whyNot=nullptr);
134 
135  /// Applies this <b>single-apply</b> API schema to the given \p prim.
136  /// This information is stored by adding "ListAPI" to the
137  /// token-valued, listOp metadata \em apiSchemas on the prim.
138  ///
139  /// \return A valid UsdLuxListAPI object is returned upon success.
140  /// An invalid (or empty) UsdLuxListAPI object is returned upon
141  /// failure. See \ref UsdPrim::ApplyAPI() for conditions
142  /// resulting in failure.
143  ///
144  /// \sa UsdPrim::GetAppliedSchemas()
145  /// \sa UsdPrim::HasAPI()
146  /// \sa UsdPrim::CanApplyAPI()
147  /// \sa UsdPrim::ApplyAPI()
148  /// \sa UsdPrim::RemoveAPI()
149  ///
150  USDLUX_API
151  static UsdLuxListAPI
152  Apply(const UsdPrim &prim);
153 
154 protected:
155  /// Returns the kind of schema this class belongs to.
156  ///
157  /// \sa UsdSchemaKind
158  USDLUX_API
159  UsdSchemaKind _GetSchemaKind() const override;
160 
161 private:
162  // needs to invoke _GetStaticTfType.
163  friend class UsdSchemaRegistry;
164  USDLUX_API
165  static const TfType &_GetStaticTfType();
166 
167  static bool _IsTypedSchema();
168 
169  // override SchemaBase virtuals.
170  USDLUX_API
171  const TfType &_GetTfType() const override;
172 
173 public:
174  // --------------------------------------------------------------------- //
175  // LIGHTLISTCACHEBEHAVIOR
176  // --------------------------------------------------------------------- //
177  /// Controls how the lightList should be interpreted.
178  /// Valid values are:
179  /// - consumeAndHalt: The lightList should be consulted,
180  /// and if it exists, treated as a final authoritative statement
181  /// of any lights that exist at or below this prim, halting
182  /// recursive discovery of lights.
183  /// - consumeAndContinue: The lightList should be consulted,
184  /// but recursive traversal over nameChildren should continue
185  /// in case additional lights are added by descendants.
186  /// - ignore: The lightList should be entirely ignored. This
187  /// provides a simple way to temporarily invalidate an existing
188  /// cache. This is the fallback behavior.
189  ///
190  ///
191  /// | ||
192  /// | -- | -- |
193  /// | Declaration | `token lightList:cacheBehavior` |
194  /// | C++ Type | TfToken |
195  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
196  /// | \ref UsdLuxTokens "Allowed Values" | consumeAndHalt, consumeAndContinue, ignore |
197  USDLUX_API
199 
200  /// See GetLightListCacheBehaviorAttr(), and also
201  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
202  /// If specified, author \p defaultValue as the attribute's default,
203  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
204  /// the default for \p writeSparsely is \c false.
205  USDLUX_API
206  UsdAttribute CreateLightListCacheBehaviorAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
207 
208 public:
209  // --------------------------------------------------------------------- //
210  // LIGHTLIST
211  // --------------------------------------------------------------------- //
212  /// Relationship to lights in the scene.
213  ///
214  USDLUX_API
216 
217  /// See GetLightListRel(), and also
218  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create
219  USDLUX_API
221 
222 public:
223  // ===================================================================== //
224  // Feel free to add custom code below this line, it will be preserved by
225  // the code generator.
226  //
227  // Just remember to:
228  // - Close the class declaration with };
229  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
230  // - Close the include guard with #endif
231  // ===================================================================== //
232  // --(BEGIN CUSTOM CODE)--
233 
234  /// Runtime control over whether to consult stored lightList caches.
235  enum ComputeMode {
236  /// Consult any caches found on the model hierarchy.
237  /// Do not traverse beneath the model hierarchy.
239  /// Ignore any caches found, and do a full prim traversal.
241  };
242 
243  /// Computes and returns the list of lights and light filters in
244  /// the stage, optionally consulting a cached result.
245  ///
246  /// In ComputeModeIgnoreCache mode, caching is ignored, and this
247  /// does a prim traversal looking for prims that have a UsdLuxLightAPI
248  /// or are of type UsdLuxLightFilter.
249  ///
250  /// In ComputeModeConsultModelHierarchyCache, this does a traversal
251  /// only of the model hierarchy. In this traversal, any lights that
252  /// live as model hierarchy prims are accumulated, as well as any
253  /// paths stored in lightList caches. The lightList:cacheBehavior
254  /// attribute gives further control over the cache behavior; see the
255  /// class overview for details.
256  ///
257  /// When instances are present, ComputeLightList(ComputeModeIgnoreCache)
258  /// will return the instance-uniqiue paths to any lights discovered
259  /// within those instances. Lights within a UsdGeomPointInstancer
260  /// will not be returned, however, since they cannot be referred to
261  /// solely via paths.
262  USDLUX_API
264 
265  /// Store the given paths as the lightlist for this prim.
266  /// Paths that do not have this prim's path as a prefix
267  /// will be silently ignored.
268  /// This will set the listList:cacheBehavior to "consumeAndContinue".
269  USDLUX_API
270  void StoreLightList(const SdfPathSet &) const;
271 
272  /// Mark any stored lightlist as invalid, by setting the
273  /// lightList:cacheBehavior attribute to ignore.
274  USDLUX_API
275  void InvalidateLightList() const;
276 };
277 
279 
280 #endif
static USDLUX_API UsdLuxListAPI Apply(const UsdPrim &prim)
UsdLuxListAPI(const UsdPrim &prim=UsdPrim())
Definition: listAPI.h:77
Single Apply API schema.
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
#define USDLUX_API
Definition: api.h:40
virtual USDLUX_API ~UsdLuxListAPI()
Destructor.
static USDLUX_API bool CanApply(const UsdPrim &prim, std::string *whyNot=nullptr)
USDLUX_API void InvalidateLightList() const
USDLUX_API UsdSchemaKind _GetSchemaKind() const override
USDLUX_API SdfPathSet ComputeLightList(ComputeMode mode) const
static USDLUX_API UsdLuxListAPI Get(const UsdStagePtr &stage, const SdfPath &path)
ComputeMode
Runtime control over whether to consult stored lightList caches.
Definition: listAPI.h:235
Definition: prim.h:133
USDLUX_API UsdAttribute GetLightListCacheBehaviorAttr() const
static USDLUX_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:457
Definition: path.h:290
GLenum mode
Definition: glcorearb.h:99
std::set< class SdfPath > SdfPathSet
A set of SdfPaths.
Definition: path.h:209
UsdSchemaKind
Definition: common.h:129
Ignore any caches found, and do a full prim traversal.
Definition: listAPI.h:240
USDLUX_API UsdRelationship CreateLightListRel() const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
USDLUX_API UsdRelationship GetLightListRel() const
USDLUX_API UsdAttribute CreateLightListCacheBehaviorAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
Definition: type.h:64
static const UsdSchemaKind schemaKind
Definition: listAPI.h:71
UsdLuxListAPI(const UsdSchemaBase &schemaObj)
Definition: listAPI.h:85
USDLUX_API void StoreLightList(const SdfPathSet &) const
Definition: value.h:164