HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ShaderGenerator.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_SHADERGENERATOR_H
7 #define MATERIALX_SHADERGENERATOR_H
8 
9 /// @file
10 /// Base shader generator class
11 
13 
18 
19 #include <MaterialXFormat/File.h>
20 
22 
24 
25 /// @class ShaderGenerator
26 /// Base class for shader generators
27 /// All third-party shader generators should derive from this class.
28 /// Derived classes should use DECLARE_SHADER_GENERATOR / DEFINE_SHADER_GENERATOR
29 /// in their declaration / definition, and register with the Registry class.
31 {
32  public:
33  /// Destructor
34  virtual ~ShaderGenerator() { }
35 
36  /// Return the name of the target this generator is for.
37  virtual const string& getTarget() const
38  {
39  return EMPTY_STRING;
40  }
41 
42  /// Generate a shader starting from the given element, translating
43  /// the element and all dependencies upstream into shader code.
44  virtual ShaderPtr generate(const string&, ElementPtr, GenContext&) const
45  {
46  return nullptr;
47  }
48 
49  /// Start a new scope using the given bracket type.
50  virtual void emitScopeBegin(ShaderStage& stage, Syntax::Punctuation punc = Syntax::CURLY_BRACKETS) const;
51 
52  /// End the current scope.
53  virtual void emitScopeEnd(ShaderStage& stage, bool semicolon = false, bool newline = true) const;
54 
55  /// Start a new line.
56  virtual void emitLineBegin(ShaderStage& stage) const;
57 
58  /// End the current line.
59  virtual void emitLineEnd(ShaderStage& stage, bool semicolon = true) const;
60 
61  /// Add a line break.
62  virtual void emitLineBreak(ShaderStage& stage) const;
63 
64  /// Add a string.
65  virtual void emitString(const string& str, ShaderStage& stage) const;
66 
67  /// Add a single line of code, optionally appending a semicolon.
68  virtual void emitLine(const string& str, ShaderStage& stage, bool semicolon = true) const;
69 
70  /// Add a single line code comment.
71  virtual void emitComment(const string& str, ShaderStage& stage) const;
72 
73  /// Add a block of code.
74  virtual void emitBlock(const string& str, const FilePath& sourceFilename, GenContext& context, ShaderStage& stage) const;
75 
76  /// Add the contents of a standard library include file if not already present.
77  /// The library file prefix of the given context, if any, will be prepended
78  /// to the given filename.
79  virtual void emitLibraryInclude(const FilePath& filename, GenContext& context, ShaderStage& stage) const;
80 
81  /// Add a value.
82  template <typename T>
83  void emitValue(const T& value, ShaderStage& stage) const
84  {
85  stage.addValue<T>(value);
86  }
87 
88  /// Add the function definition for a single node.
89  virtual void emitFunctionDefinition(const ShaderNode& node, GenContext& context, ShaderStage& stage) const;
90 
91  /// Add all function definitions for a graph.
92  virtual void emitFunctionDefinitions(const ShaderGraph& graph, GenContext& context, ShaderStage& stage) const;
93 
94  /// Add the function call for a single node.
95  virtual void emitFunctionCall(const ShaderNode& node, GenContext& context, ShaderStage& stage) const;
96  [[deprecated]] virtual void emitFunctionCall(const ShaderNode& node, GenContext& context, ShaderStage& stage, bool checkScope) const;
97 
98  /// Add all function calls for a graph. If a classification mask is given only functions for
99  /// nodes matching this classification will be emitted.
100  virtual void emitFunctionCalls(const ShaderGraph& graph, GenContext& context, ShaderStage& stage, uint32_t classification = 0u) const;
101 
102  /// Add function calls for nodes connected directly upstream from the given node.
103  /// If a classification mask is given only functions for nodes matching this classification
104  /// will be emitted.
105  virtual void emitDependentFunctionCalls(const ShaderNode& node, GenContext& context, ShaderStage& stage, uint32_t classification = 0u) const;
106 
107  /// Emit code for starting a new function body.
108  virtual void emitFunctionBodyBegin(const ShaderNode& node, GenContext& context, ShaderStage& stage, Syntax::Punctuation punc = Syntax::CURLY_BRACKETS) const;
109 
110  /// Emit code for ending a function body.
111  virtual void emitFunctionBodyEnd(const ShaderNode& node, GenContext& context, ShaderStage& stage) const;
112 
113  /// Emit type definitions for all data types that needs it.
114  virtual void emitTypeDefinitions(GenContext& context, ShaderStage& stage) const;
115 
116  /// Emit the connected variable name for an input,
117  /// or constant value if the port is not connected
118  virtual void emitInput(const ShaderInput* input, GenContext& context, ShaderStage& stage) const;
119 
120  /// Emit the output variable name for an output, optionally including it's type
121  /// and default value assignment.
122  virtual void emitOutput(const ShaderOutput* output, bool includeType, bool assignValue, GenContext& context, ShaderStage& stage) const;
123 
124  /// Emit definitions for all shader variables in a block.
125  /// @param block Block to emit.
126  /// @param qualifier Optional qualifier to add before the variable declaration.
127  /// @param separator Separator to use between the declarations.
128  /// @param context Context for generation.
129  /// @param stage The stage to emit code into.
130  /// @param assignValue If true the variables are initialized with their value.
131  virtual void emitVariableDeclarations(const VariableBlock& block, const string& qualifier, const string& separator, GenContext& context, ShaderStage& stage,
132  bool assignValue = true) const;
133 
134  /// Emit definition of a single shader variable.
135  /// @param variable Shader port representing the variable.
136  /// @param qualifier Optional qualifier to add before the variable declaration.
137  /// @param context Context for generation.
138  /// @param stage The stage to emit code into.
139  /// @param assignValue If true the variable is initialized with its value.
140  virtual void emitVariableDeclaration(const ShaderPort* variable, const string& qualifier, GenContext& context, ShaderStage& stage,
141  bool assignValue = true) const;
142 
143  /// Return the closure contexts defined for the given node.
144  virtual void getClosureContexts(const ShaderNode& node, vector<ClosureContext*>& cct) const;
145 
146  /// Return the result of an upstream connection or value for an input.
147  virtual string getUpstreamResult(const ShaderInput* input, GenContext& context) const;
148 
149  /// Return the syntax object for the language used by the code generator
150  const Syntax& getSyntax() const { return *_syntax; }
151 
152  /// Register a shader node implementation for a given implementation element name
153  void registerImplementation(const string& name, CreatorFunction<ShaderNodeImpl> creator);
154 
155  /// Register a shader node implementation for a given set of implementation element names
156  void registerImplementation(const StringVec& nameVec, CreatorFunction<ShaderNodeImpl> creator);
157 
158  /// Determine if a shader node implementation has been registered for a given implementation element name
159  bool implementationRegistered(const string& name) const;
160 
161  /// Return a registered shader node implementation for the given nodedef.
162  virtual ShaderNodeImplPtr getImplementation(const NodeDef& nodedef, GenContext& context) const;
163 
164  /// Sets the color management system
166  {
167  _colorManagementSystem = colorManagementSystem;
168  }
169 
170  /// Returns the color management system
172  {
173  return _colorManagementSystem;
174  }
175 
176  /// Sets the unit system
177  void setUnitSystem(UnitSystemPtr unitSystem)
178  {
179  _unitSystem = unitSystem;
180  }
181 
182  /// Returns the unit system
184  {
185  return _unitSystem;
186  }
187 
188  /// Return the map of token substitutions used by the generator.
190  {
191  return _tokenSubstitutions;
192  }
193 
194  /// Register metadata that should be exported to the generated shaders.
195  /// Supported metadata includes standard UI attributes like "uiname", "uifolder",
196  /// "uimin", "uimax", etc.
197  /// But it is also extendable by defining custom attributes using AttributeDefs.
198  /// Any AttributeDef in the given document with exportable="true" will be
199  /// exported as shader metadata when found on nodes during shader generation.
200  /// Derived shader generators may override this method to change the registration.
201  /// Applications must explicitly call this method before shader generation to enable
202  /// export of metadata.
203  virtual void registerShaderMetadata(const DocumentPtr& doc, GenContext& context) const;
204 
205  protected:
206  /// Protected constructor
207  ShaderGenerator(SyntaxPtr syntax);
208 
209  /// Create a new stage in a shader.
210  virtual ShaderStagePtr createStage(const string& name, Shader& shader) const;
211 
212  /// Set function name for a stage.
213  void setFunctionName(const string& functionName, ShaderStage& stage) const
214  {
215  stage.setFunctionName(functionName);
216  }
217 
218  /// Replace tokens with identifiers according to the given substitutions map.
219  void replaceTokens(const StringMap& substitutions, ShaderStage& stage) const;
220 
221  /// Create shader variables (e.g. uniforms, inputs and outputs) for
222  /// nodes that require input data from the application.
223  void createVariables(ShaderGraphPtr graph, GenContext& context, Shader& shader) const;
224 
225  protected:
226  static const string T_FILE_TRANSFORM_UV;
227 
233 
234  friend ShaderGraph;
235 };
236 
237 /// @class ExceptionShaderGenError
238 /// An exception that is thrown when shader generation fails.
240 {
241  public:
242  using Exception::Exception;
243 };
244 
246 
247 #endif // MATERIALX_SHADERGENERATOR_H
GT_API const UT_StringHolder filename
ColorManagementSystemPtr _colorManagementSystem
shared_ptr< ShaderNodeImpl > ShaderNodeImplPtr
Shared pointer to a ShaderNodeImpl.
Definition: Library.h:40
Definition: File.h:26
void setFunctionName(const string &functionName, ShaderStage &stage) const
Set function name for a stage.
Factory< ShaderNodeImpl > _implFactory
void addValue(const T &value)
Add a value.
Definition: ShaderStage.h:264
void setColorManagementSystem(ColorManagementSystemPtr colorManagementSystem)
Sets the color management system.
static const string T_FILE_TRANSFORM_UV
#define MATERIALX_NAMESPACE_BEGIN
Definition: Generated.h:25
vector< string > StringVec
A vector of strings.
Definition: Library.h:57
GLsizei const GLfloat * value
Definition: glcorearb.h:824
const Syntax & getSyntax() const
Return the syntax object for the language used by the code generator.
shared_ptr< class UnitSystem > UnitSystemPtr
A shared pointer to a UnitSystem.
Definition: UnitSystem.h:26
MATERIALX_NAMESPACE_BEGIN MX_CORE_API const string EMPTY_STRING
shared_ptr< Syntax > SyntaxPtr
Shared pointer to a Syntax.
Definition: Syntax.h:26
#define MX_GENSHADER_API
Definition: Export.h:18
void setUnitSystem(UnitSystemPtr unitSystem)
Sets the unit system.
const StringMap & getTokenSubstitutions() const
Return the map of token substitutions used by the generator.
shared_ptr< class ColorManagementSystem > ColorManagementSystemPtr
A shared pointer to a ColorManagementSystem.
void emitValue(const T &value, ShaderStage &stage) const
Add a value.
UnitSystemPtr _unitSystem
shared_ptr< Document > DocumentPtr
A shared pointer to a Document.
Definition: Document.h:22
GLuint const GLchar * name
Definition: glcorearb.h:786
shared_ptr< class ShaderGraph > ShaderGraphPtr
A shared pointer to a shader graph.
Definition: ShaderGraph.h:39
void setFunctionName(const string &functionName)
Set stage function name.
Definition: ShaderStage.h:284
ColorManagementSystemPtr getColorManagementSystem() const
Returns the color management system.
virtual const string & getTarget() const
Return the name of the target this generator is for.
GLuint shader
Definition: glcorearb.h:785
Definition: Shader.h:32
Exception(const string &msg)
Definition: Exception.h:24
shared_ptr< ShaderStage > ShaderStagePtr
Shared pointer to a ShaderStage.
Definition: Library.h:36
Punctuation
Punctuation types.
Definition: Syntax.h:43
UnitSystemPtr getUnitSystem() const
Returns the unit system.
std::unordered_map< string, string > StringMap
An unordered map with strings as both keys and values.
Definition: Library.h:59
shared_ptr< Shader > ShaderPtr
Shared pointer to a Shader.
Definition: Library.h:34
Definition: core.h:1131
shared_ptr< Element > ElementPtr
A shared pointer to an Element.
Definition: Element.h:31
#define MATERIALX_NAMESPACE_END
Definition: Generated.h:26
virtual ~ShaderGenerator()
Destructor.
Definition: Syntax.h:39
virtual ShaderPtr generate(const string &, ElementPtr, GenContext &) const
StringMap _tokenSubstitutions