HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
lightListAPI.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the terms set forth in the LICENSE.txt file available at
5 // https://openusd.org/license.
6 //
7 #ifndef USDLUX_GENERATED_LIGHTLISTAPI_H
8 #define USDLUX_GENERATED_LIGHTLISTAPI_H
9 
10 /// \file usdLux/lightListAPI.h
11 
12 #include "pxr/pxr.h"
13 #include "pxr/usd/usdLux/api.h"
15 #include "pxr/usd/usd/prim.h"
16 #include "pxr/usd/usd/stage.h"
17 #include "pxr/usd/usdLux/tokens.h"
18 
19 #include "pxr/base/vt/value.h"
20 
21 #include "pxr/base/gf/vec3d.h"
22 #include "pxr/base/gf/vec3f.h"
23 #include "pxr/base/gf/matrix4d.h"
24 
25 #include "pxr/base/tf/token.h"
26 #include "pxr/base/tf/type.h"
27 
29 
30 class SdfAssetPath;
31 
32 // -------------------------------------------------------------------------- //
33 // LIGHTLISTAPI //
34 // -------------------------------------------------------------------------- //
35 
36 /// \class UsdLuxLightListAPI
37 ///
38 /// API schema to support discovery and publishing of lights in a scene.
39 ///
40 /// \section UsdLuxLightListAPI_Discovery Discovering Lights via Traversal
41 ///
42 /// To motivate this API, consider what is required to discover all
43 /// lights in a scene. We must load all payloads and traverse all prims:
44 ///
45 /// \code
46 /// 01 // Load everything on the stage so we can find all lights,
47 /// 02 // including those inside payloads
48 /// 03 stage->Load();
49 /// 04
50 /// 05 // Traverse all prims, checking if they have an applied UsdLuxLightAPI
51 /// 06 // (Note: ignoring instancing and a few other things for simplicity)
52 /// 07 SdfPathVector lights;
53 /// 08 for (UsdPrim prim: stage->Traverse()) {
54 /// 09 if (prim.HasAPI<UsdLuxLightAPI>()) {
55 /// 10 lights.push_back(i->GetPath());
56 /// 11 }
57 /// 12 }
58 /// \endcode
59 ///
60 /// This traversal -- suitably elaborated to handle certain details --
61 /// is the first and simplest thing UsdLuxLightListAPI provides.
62 /// UsdLuxLightListAPI::ComputeLightList() performs this traversal and returns
63 /// all lights in the scene:
64 ///
65 /// \code
66 /// 01 UsdLuxLightListAPI listAPI(stage->GetPseudoRoot());
67 /// 02 SdfPathVector lights = listAPI.ComputeLightList();
68 /// \endcode
69 ///
70 /// \section UsdLuxLightListAPI_LightList Publishing a Cached Light List
71 ///
72 /// Consider a USD client that needs to quickly discover lights but
73 /// wants to defer loading payloads and traversing the entire scene
74 /// where possible, and is willing to do up-front computation and
75 /// caching to achieve that.
76 ///
77 /// UsdLuxLightListAPI provides a way to cache the computed light list,
78 /// by publishing the list of lights onto prims in the model
79 /// hierarchy. Consider a big set that contains lights:
80 ///
81 /// \code
82 /// 01 def Xform "BigSetWithLights" (
83 /// 02 kind = "assembly"
84 /// 03 payload = @BigSetWithLights.usd@ // Heavy payload
85 /// 04 ) {
86 /// 05 // Pre-computed, cached list of lights inside payload
87 /// 06 rel lightList = [
88 /// 07 <./Lights/light_1>,
89 /// 08 <./Lights/light_2>,
90 /// 09 ...
91 /// 10 ]
92 /// 11 token lightList:cacheBehavior = "consumeAndContinue";
93 /// 12 }
94 /// \endcode
95 ///
96 /// The lightList relationship encodes a set of lights, and the
97 /// lightList:cacheBehavior property provides fine-grained
98 /// control over how to use that cache. (See details below.)
99 ///
100 /// The cache can be created by first invoking
101 /// ComputeLightList(ComputeModeIgnoreCache) to pre-compute the list
102 /// and then storing the result with UsdLuxLightListAPI::StoreLightList().
103 ///
104 /// To enable efficient retrieval of the cache, it should be stored
105 /// on a model hierarchy prim. Furthermore, note that while you can
106 /// use a UsdLuxLightListAPI bound to the pseudo-root prim to query the
107 /// lights (as in the example above) because it will perform a
108 /// traversal over descendants, you cannot store the cache back to the
109 /// pseduo-root prim.
110 ///
111 /// To consult the cached list, we invoke
112 /// ComputeLightList(ComputeModeConsultModelHierarchyCache):
113 ///
114 /// \code
115 /// 01 // Find and load all lights, using lightList cache where available
116 /// 02 UsdLuxLightListAPI list(stage->GetPseudoRoot());
117 /// 03 SdfPathSet lights = list.ComputeLightList(
118 /// 04 UsdLuxLightListAPI::ComputeModeConsultModelHierarchyCache);
119 /// 05 stage.LoadAndUnload(lights, SdfPathSet());
120 /// \endcode
121 ///
122 /// In this mode, ComputeLightList() will traverse the model
123 /// hierarchy, accumulating cached light lists.
124 ///
125 /// \section UsdLuxLightListAPI_CacheBehavior Controlling Cache Behavior
126 ///
127 /// The lightList:cacheBehavior property gives additional fine-grained
128 /// control over cache behavior:
129 ///
130 /// \li The fallback value, "ignore", indicates that the lightList should
131 /// be disregarded. This provides a way to invalidate cache entries.
132 /// Note that unless "ignore" is specified, a lightList with an empty
133 /// list of targets is considered a cache indicating that no lights
134 /// are present.
135 ///
136 /// \li The value "consumeAndContinue" indicates that the cache should
137 /// be consulted to contribute lights to the scene, and that recursion
138 /// should continue down the model hierarchy in case additional lights
139 /// are added as descedants. This is the default value established when
140 /// StoreLightList() is invoked. This behavior allows the lights within
141 /// a large model, such as the BigSetWithLights example above, to be
142 /// published outside the payload, while also allowing referencing and
143 /// layering to add additional lights over that set.
144 ///
145 /// \li The value "consumeAndHalt" provides a way to terminate recursive
146 /// traversal of the scene for light discovery. The cache will be
147 /// consulted but no descendant prims will be examined.
148 ///
149 /// \section UsdLuxLightListAPI_Instancing Instancing
150 ///
151 /// Where instances are present, UsdLuxLightListAPI::ComputeLightList() will
152 /// return the instance-unique paths to any lights discovered within
153 /// those instances. Lights within a UsdGeomPointInstancer will
154 /// not be returned, however, since they cannot be referred to
155 /// solely via paths.
156 ///
157 ///
158 /// For any described attribute \em Fallback \em Value or \em Allowed \em Values below
159 /// that are text/tokens, the actual token is published and defined in \ref UsdLuxTokens.
160 /// So to set an attribute to the value "rightHanded", use UsdLuxTokens->rightHanded
161 /// as the value.
162 ///
164 {
165 public:
166  /// Compile time constant representing what kind of schema this class is.
167  ///
168  /// \sa UsdSchemaKind
170 
171  /// Construct a UsdLuxLightListAPI on UsdPrim \p prim .
172  /// Equivalent to UsdLuxLightListAPI::Get(prim.GetStage(), prim.GetPath())
173  /// for a \em valid \p prim, but will not immediately throw an error for
174  /// an invalid \p prim
175  explicit UsdLuxLightListAPI(const UsdPrim& prim=UsdPrim())
176  : UsdAPISchemaBase(prim)
177  {
178  }
179 
180  /// Construct a UsdLuxLightListAPI on the prim held by \p schemaObj .
181  /// Should be preferred over UsdLuxLightListAPI(schemaObj.GetPrim()),
182  /// as it preserves SchemaBase state.
183  explicit UsdLuxLightListAPI(const UsdSchemaBase& schemaObj)
184  : UsdAPISchemaBase(schemaObj)
185  {
186  }
187 
188  /// Destructor.
189  USDLUX_API
190  virtual ~UsdLuxLightListAPI();
191 
192  /// Return a vector of names of all pre-declared attributes for this schema
193  /// class and all its ancestor classes. Does not include attributes that
194  /// may be authored by custom/extended methods of the schemas involved.
195  USDLUX_API
196  static const TfTokenVector &
197  GetSchemaAttributeNames(bool includeInherited=true);
198 
199  /// Return a UsdLuxLightListAPI holding the prim adhering to this
200  /// schema at \p path on \p stage. If no prim exists at \p path on
201  /// \p stage, or if the prim at that path does not adhere to this schema,
202  /// return an invalid schema object. This is shorthand for the following:
203  ///
204  /// \code
205  /// UsdLuxLightListAPI(stage->GetPrimAtPath(path));
206  /// \endcode
207  ///
208  USDLUX_API
209  static UsdLuxLightListAPI
210  Get(const UsdStagePtr &stage, const SdfPath &path);
211 
212 
213  /// Returns true if this <b>single-apply</b> API schema can be applied to
214  /// the given \p prim. If this schema can not be a applied to the prim,
215  /// this returns false and, if provided, populates \p whyNot with the
216  /// reason it can not be applied.
217  ///
218  /// Note that if CanApply returns false, that does not necessarily imply
219  /// that calling Apply will fail. Callers are expected to call CanApply
220  /// before calling Apply if they want to ensure that it is valid to
221  /// apply a schema.
222  ///
223  /// \sa UsdPrim::GetAppliedSchemas()
224  /// \sa UsdPrim::HasAPI()
225  /// \sa UsdPrim::CanApplyAPI()
226  /// \sa UsdPrim::ApplyAPI()
227  /// \sa UsdPrim::RemoveAPI()
228  ///
229  USDLUX_API
230  static bool
231  CanApply(const UsdPrim &prim, std::string *whyNot=nullptr);
232 
233  /// Applies this <b>single-apply</b> API schema to the given \p prim.
234  /// This information is stored by adding "LightListAPI" to the
235  /// token-valued, listOp metadata \em apiSchemas on the prim.
236  ///
237  /// \return A valid UsdLuxLightListAPI object is returned upon success.
238  /// An invalid (or empty) UsdLuxLightListAPI object is returned upon
239  /// failure. See \ref UsdPrim::ApplyAPI() for conditions
240  /// resulting in failure.
241  ///
242  /// \sa UsdPrim::GetAppliedSchemas()
243  /// \sa UsdPrim::HasAPI()
244  /// \sa UsdPrim::CanApplyAPI()
245  /// \sa UsdPrim::ApplyAPI()
246  /// \sa UsdPrim::RemoveAPI()
247  ///
248  USDLUX_API
249  static UsdLuxLightListAPI
250  Apply(const UsdPrim &prim);
251 
252 protected:
253  /// Returns the kind of schema this class belongs to.
254  ///
255  /// \sa UsdSchemaKind
256  USDLUX_API
257  UsdSchemaKind _GetSchemaKind() const override;
258 
259 private:
260  // needs to invoke _GetStaticTfType.
261  friend class UsdSchemaRegistry;
262  USDLUX_API
263  static const TfType &_GetStaticTfType();
264 
265  static bool _IsTypedSchema();
266 
267  // override SchemaBase virtuals.
268  USDLUX_API
269  const TfType &_GetTfType() const override;
270 
271 public:
272  // --------------------------------------------------------------------- //
273  // LIGHTLISTCACHEBEHAVIOR
274  // --------------------------------------------------------------------- //
275  ///
276  /// Controls how the lightList should be interpreted.
277  /// Valid values are:
278  /// - consumeAndHalt: The lightList should be consulted,
279  /// and if it exists, treated as a final authoritative statement
280  /// of any lights that exist at or below this prim, halting
281  /// recursive discovery of lights.
282  /// - consumeAndContinue: The lightList should be consulted,
283  /// but recursive traversal over nameChildren should continue
284  /// in case additional lights are added by descendants.
285  /// - ignore: The lightList should be entirely ignored. This
286  /// provides a simple way to temporarily invalidate an existing
287  /// cache. This is the fallback behavior.
288  ///
289  ///
290  /// | ||
291  /// | -- | -- |
292  /// | Declaration | `token lightList:cacheBehavior` |
293  /// | C++ Type | TfToken |
294  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
295  /// | \ref UsdLuxTokens "Allowed Values" | consumeAndHalt, consumeAndContinue, ignore |
296  USDLUX_API
298 
299  /// See GetLightListCacheBehaviorAttr(), and also
300  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
301  /// If specified, author \p defaultValue as the attribute's default,
302  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
303  /// the default for \p writeSparsely is \c false.
304  USDLUX_API
305  UsdAttribute CreateLightListCacheBehaviorAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
306 
307 public:
308  // --------------------------------------------------------------------- //
309  // LIGHTLIST
310  // --------------------------------------------------------------------- //
311  /// Relationship to lights in the scene.
312  ///
313  USDLUX_API
315 
316  /// See GetLightListRel(), and also
317  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create
318  USDLUX_API
320 
321 public:
322  // ===================================================================== //
323  // Feel free to add custom code below this line, it will be preserved by
324  // the code generator.
325  //
326  // Just remember to:
327  // - Close the class declaration with };
328  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
329  // - Close the include guard with #endif
330  // ===================================================================== //
331  // --(BEGIN CUSTOM CODE)--
332 
333  /// Runtime control over whether to consult stored lightList caches.
334  enum ComputeMode {
335  /// Consult any caches found on the model hierarchy.
336  /// Do not traverse beneath the model hierarchy.
338  /// Ignore any caches found, and do a full prim traversal.
340  };
341 
342  /// Computes and returns the list of lights and light filters in
343  /// the stage, optionally consulting a cached result.
344  ///
345  /// In ComputeModeIgnoreCache mode, caching is ignored, and this
346  /// does a prim traversal looking for prims that have a UsdLuxLightAPI
347  /// or are of type UsdLuxLightFilter.
348  ///
349  /// In ComputeModeConsultModelHierarchyCache, this does a traversal
350  /// only of the model hierarchy. In this traversal, any lights that
351  /// live as model hierarchy prims are accumulated, as well as any
352  /// paths stored in lightList caches. The lightList:cacheBehavior
353  /// attribute gives further control over the cache behavior; see the
354  /// class overview for details.
355  ///
356  /// When instances are present, ComputeLightList(ComputeModeIgnoreCache)
357  /// will return the instance-uniqiue paths to any lights discovered
358  /// within those instances. Lights within a UsdGeomPointInstancer
359  /// will not be returned, however, since they cannot be referred to
360  /// solely via paths.
361  USDLUX_API
363 
364  /// Store the given paths as the lightlist for this prim.
365  /// Paths that do not have this prim's path as a prefix
366  /// will be silently ignored.
367  /// This will set the listList:cacheBehavior to "consumeAndContinue".
368  USDLUX_API
369  void StoreLightList(const SdfPathSet &) const;
370 
371  /// Mark any stored lightlist as invalid, by setting the
372  /// lightList:cacheBehavior attribute to ignore.
373  USDLUX_API
374  void InvalidateLightList() const;
375 };
376 
378 
379 #endif
USDLUX_API UsdAttribute CreateLightListCacheBehaviorAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
Single Apply API schema.
USDLUX_API UsdAttribute GetLightListCacheBehaviorAttr() const
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
UsdLuxLightListAPI(const UsdSchemaBase &schemaObj)
Definition: lightListAPI.h:183
#define USDLUX_API
Definition: api.h:23
Ignore any caches found, and do a full prim traversal.
Definition: lightListAPI.h:339
USDLUX_API UsdRelationship GetLightListRel() const
ComputeMode
Runtime control over whether to consult stored lightList caches.
Definition: lightListAPI.h:334
USDLUX_API void InvalidateLightList() const
UsdLuxLightListAPI(const UsdPrim &prim=UsdPrim())
Definition: lightListAPI.h:175
USDLUX_API UsdSchemaKind _GetSchemaKind() const override
static USDLUX_API bool CanApply(const UsdPrim &prim, std::string *whyNot=nullptr)
Definition: prim.h:116
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:440
static USDLUX_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
Definition: path.h:273
static USDLUX_API UsdLuxLightListAPI Get(const UsdStagePtr &stage, const SdfPath &path)
GLenum mode
Definition: glcorearb.h:99
std::set< class SdfPath > SdfPathSet
A set of SdfPaths.
Definition: path.h:192
UsdSchemaKind
Definition: common.h:112
USDLUX_API UsdRelationship CreateLightListRel() const
USDLUX_API SdfPathSet ComputeLightList(ComputeMode mode) const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
USDLUX_API void StoreLightList(const SdfPathSet &) const
virtual USDLUX_API ~UsdLuxLightListAPI()
Destructor.
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
Definition: type.h:47
static USDLUX_API UsdLuxLightListAPI Apply(const UsdPrim &prim)
static const UsdSchemaKind schemaKind
Definition: lightListAPI.h:169
Definition: value.h:146