HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
shaderProperty.h
Go to the documentation of this file.
1 //
2 // Copyright 2018 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 
25 #ifndef PXR_USD_SDR_SHADER_PROPERTY_H
26 #define PXR_USD_SDR_SHADER_PROPERTY_H
27 
28 /// \file sdr/shaderProperty.h
29 
30 #include "pxr/pxr.h"
31 #include "pxr/usd/sdr/api.h"
33 #include "pxr/base/tf/token.h"
34 #include "pxr/base/tf/weakBase.h"
35 #include "pxr/base/vt/value.h"
36 #include "pxr/usd/ndr/property.h"
37 #include "pxr/usd/sdr/shaderNode.h"
38 
40 
41 // If additional types are added here, it's also worth trying to add a mapping
42 // to the equivalent Sdf type in the implementation file.
43 #define SDR_PROPERTY_TYPE_TOKENS \
44  ((Int, "int")) \
45  ((String, "string")) \
46  ((Float, "float")) \
47  ((Color, "color")) \
48  ((Point, "point")) \
49  ((Normal, "normal")) \
50  ((Vector, "vector")) \
51  ((Matrix, "matrix")) \
52  ((Struct, "struct")) \
53  ((Terminal, "terminal")) \
54  ((Vstruct, "vstruct")) \
55  ((Unknown, "unknown"))
56 
57 // Note: Metadata keys that are generated by parsers should start with
58 // "__SDR__" to reduce the risk of collision with metadata actually in the
59 // shader.
60 #define SDR_PROPERTY_METADATA_TOKENS \
61  ((Label, "label")) \
62  ((Help, "help")) \
63  ((Page, "page")) \
64  ((RenderType, "renderType")) \
65  ((Role, "role")) \
66  ((Widget, "widget")) \
67  ((Hints, "hints")) \
68  ((Options, "options")) \
69  ((IsDynamicArray, "isDynamicArray")) \
70  ((Connectable, "connectable")) \
71  ((ValidConnectionTypes, "validConnectionTypes")) \
72  ((VstructMemberOf, "vstructMemberOf")) \
73  ((VstructMemberName, "vstructMemberName")) \
74  ((VstructConditionalExpr, "vstructConditionalExpr"))\
75  ((IsAssetIdentifier, "__SDR__isAssetIdentifier"))\
76  ((ImplementationName, "__SDR__implementationName"))\
77  ((DefaultInput, "__SDR__defaultinput")) \
78  ((Target, "__SDR__target")) \
79  ((Colorspace, "__SDR__colorspace"))
80 
81 
82 // The following tokens are valid values for the metadata "role"
83 #define SDR_PROPERTY_ROLE_TOKENS \
84  ((None, "none"))
85 
87 TF_DECLARE_PUBLIC_TOKENS(SdrPropertyMetadata, SDR_API,
89 TF_DECLARE_PUBLIC_TOKENS(SdrPropertyRole, SDR_API,
91 
92 /// \class SdrShaderProperty
93 ///
94 /// A specialized version of `NdrProperty` which holds shading information.
95 ///
97 {
98 public:
99  // Constructor.
100  SDR_API
102  const TfToken& name,
103  const TfToken& type,
104  const VtValue& defaultValue,
105  bool isOutput,
106  size_t arraySize,
107  const NdrTokenMap& metadata,
108  const NdrTokenMap& hints,
109  const NdrOptionVec& options
110  );
111 
112  /// \name Metadata
113  /// The metadata returned here is a direct result of what the parser plugin
114  /// is able to determine about the property. See the documentation for a
115  /// specific parser plugin to get help on what the parser is looking for to
116  /// populate these values.
117  /// @{
118 
119  /// The label assigned to this property, if any. Distinct from the name
120  /// returned from `GetName()`. In the context of a UI, the label value
121  /// might be used as the display name for the property instead of the name.
122  SDR_API
123  const TfToken& GetLabel() const { return _label; }
124 
125  /// The help message assigned to this property, if any.
126  SDR_API
127  std::string GetHelp() const;
128 
129  /// The page (group), eg "Advanced", this property appears on, if any.
130  SDR_API
131  const TfToken& GetPage() const { return _page; }
132 
133  /// The widget "hint" that indicates the widget that can best display the
134  /// type of data contained in this property, if any. Examples of this value
135  /// could include "number", "slider", etc.
136  SDR_API
137  const TfToken& GetWidget() const { return _widget; }
138 
139  /// Any UI "hints" that are associated with this property. "Hints" are
140  /// simple key/value pairs.
141  SDR_API
142  const NdrTokenMap& GetHints() const { return _hints; }
143 
144  /// If the property has a set of valid values that are pre-determined, this
145  /// will return the valid option names and corresponding string values (if
146  /// the option was specified with a value).
147  SDR_API
148  const NdrOptionVec& GetOptions() const { return _options; }
149 
150  /// Returns the implementation name of this property. The name of the
151  /// property is how to refer to the property in shader networks. The
152  /// label is how to present this property to users. The implementation
153  /// name is the name of the parameter this property represents in the
154  /// implementation. Any client using the implementation \b must call
155  /// this method to get the correct name; using \c getName() is not
156  /// correct.
157  SDR_API
159 
160  /// @}
161 
162 
163  /// \name VStruct Information
164  /// @{
165 
166  /// If this field is part of a vstruct, this is the name of the struct.
167  SDR_API
168  const TfToken& GetVStructMemberOf() const {
169  return _vstructMemberOf;
170  }
171 
172  /// If this field is part of a vstruct, this is its name in the struct.
173  SDR_API
174  const TfToken& GetVStructMemberName() const {
175  return _vstructMemberName;
176  }
177 
178  /// Returns true if this field is part of a vstruct.
179  SDR_API
180  bool IsVStructMember() const;
181 
182  /// Returns true if the field is the head of a vstruct.
183  SDR_API
184  bool IsVStruct() const;
185 
186 
187  /// If this field is part of a vstruct, this is the conditional expression
188  SDR_API
191  }
192 
193  /// @}
194 
195 
196  /// \name Connection Information
197  /// @{
198 
199  /// Whether this property can be connected to other properties. If this
200  /// returns `true`, connectability to a specific property can be tested via
201  /// `CanConnectTo()`.
202  SDR_API
203  bool IsConnectable() const override { return _isConnectable; }
204 
205  /// Gets the list of valid connection types for this property. This value
206  /// comes from shader metadata, and may not be specified. The value from
207  /// `NdrProperty::GetType()` can be used as a fallback, or you can use the
208  /// connectability test in `CanConnectTo()`.
209  SDR_API
211  return _validConnectionTypes;
212  }
213 
214  /// Determines if this property can be connected to the specified property.
215  SDR_API
216  bool CanConnectTo(const NdrProperty& other) const override;
217 
218  /// @}
219 
220 
221  /// \name Utilities
222  /// @{
223 
224  /// Converts the property's type from `GetType()` into a `SdfValueTypeName`.
225  ///
226  /// Two scenarios can result: an exact mapping from property type to Sdf
227  /// type, and an inexact mapping. In the first scenario, the first element
228  /// in the pair will be the cleanly-mapped Sdf type, and the second element,
229  /// a TfToken, will be empty. In the second scenario, the Sdf type will be
230  /// set to `Token` to indicate an unclean mapping, and the second element
231  /// will be set to the original type returned by `GetType()`.
232  SDR_API
233  const NdrSdfTypeIndicator GetTypeAsSdfType() const override;
234 
235  /// Determines if the value held by this property is an asset identifier
236  /// (eg, a file path); the logic for this is left up to the parser.
237  ///
238  /// Note: The type returned from `GetTypeAsSdfType()` will be `Asset` if
239  /// this method returns `true` (even though its true underlying data type
240  /// is string).
241  SDR_API
242  bool IsAssetIdentifier() const;
243 
244  /// Determines if the value held by this property is the default input
245  /// for this node.
246  SDR_API
247  bool IsDefaultInput() const;
248 
249  /// @}
250 
251 protected:
252  SdrShaderProperty& operator=(const SdrShaderProperty&) = delete;
253 
254  // Allow the shader's post process function to access the property's
255  // internals. Some property information can only be determined after parse
256  // time.
257  friend void SdrShaderNode::_PostProcessProperties();
258 
259  // Some metadata values cannot be returned by reference from the main
260  // metadata dictionary because they need additional parsing.
263 
264  // Tokenized metadata
272 };
273 
275 
276 #endif // PXR_USD_SDR_SHADER_PROPERTY_H
SDR_API const TfToken & GetLabel() const
bool _isConnectable
Definition: property.h:172
SDR_API const TfToken & GetPage() const
The page (group), eg "Advanced", this property appears on, if any.
std::vector< TfToken > NdrTokenVec
Definition: declare.h:59
const NdrTokenMap _hints
std::vector< NdrOption > NdrOptionVec
Definition: declare.h:81
SDR_API bool CanConnectTo(const NdrProperty &other) const override
Determines if this property can be connected to the specified property.
NdrTokenVec _validConnectionTypes
GLuint const GLchar * name
Definition: glcorearb.h:785
SDR_API SdrShaderProperty(const TfToken &name, const TfToken &type, const VtValue &defaultValue, bool isOutput, size_t arraySize, const NdrTokenMap &metadata, const NdrTokenMap &hints, const NdrOptionVec &options)
SDR_API const NdrTokenVec & GetValidConnectionTypes() const
TfToken _vstructMemberName
#define SDR_PROPERTY_TYPE_TOKENS
SDR_API const TfToken & GetVStructMemberOf() const
If this field is part of a vstruct, this is the name of the struct.
SDR_API const TfToken & GetVStructConditionalExpr() const
If this field is part of a vstruct, this is the conditional expression.
std::pair< SdfValueTypeName, TfToken > NdrSdfTypeIndicator
Definition: declare.h:83
SDR_API const TfToken & GetWidget() const
Definition: token.h:87
GLint GLint GLsizei GLint GLenum GLenum type
Definition: glcorearb.h:107
SDR_API const TfToken & GetVStructMemberName() const
If this field is part of a vstruct, this is its name in the struct.
GLsizei const GLchar *const * string
Definition: glcorearb.h:813
#define SDR_PROPERTY_ROLE_TOKENS
SDR_API const NdrTokenMap & GetHints() const
SDR_API std::string GetImplementationName() const
SDR_API const NdrSdfTypeIndicator GetTypeAsSdfType() const override
SDR_API bool IsDefaultInput() const
SDR_API bool IsAssetIdentifier() const
const NdrOptionVec _options
#define SDR_PROPERTY_METADATA_TOKENS
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1375
SdrShaderProperty & operator=(const SdrShaderProperty &)=delete
SDR_API bool IsConnectable() const override
TF_DECLARE_PUBLIC_TOKENS(SdrPropertyTypes, SDR_API, SDR_PROPERTY_TYPE_TOKENS)
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
SDR_API bool IsVStructMember() const
Returns true if this field is part of a vstruct.
std::unordered_map< TfToken, std::string, TfToken::HashFunctor > NdrTokenMap
Definition: declare.h:61
TfToken _vstructConditionalExpr
SDR_API std::string GetHelp() const
The help message assigned to this property, if any.
SDR_API bool IsVStruct() const
Returns true if the field is the head of a vstruct.
#define SDR_API
Definition: api.h:40
Definition: value.h:168
SDR_API const NdrOptionVec & GetOptions() const