HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
lightFilter.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_LIGHTFILTER_H
25 #define USDLUX_GENERATED_LIGHTFILTER_H
26 
27 /// \file usdLux/lightFilter.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 
37 #include "pxr/usd/usdShade/input.h"
38 #include "pxr/usd/usdShade/output.h"
39 
40 #include "pxr/base/vt/value.h"
41 
42 #include "pxr/base/gf/vec3d.h"
43 #include "pxr/base/gf/vec3f.h"
44 #include "pxr/base/gf/matrix4d.h"
45 
46 #include "pxr/base/tf/token.h"
47 #include "pxr/base/tf/type.h"
48 
50 
51 class SdfAssetPath;
52 
53 // -------------------------------------------------------------------------- //
54 // LIGHTFILTER //
55 // -------------------------------------------------------------------------- //
56 
57 /// \class UsdLuxLightFilter
58 ///
59 /// A light filter modifies the effect of a light.
60 /// Lights refer to filters via relationships so that filters may be
61 /// shared.
62 ///
63 /// <b>Linking</b>
64 ///
65 /// Filters can be linked to geometry. Linking controls which geometry
66 /// a light-filter affects, when considering the light filters attached
67 /// to a light illuminating the geometry.
68 ///
69 /// Linking is specified as a collection (UsdCollectionAPI) which can
70 /// be accessed via GetFilterLinkCollection().
71 ///
72 ///
73 /// For any described attribute \em Fallback \em Value or \em Allowed \em Values below
74 /// that are text/tokens, the actual token is published and defined in \ref UsdLuxTokens.
75 /// So to set an attribute to the value "rightHanded", use UsdLuxTokens->rightHanded
76 /// as the value.
77 ///
79 {
80 public:
81  /// Compile time constant representing what kind of schema this class is.
82  ///
83  /// \sa UsdSchemaKind
85 
86  /// Construct a UsdLuxLightFilter on UsdPrim \p prim .
87  /// Equivalent to UsdLuxLightFilter::Get(prim.GetStage(), prim.GetPath())
88  /// for a \em valid \p prim, but will not immediately throw an error for
89  /// an invalid \p prim
90  explicit UsdLuxLightFilter(const UsdPrim& prim=UsdPrim())
91  : UsdGeomXformable(prim)
92  {
93  }
94 
95  /// Construct a UsdLuxLightFilter on the prim held by \p schemaObj .
96  /// Should be preferred over UsdLuxLightFilter(schemaObj.GetPrim()),
97  /// as it preserves SchemaBase state.
98  explicit UsdLuxLightFilter(const UsdSchemaBase& schemaObj)
99  : UsdGeomXformable(schemaObj)
100  {
101  }
102 
103  /// Destructor.
104  USDLUX_API
105  virtual ~UsdLuxLightFilter();
106 
107  /// Return a vector of names of all pre-declared attributes for this schema
108  /// class and all its ancestor classes. Does not include attributes that
109  /// may be authored by custom/extended methods of the schemas involved.
110  USDLUX_API
111  static const TfTokenVector &
112  GetSchemaAttributeNames(bool includeInherited=true);
113 
114  /// Return a UsdLuxLightFilter holding the prim adhering to this
115  /// schema at \p path on \p stage. If no prim exists at \p path on
116  /// \p stage, or if the prim at that path does not adhere to this schema,
117  /// return an invalid schema object. This is shorthand for the following:
118  ///
119  /// \code
120  /// UsdLuxLightFilter(stage->GetPrimAtPath(path));
121  /// \endcode
122  ///
123  USDLUX_API
124  static UsdLuxLightFilter
125  Get(const UsdStagePtr &stage, const SdfPath &path);
126 
127  /// Attempt to ensure a \a UsdPrim adhering to this schema at \p path
128  /// is defined (according to UsdPrim::IsDefined()) on this stage.
129  ///
130  /// If a prim adhering to this schema at \p path is already defined on this
131  /// stage, return that prim. Otherwise author an \a SdfPrimSpec with
132  /// \a specifier == \a SdfSpecifierDef and this schema's prim type name for
133  /// the prim at \p path at the current EditTarget. Author \a SdfPrimSpec s
134  /// with \p specifier == \a SdfSpecifierDef and empty typeName at the
135  /// current EditTarget for any nonexistent, or existing but not \a Defined
136  /// ancestors.
137  ///
138  /// The given \a path must be an absolute prim path that does not contain
139  /// any variant selections.
140  ///
141  /// If it is impossible to author any of the necessary PrimSpecs, (for
142  /// example, in case \a path cannot map to the current UsdEditTarget's
143  /// namespace) issue an error and return an invalid \a UsdPrim.
144  ///
145  /// Note that this method may return a defined prim whose typeName does not
146  /// specify this schema class, in case a stronger typeName opinion overrides
147  /// the opinion at the current EditTarget.
148  ///
149  USDLUX_API
150  static UsdLuxLightFilter
151  Define(const UsdStagePtr &stage, const SdfPath &path);
152 
153 protected:
154  /// Returns the kind of schema this class belongs to.
155  ///
156  /// \sa UsdSchemaKind
157  USDLUX_API
158  UsdSchemaKind _GetSchemaKind() const override;
159 
160 private:
161  // needs to invoke _GetStaticTfType.
162  friend class UsdSchemaRegistry;
163  USDLUX_API
164  static const TfType &_GetStaticTfType();
165 
166  static bool _IsTypedSchema();
167 
168  // override SchemaBase virtuals.
169  USDLUX_API
170  const TfType &_GetTfType() const override;
171 
172 public:
173  // --------------------------------------------------------------------- //
174  // SHADERID
175  // --------------------------------------------------------------------- //
176  /// Default ID for the light filter's shader.
177  /// This defines the shader ID for this light filter when a render context
178  /// specific shader ID is not available.
179  ///
180  /// \see GetShaderId
181  /// \see GetShaderIdAttrForRenderContext
182  /// \see SdrRegistry::GetShaderNodeByIdentifier
183  /// \see SdrRegistry::GetShaderNodeByIdentifierAndType
184  ///
185  ///
186  /// | ||
187  /// | -- | -- |
188  /// | Declaration | `uniform token lightFilter:shaderId = ""` |
189  /// | C++ Type | TfToken |
190  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
191  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
192  USDLUX_API
194 
195  /// See GetShaderIdAttr(), and also
196  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
197  /// If specified, author \p defaultValue as the attribute's default,
198  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
199  /// the default for \p writeSparsely is \c false.
200  USDLUX_API
201  UsdAttribute CreateShaderIdAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
202 
203 public:
204  // ===================================================================== //
205  // Feel free to add custom code below this line, it will be preserved by
206  // the code generator.
207  //
208  // Just remember to:
209  // - Close the class declaration with };
210  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
211  // - Close the include guard with #endif
212  // ===================================================================== //
213  // --(BEGIN CUSTOM CODE)--
214 
215  // -------------------------------------------------------------------------
216  /// \name Conversion to and from UsdShadeConnectableAPI
217  ///
218  /// @{
219 
220  /// Constructor that takes a ConnectableAPI object.
221  /// Allow implicit conversion of UsdShadeConnectableAPI to
222  /// UsdLuxLightFilter.
223  USDLUX_API
224  UsdLuxLightFilter(const UsdShadeConnectableAPI &connectable);
225 
226  /// Contructs and returns a UsdShadeConnectableAPI object with this light
227  /// filter.
228  ///
229  /// Note that most tasks can be accomplished without explicitly constructing
230  /// a UsdShadeConnectable API, since connection-related API such as
231  /// UsdShadeConnectableAPI::ConnectToSource() are static methods, and
232  /// UsdLuxLightFilter will auto-convert to a UsdShadeConnectableAPI when
233  /// passed to functions that want to act generically on a connectable
234  /// UsdShadeConnectableAPI object.
235  USDLUX_API
237 
238  /// @}
239 
240  // -------------------------------------------------------------------------
241  /// \name Outputs API
242  ///
243  /// Outputs represent a typed attribute on a light filter whose value is
244  /// computed externally.
245  ///
246  /// @{
247 
248  /// Create an output which can either have a value or can be connected.
249  /// The attribute representing the output is created in the "outputs:"
250  /// namespace. Outputs on a light filter cannot be connected, as their
251  /// value is assumed to be computed externally.
252  ///
253  USDLUX_API
255  const SdfValueTypeName& typeName);
256 
257  /// Return the requested output if it exists.
258  ///
259  USDLUX_API
260  UsdShadeOutput GetOutput(const TfToken &name) const;
261 
262  /// Outputs are represented by attributes in the "outputs:" namespace.
263  /// If \p onlyAuthored is true (the default), then only return authored
264  /// attributes; otherwise, this also returns un-authored builtins.
265  ///
266  USDLUX_API
267  std::vector<UsdShadeOutput> GetOutputs(bool onlyAuthored=true) const;
268 
269  /// @}
270 
271  // -------------------------------------------------------------------------
272 
273  /// \name Inputs API
274  ///
275  /// Inputs are connectable attribute with a typed value.
276  ///
277  /// Light filter parameters are encoded as inputs.
278  ///
279  /// @{
280 
281  /// Create an input which can either have a value or can be connected.
282  /// The attribute representing the input is created in the "inputs:"
283  /// namespace. Inputs on light filters are connectable.
284  ///
285  USDLUX_API
287  const SdfValueTypeName& typeName);
288 
289  /// Return the requested input if it exists.
290  ///
291  USDLUX_API
292  UsdShadeInput GetInput(const TfToken &name) const;
293 
294  /// Inputs are represented by attributes in the "inputs:" namespace.
295  /// If \p onlyAuthored is true (the default), then only return authored
296  /// attributes; otherwise, this also returns un-authored builtins.
297  ///
298  USDLUX_API
299  std::vector<UsdShadeInput> GetInputs(bool onlyAuthored=true) const;
300 
301  /// @}
302 
303  /// Return the UsdCollectionAPI interface used for examining and
304  /// modifying the filter-linking of this light filter. Linking
305  /// controls which geometry this light filter affects.
306  USDLUX_API
308 
309  /// Returns the shader ID attribute for the given \p renderContext.
310  ///
311  /// If \p renderContext is non-empty, this will try to return an attribute
312  /// named _lightFilter:shaderId_ with the namespace prefix \p renderContext.
313  /// For example, if the passed in render context is "ri" then the attribute
314  /// returned by this function would have the following signature:
315  /// | ||
316  /// | -- | -- |
317  /// | Declaration | `token ri:lightFilter:shaderId` |
318  /// | C++ Type | TfToken |
319  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
320  ///
321  /// If the render context is empty, this will return the default shader ID
322  /// attribute as returned by GetShaderIdAttr().
323  USDLUX_API
325  const TfToken &renderContext) const;
326 
327  /// Creates the shader ID attribute for the given \p renderContext.
328  ///
329  /// See GetShaderIdAttrForRenderContext(), and also
330  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
331  /// If specified, author \p defaultValue as the attribute's default,
332  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
333  /// the default for \p writeSparsely is \c false.
334  USDLUX_API
336  const TfToken &renderContext,
337  VtValue const &defaultValue = VtValue(),
338  bool writeSparsely=false) const;
339 
340  /// Return the light filter's shader ID for the given list of available
341  /// \p renderContexts.
342  ///
343  /// The shader ID returned by this function is the identifier to use when
344  /// looking up the shader definition for this light filter in the
345  /// \ref SdrRegistry "shader registry".
346  ///
347  /// The render contexts are expected to be listed in priority order, so
348  /// for each render context provided, this will try to find the shader ID
349  /// attribute specific to that render context (see
350  /// GetShaderIdAttrForRenderContext()) and will return the
351  /// value of the first one found that has a non-empty value. If no shader ID
352  /// value can be found for any of the given render contexts or
353  /// \p renderContexts is empty, then this will return the value of the
354  /// default shader ID attribute (see GetShaderIdAttr()).
355  USDLUX_API
356  TfToken GetShaderId(const TfTokenVector &renderContexts) const;
357 
358 };
359 
361 
362 #endif
USDLUX_API TfToken GetShaderId(const TfTokenVector &renderContexts) const
USDLUX_API UsdShadeOutput CreateOutput(const TfToken &name, const SdfValueTypeName &typeName)
static USDLUX_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
USDLUX_API UsdShadeConnectableAPI ConnectableAPI() const
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
#define USDLUX_API
Definition: api.h:40
static USDLUX_API UsdLuxLightFilter Define(const UsdStagePtr &stage, const SdfPath &path)
Definition: token.h:87
UsdLuxLightFilter(const UsdPrim &prim=UsdPrim())
Definition: lightFilter.h:90
Represents a concrete typed schema.
static const UsdSchemaKind schemaKind
Definition: lightFilter.h:84
USDLUX_API UsdAttribute CreateShaderIdAttrForRenderContext(const TfToken &renderContext, VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
virtual USDLUX_API ~UsdLuxLightFilter()
Destructor.
Definition: prim.h:135
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:442
GLuint const GLchar * name
Definition: glcorearb.h:786
Definition: path.h:291
USDLUX_API UsdShadeInput CreateInput(const TfToken &name, const SdfValueTypeName &typeName)
UsdSchemaKind
Definition: common.h:127
USDLUX_API UsdCollectionAPI GetFilterLinkCollectionAPI() const
USDLUX_API std::vector< UsdShadeOutput > GetOutputs(bool onlyAuthored=true) const
USDLUX_API UsdShadeInput GetInput(const TfToken &name) const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1441
USDLUX_API UsdAttribute GetShaderIdAttr() const
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
USDLUX_API UsdAttribute GetShaderIdAttrForRenderContext(const TfToken &renderContext) const
USDLUX_API UsdSchemaKind _GetSchemaKind() const override
Definition: type.h:64
USDLUX_API UsdShadeOutput GetOutput(const TfToken &name) const
UsdLuxLightFilter(const UsdSchemaBase &schemaObj)
Definition: lightFilter.h:98
USDLUX_API UsdAttribute CreateShaderIdAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
Definition: value.h:167
USDLUX_API std::vector< UsdShadeInput > GetInputs(bool onlyAuthored=true) const
static USDLUX_API UsdLuxLightFilter Get(const UsdStagePtr &stage, const SdfPath &path)