HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Syntax.h
Go to the documentation of this file.
1 //
2 // Copyright Contributors to the MaterialX Project
3 // SPDX-License-Identifier: Apache-2.0
4 //
5 
6 #ifndef MATERIALX_SYNTAX_H
7 #define MATERIALX_SYNTAX_H
8 
9 /// @file
10 /// Base class for syntax handling for shader generators
11 
13 
15 #include <MaterialXCore/Library.h>
16 #include <MaterialXCore/Value.h>
17 
19 
20 class Syntax;
21 class TypeSyntax;
22 class TypeDesc;
23 class ShaderPort;
24 
25 /// Shared pointer to a Syntax
26 using SyntaxPtr = shared_ptr<Syntax>;
27 /// Shared pointer to a constant Syntax
28 using ConstSyntaxPtr = shared_ptr<const Syntax>;
29 /// Shared pointer to a TypeSyntax
30 using TypeSyntaxPtr = shared_ptr<TypeSyntax>;
31 
32 /// Map holding identifier names and a counter for
33 /// creating unique names from them.
34 using IdentifierMap = std::unordered_map<string, size_t>;
35 
36 /// @class Syntax
37 /// Base class for syntax objects used by shader generators
38 /// to emit code with correct syntax for each language.
40 {
41  public:
42  /// Punctuation types
44  {
48  DOUBLE_SQUARE_BRACKETS
49  };
50 
51  public:
52  virtual ~Syntax() { }
53 
54  /// Register syntax handling for a data type.
55  /// Required to be set for all supported data types.
56  void registerTypeSyntax(const TypeDesc* type, TypeSyntaxPtr syntax);
57 
58  /// Register names that are reserved words not to be used by a code generator when naming
59  /// variables and functions. Keywords, types, built-in functions etc. should be
60  /// added to this set. Multiple calls will add to the internal set of names.
61  void registerReservedWords(const StringSet& names);
62 
63  /// Register a set string replacements for disallowed tokens
64  /// for a code generator when naming variables and functions.
65  /// Multiple calls will add to the internal set of tokens.
66  void registerInvalidTokens(const StringMap& tokens);
67 
68  /// Returns a set of names that are reserved words for this language syntax.
69  const StringSet& getReservedWords() const { return _reservedWords; }
70 
71  /// Returns a mapping from disallowed tokens to replacement strings for this language syntax.
72  const StringMap& getInvalidTokens() const { return _invalidTokens; }
73 
74  /// Returns the type syntax object for a named type.
75  /// Throws an exception if a type syntax is not defined for the given type.
76  const TypeSyntax& getTypeSyntax(const TypeDesc* type) const;
77 
78  /// Returns an array of all registered type syntax objects
79  const vector<TypeSyntaxPtr>& getTypeSyntaxes() const { return _typeSyntaxes; }
80 
81  /// Returns a type description given a type syntax. Throws an exception
82  /// if the type syntax has not been registered
83  const TypeDesc* getTypeDescription(const TypeSyntaxPtr& typeSyntax) const;
84 
85  /// Returns the name syntax of the given type
86  const string& getTypeName(const TypeDesc* type) const;
87 
88  /// Returns the type name in an output context
89  virtual string getOutputTypeName(const TypeDesc* type) const;
90 
91  /// Returns a type alias for the given data type.
92  /// If not used returns an empty string.
93  const string& getTypeAlias(const TypeDesc* type) const;
94 
95  /// Returns a custom type definition if needed for the given data type.
96  /// If not used returns an empty string.
97  const string& getTypeDefinition(const TypeDesc* type) const;
98 
99  /// Returns the default value string for the given type
100  const string& getDefaultValue(const TypeDesc* type, bool uniform = false) const;
101 
102  /// Returns the value string for a given type and value object
103  virtual string getValue(const TypeDesc* type, const Value& value, bool uniform = false) const;
104 
105  /// Returns the value string for a given shader port object
106  virtual string getValue(const ShaderPort* port, bool uniform = false) const;
107 
108  /// Get syntax for a swizzled variable
109  virtual string getSwizzledVariable(const string& srcName, const TypeDesc* srcType, const string& channels, const TypeDesc* dstType) const;
110 
111  /// Get swizzled value
112  virtual ValuePtr getSwizzledValue(ValuePtr value, const TypeDesc* srcType, const string& channels, const TypeDesc* dstType) const;
113 
114  /// Returns a type qualifier to be used when declaring types for input variables.
115  /// Default implementation returns empty string and derived syntax classes should
116  /// override this method.
117  virtual const string& getInputQualifier() const { return EMPTY_STRING; };
118 
119  /// Returns a type qualifier to be used when declaring types for output variables.
120  /// Default implementation returns empty string and derived syntax classes should
121  /// override this method.
122  virtual const string& getOutputQualifier() const { return EMPTY_STRING; };
123 
124  /// Get the qualifier used when declaring constant variables.
125  /// Derived classes must define this method.
126  virtual const string& getConstantQualifier() const = 0;
127 
128  /// Get the qualifier used when declaring uniform variables.
129  /// Default implementation returns empty string and derived syntax classes should
130  /// override this method.
131  virtual const string& getUniformQualifier() const { return EMPTY_STRING; };
132 
133  /// Return the characters used for a newline.
134  virtual const string& getNewline() const { return NEWLINE; };
135 
136  /// Return the characters used for a single indentation level.
137  virtual const string& getIndentation() const { return INDENTATION; };
138 
139  /// Return the characters used to begin/end a string definition.
140  virtual const string& getStringQuote() const { return STRING_QUOTE; };
141 
142  /// Return the string pattern used for a file include statement.
143  virtual const string& getIncludeStatement() const { return INCLUDE_STATEMENT; };
144 
145  /// Return the characters used for single line comment.
146  virtual const string& getSingleLineComment() const { return SINGLE_LINE_COMMENT; };
147 
148  /// Return the characters used to begin a multi line comments block.
149  virtual const string& getBeginMultiLineComment() const { return BEGIN_MULTI_LINE_COMMENT; };
150 
151  /// Return the characters used to end a multi line comments block.
152  virtual const string& getEndMultiLineComment() const { return END_MULTI_LINE_COMMENT; };
153 
154  /// Return the file extension used for source code files in this language.
155  virtual const string& getSourceFileExtension() const = 0;
156 
157  /// Return the array suffix to use for declaring an array type.
158  virtual string getArrayTypeSuffix(const TypeDesc*, const Value&) const { return EMPTY_STRING; };
159 
160  /// Return the array suffix to use for declaring an array variable.
161  virtual string getArrayVariableSuffix(const TypeDesc* type, const Value& value) const;
162 
163  /// Query if given type is suppored in the syntax.
164  /// By default all types are assumed to be supported.
165  virtual bool typeSupported(const TypeDesc* type) const;
166 
167  /// Modify the given name string to remove any invalid characters or tokens.
168  virtual void makeValidName(string& name) const;
169 
170  /// Make sure the given name is a unique identifier,
171  /// updating it if needed to make it unique.
172  virtual void makeIdentifier(string& name, IdentifierMap& identifiers) const;
173 
174  /// Create a unique identifier for the given variable name and type.
175  /// The method is used for naming variables (inputs and outputs) in generated code.
176  /// Derived classes can override this method to have a custom naming strategy.
177  /// Default implementation adds a number suffix, or increases an existing number suffix,
178  /// on the name string if there is a name collision.
179  virtual string getVariableName(const string& name, const TypeDesc* type, IdentifierMap& identifiers) const;
180 
181  /// Given an input specification attempt to remap this to an enumeration which is accepted by
182  /// the shader generator. The enumeration may be converted to a different type than the input.
183  /// @param value The value string to remap.
184  /// @param type The type of the value to remap,
185  /// @param enumNames Type enumeration names
186  /// @param result Enumeration type and value (returned).
187  /// @return Return true if the remapping was successful.
188  virtual bool remapEnumeration(const string& value, const TypeDesc* type, const string& enumNames,
189  std::pair<const TypeDesc*, ValuePtr>& result) const;
190 
191  /// Constants with commonly used strings.
192  static const string NEWLINE;
193  static const string SEMICOLON;
194  static const string COMMA;
195 
196  protected:
197  /// Protected constructor
198  Syntax();
199 
200  vector<TypeSyntaxPtr> _typeSyntaxes;
201  std::unordered_map<const TypeDesc*, size_t> _typeSyntaxByType;
202 
205 
206  static const string INDENTATION;
207  static const string STRING_QUOTE;
208  static const string INCLUDE_STATEMENT;
209  static const string SINGLE_LINE_COMMENT;
210  static const string BEGIN_MULTI_LINE_COMMENT;
211  static const string END_MULTI_LINE_COMMENT;
212 
213  static const std::unordered_map<char, size_t> CHANNELS_MAPPING;
214 };
215 
216 /// @class TypeSyntax
217 /// Base class for syntax handling of types.
219 {
220  public:
221  virtual ~TypeSyntax() { }
222 
223  /// Returns the type name.
224  const string& getName() const { return _name; }
225 
226  /// Returns a type alias if needed to define the type in the target language.
227  const string& getTypeAlias() const { return _typeAlias; }
228 
229  /// Returns a type definition if needed to define the type in the target language.
230  const string& getTypeDefinition() const { return _typeDefinition; }
231 
232  /// Returns the default value for this type.
233  const string& getDefaultValue(bool uniform) const { return uniform ? _uniformDefaultValue : _defaultValue; }
234 
235  /// Returns the syntax for accessing type members if the type
236  /// can be swizzled.
237  const StringVec& getMembers() const { return _members; }
238 
239  /// Returns a value formatted according to this type syntax.
240  /// The value is constructed from the given shader port object.
241  virtual string getValue(const ShaderPort* port, bool uniform) const;
242 
243  /// Returns a value formatted according to this type syntax.
244  /// The value is constructed from the given value object.
245  virtual string getValue(const Value& value, bool uniform) const = 0;
246 
247  /// Returns a value formatted according to this type syntax.
248  /// The value is constructed from the given list of value entries
249  /// with one entry for each member of the type.
250  virtual string getValue(const StringVec& values, bool uniform) const = 0;
251 
252  protected:
253  /// Protected constructor
254  TypeSyntax(const string& name, const string& defaultValue, const string& uniformDefaultValue,
255  const string& typeAlias, const string& typeDefinition, const StringVec& members);
256 
257  string _name; // type name
258  string _defaultValue; // default value syntax
259  string _uniformDefaultValue; // default value syntax when assigned to uniforms
260  string _typeAlias; // type alias if needed in source code
261  string _typeDefinition; // custom type definition if needed in source code
262  StringVec _members; // syntax for member access
263 
264  static const StringVec EMPTY_MEMBERS;
265 };
266 
267 /// Specialization of TypeSyntax for scalar types.
269 {
270  public:
271  ScalarTypeSyntax(const string& name, const string& defaultValue, const string& uniformDefaultValue,
272  const string& typeAlias = EMPTY_STRING, const string& typeDefinition = EMPTY_STRING);
273 
274  string getValue(const Value& value, bool uniform) const override;
275  string getValue(const StringVec& values, bool uniform) const override;
276 };
277 
278 /// Specialization of TypeSyntax for string types.
280 {
281  public:
282  StringTypeSyntax(const string& name, const string& defaultValue, const string& uniformDefaultValue,
283  const string& typeAlias = EMPTY_STRING, const string& typeDefinition = EMPTY_STRING);
284 
285  string getValue(const Value& value, bool uniform) const override;
286 };
287 
288 /// Specialization of TypeSyntax for aggregate types.
290 {
291  public:
292  AggregateTypeSyntax(const string& name, const string& defaultValue, const string& uniformDefaultValue,
293  const string& typeAlias = EMPTY_STRING, const string& typeDefinition = EMPTY_STRING,
294  const StringVec& members = EMPTY_MEMBERS);
295 
296  string getValue(const Value& value, bool uniform) const override;
297  string getValue(const StringVec& values, bool uniform) const override;
298 };
299 
301 
302 #endif
static const std::unordered_map< char, size_t > CHANNELS_MAPPING
Definition: Syntax.h:213
const string & getTypeDefinition() const
Returns a type definition if needed to define the type in the target language.
Definition: Syntax.h:230
string _typeDefinition
Definition: Syntax.h:261
const StringVec & getMembers() const
Definition: Syntax.h:237
const StringSet & getReservedWords() const
Returns a set of names that are reserved words for this language syntax.
Definition: Syntax.h:69
string _name
Definition: Syntax.h:257
virtual const string & getEndMultiLineComment() const
Return the characters used to end a multi line comments block.
Definition: Syntax.h:152
Specialization of TypeSyntax for scalar types.
Definition: Syntax.h:268
#define MATERIALX_NAMESPACE_BEGIN
Definition: Generated.h:25
string _defaultValue
Definition: Syntax.h:258
vector< string > StringVec
A vector of strings.
Definition: Library.h:57
const string & getName() const
Returns the type name.
Definition: Syntax.h:224
virtual string getArrayTypeSuffix(const TypeDesc *, const Value &) const
Return the array suffix to use for declaring an array type.
Definition: Syntax.h:158
virtual const string & getUniformQualifier() const
Definition: Syntax.h:131
StringMap _invalidTokens
Definition: Syntax.h:204
MATERIALX_NAMESPACE_BEGIN MX_CORE_API const string EMPTY_STRING
shared_ptr< TypeSyntax > TypeSyntaxPtr
Shared pointer to a TypeSyntax.
Definition: Syntax.h:30
const string & getTypeAlias() const
Returns a type alias if needed to define the type in the target language.
Definition: Syntax.h:227
shared_ptr< Syntax > SyntaxPtr
Shared pointer to a Syntax.
Definition: Syntax.h:26
const vector< TypeSyntaxPtr > & getTypeSyntaxes() const
Returns an array of all registered type syntax objects.
Definition: Syntax.h:79
shared_ptr< const Syntax > ConstSyntaxPtr
Shared pointer to a constant Syntax.
Definition: Syntax.h:28
static const string INDENTATION
Definition: Syntax.h:206
const string & getDefaultValue(bool uniform) const
Returns the default value for this type.
Definition: Syntax.h:233
virtual const string & getOutputQualifier() const
Definition: Syntax.h:122
virtual const string & getSingleLineComment() const
Return the characters used for single line comment.
Definition: Syntax.h:146
#define MX_GENSHADER_API
Definition: Export.h:18
**But if you need a result
Definition: thread.h:613
string _typeAlias
Definition: Syntax.h:260
string getValue(const Value &value, bool uniform) const override
virtual string getValue(const ShaderPort *port, bool uniform) const
virtual ~Syntax()
Definition: Syntax.h:52
std::unordered_map< const TypeDesc *, size_t > _typeSyntaxByType
Definition: Syntax.h:201
A generic, discriminated value, whose type may be queried dynamically.
Definition: Value.h:44
static const string END_MULTI_LINE_COMMENT
Definition: Syntax.h:211
string _uniformDefaultValue
Definition: Syntax.h:259
virtual const string & getIndentation() const
Return the characters used for a single indentation level.
Definition: Syntax.h:137
virtual const string & getStringQuote() const
Return the characters used to begin/end a string definition.
Definition: Syntax.h:140
static const string NEWLINE
Constants with commonly used strings.
Definition: Syntax.h:192
GLuint const GLchar * name
Definition: glcorearb.h:786
virtual const string & getNewline() const
Return the characters used for a newline.
Definition: Syntax.h:134
Specialization of TypeSyntax for aggregate types.
Definition: Syntax.h:289
vector< TypeSyntaxPtr > _typeSyntaxes
Definition: Syntax.h:200
Specialization of TypeSyntax for string types.
Definition: Syntax.h:279
static const string INCLUDE_STATEMENT
Definition: Syntax.h:208
GLenum GLsizei GLsizei GLint * values
Definition: glcorearb.h:1602
StringVec _members
Definition: Syntax.h:262
static const StringVec EMPTY_MEMBERS
Definition: Syntax.h:264
virtual ~TypeSyntax()
Definition: Syntax.h:221
Punctuation
Punctuation types.
Definition: Syntax.h:43
std::unordered_map< string, size_t > IdentifierMap
Definition: Syntax.h:34
StringSet _reservedWords
Definition: Syntax.h:203
std::unordered_map< string, string > StringMap
An unordered map with strings as both keys and values.
Definition: Library.h:59
std::set< string > StringSet
A set of strings.
Definition: Library.h:61
Definition: core.h:1131
#define MATERIALX_NAMESPACE_END
Definition: Generated.h:26
static const string COMMA
Definition: Syntax.h:194
static const string STRING_QUOTE
Definition: Syntax.h:207
virtual const string & getBeginMultiLineComment() const
Return the characters used to begin a multi line comments block.
Definition: Syntax.h:149
Definition: Syntax.h:39
virtual const string & getIncludeStatement() const
Return the string pattern used for a file include statement.
Definition: Syntax.h:143
shared_ptr< Value > ValuePtr
A shared pointer to a Value.
Definition: Value.h:29
type
Definition: core.h:1059
virtual const string & getInputQualifier() const
Definition: Syntax.h:117
static const string SINGLE_LINE_COMMENT
Definition: Syntax.h:209
ImageBuf OIIO_API channels(const ImageBuf &src, int nchannels, cspan< int > channelorder, cspan< float > channelvalues={}, cspan< std::string > newchannelnames={}, bool shuffle_channel_names=false, int nthreads=0)
const StringMap & getInvalidTokens() const
Returns a mapping from disallowed tokens to replacement strings for this language syntax...
Definition: Syntax.h:72
static const string BEGIN_MULTI_LINE_COMMENT
Definition: Syntax.h:210
static const string SEMICOLON
Definition: Syntax.h:193