Content

ShaderFile:

+
-

Description:

Inside the shader file you define every needed OpenGL shader code, meta information and precompiler instructions you need. The precompiler then interprets your code and generate the normal OpenGL shader code for you. It will take care, that only the needed code parts are added to the resulting code, so the shader code is always as simple and small as needed.
The shader file is also a code generator. It's name is a empty string. So if you pass the empty string to the code generator creator function you will get the code generator for the whole file.
A class does not need a {$MAIN} method.
+
-

Syntax:

+
-

Example:

"Hello World" example:
{$MAIN}
gl_Position = gl_ModelViewProjectionMatrix * gl_Vertex;
gl_FrontColor = gl_Color;
{$END}

resulting code:
void main(void)
{
gl_Position = gl_ModelViewProjectionMatrix * gl_Vertex;
gl_FrontColor = gl_Color;
}

Class:

+
-

Description:

A class is a logical wrapper to summarize OpenGL shader code, meta information and precompiler instructions. You can inherit a class from other classes using the $EXTENDS token. The precompiler then interprets your code and generate the normal OpenGL shader code for you. It will take care, that only the needed code parts are added to the resulting code, so the shader code is always as simple and small as needed.
A class is always a generator. If you use the name of class as parameter for the code generator creator function you will get a code generator for the requested class.
A class or one of its parent classes always needs a {$MAIN} method.
+
-

Syntax:

Class
{$CLASS ClassName $EXTENDS ClassName } ClassProcedure ClassFunction ClassMain Code {$END}
Class ::= '{$CLASS' ClassName ( '$EXTENDS' ClassName* )? '}' ( ClassProcedure | ClassFunction | ClassMain | Code )* '{$END}'
referenced by:
+
-

Example:

example for a simple shader that uses either a solid color or a texture:
{$CLASS Color}
{$PROPERTY UseColorMap 'false'}
{$END}

{$CLASS ColorFrag $EXTENDS Color}

/* you can also define code here. It will be added when the code for the class is generated */

{$FUNC 'vec4' GetColor $INLINE}
{$IF UseColorMap}
{$VAR 'vec2' '_texCoord' 'gl_TexCoord[0].st'}
{$UNIFORM 'sampler2D' 'uColorMap'}
return texture2D(uColorMap, _texCoord);
{$ELSE}
return gl_Color;
{$END}
{$END}

{$MAIN}
gl_FragColor = {$CALL GetColor};
{$END}
{$END}

{$CLASS ColorVert $EXTENDS Color}
{$MAIN}
gl_Position = gl_ModelViewProjectionMatrix * gl_Vertex;
{$IF UseColorMap}
gl_TexCoord[0] = gl_MultiTexCoord0;
{$ELSE}
gl_FrontColor = gl_Color;
gl_BackColor = gl_Color;
{$END}
{$END}
{$END}

resulting code for ColorFrag with UseColorMap = true
/* you can also define code here. It will be added when the code for the class is generated */

uniform sampler2D uColorMap;

vec2 _texCoord = gl_TexCoord[0].st;

void main(void)
{
gl_FragColor = (texture2D(uColorMap, _texCoord));
}

Procedure

+
-

Description:

The procedure token will generate a normal procedure in the resulting code, when the procedure is at least used one time inside a {$CALL}.
Inside a class you can add the $INLINE token. If the $INLINE token is added the code inside the procedure will be copied and pasted inside the resulting code.
Be careful with inlined methods, because the precompiler will not check the variable names inside the method, so you maybe have a duplicate variable when it is pasted inside the resulting code.
+
-

Syntax:

Procedure
ProcedureHead Code {$END}
Procedure ::= ProcedureHead Code '{$END}'
referenced by:
ClassProcedure
ProcedureHead Code Inherited {$END}
ClassProcedure ::= ProcedureHead ( Code | Inherited )* '{$END}'
referenced by:
ProcedureHead
{$PROC MethodName ParameterType ParameterName $INLINE }
ProcedureHead ::= '{$PROC' MethodName ( ParameterType ParameterName )* '$INLINE'? '}'
referenced by:
+
-

Example:

simple example:
{$PROC setFragColor 'vec2' 'texCoord'}
{$UNIFORM 'sampler2D' 'uColorMap'}
vec4 color = texture2D(uColorMap, texCoord);
gl_FragColor = color;
{$END}

{$CALL setFragColor 'gl_TexCoord[0].st'};

resulting code:
uniform sampler2D uColorMap;

void setFragColor(vec2 texCoord)
{
vec4 color = texture2D(uColorMap, texCoord);
gl_FragColor = color;
}

setFragColor(gl_TexCoord[0].st);

Function

+
-

Description:

The function token will generate a normal function in the resulting code, when the function is at least used one time inside a {$CALL}.
Inside a class you can add the $INLINE token. If the $INLINE token is added the code inside the function will be copied and pasted inside the resulting code.
Be careful with inlined methods, because the precompiler will not check the variable names inside the method, so you maybe have a duplicate variable when it is pasted inside the resulting code.
+
-

Syntax:

Function
FunctionHead Code {$END}
Function ::= FunctionHead Code '{$END}'
referenced by:
ClassFunction
FunctionHead Code Inherited {$END}
ClassFunction ::= FunctionHead ( Code | Inherited )* '{$END}'
referenced by:
+
-

Example:

simple example:
{$FUNC 'vec4' 'getColor'}
{$UNIFORM 'sampler2D' 'uColorMap'}
vec2 texCoord = gl_TexCoord[0].st;
return texture2D(uColorMap, texCoord);
{$END}

gl_FragColor = {$CALL getColor};

resulting code:
uniform sampler2D uColorMap;

vec4 getColor()
{
vec2 texCoord = gl_TexCoord[0].st;
return texture2D(uColorMap, texCoord);
}

gl_FragColor = getColor();

Main

+
-

Description:

The {$MAIN} token is a special procedure without parameters that will be called automatically by the pre compiler, when the code is generated. The {$MAIN} token is necessary inside a class and optional inside a shader file.
+
-

Syntax:

Main
{$MAIN} Code {$END}
Main ::= '{$MAIN}' Code '{$END}'
referenced by:
ClassMain
{$MAIN} Code Inherited {$END}
ClassMain ::= '{$MAIN}' ( Code | Inherited )* '{$END}'
referenced by:
+
-

Example:

simple example:
{$MAIN}
gl_Position = gl_ModelViewProjectionMatrix * gl_Vertex;
gl_FrontColor = gl_Color;
{$END}

resulting code:
void main(void)
{
gl_Position = gl_ModelViewProjectionMatrix * gl_Vertex;
gl_FrontColor = gl_Color;
}

Call

+
-

Description:

The {$CALL} token tells the precompiler to execute a method.
If the method is marked with the $INLINE token the code of this method will be copied and pasted in the resulting code. Be careful with inlined methods, because the precompiler will not check the variable names inside the method, so you maybe have a duplicate variable when it is pasted inside the resulting code.
If the method is not marked with the $INLINE token a normal method will be generated in the resulting code.
+
-

Syntax:

Call
{$CALL MethodName Parameter }
Call ::= '{$CALL' MethodName Parameter* '}'
referenced by:
+
-

Example:

simple example:
{$FUNC 'vec4' 'getColor'}
{$UNIFORM 'sampler2D' 'uColorMap'}
vec2 texCoord = gl_TexCoord[0].st;
return texture2D(uColorMap, texCoord);
{$END}

gl_FragColor = {$CALL getColor};

resulting code:
uniform sampler2D uColorMap;

vec4 getColor()
{
vec2 texCoord = gl_TexCoord[0].st;
return texture2D(uColorMap, texCoord);
}

gl_FragColor = getColor();

Inherited

+
-

Description:

The {$INHERITED} token is a special {$CALL} token. It can only be used inside a {$CLASS}. It will call a method inside a parent class. If you add the $INLINE token, the called method will be inlined. Be careful with inlined methods, because the precompiler will not check the variable names inside the method, so you maybe have a duplicate variable when it is pasted inside the resulting code.
+
-

Syntax:

Inherited
{$INHERITED ClassName MethodName Parameter $INLINE }
Inherited ::= '{$INHERITED' ClassName? MethodName? Parameter* '$INLINE'? '}'
referenced by:
+
-

Example:

example:
{$CLASS ColorVert}
{$MAIN}
gl_Position = gl_ModelViewProjectionMatrix * gl_Vertex;
gl_TexCoord[0] = gl_MultiTexCoord0;
{$END}
{$END}

{$CLASS PhongLightVert $EXTENDS ColorVert}
{$MAIN}
{$VARYING 'vec3' 'vNormal'}
{$VARYING 'vec3' 'vVertex'}
{$INHERITED ColorVert $INLINE};
vNormal = normalize(gl_NormalMatrix * gl_Normal);
vVertex = vec3(gl_ModelViewMatrix * gl_Vertex);
{$END}
{$END}

resulting code:
varying vec3 vNormal;
varying vec3 vVertex;

void main(void)
{
gl_Position = gl_ModelViewProjectionMatrix * gl_Vertex;
gl_TexCoord[0] = gl_MultiTexCoord0;
vNormal = normalize(gl_NormalMatrix * gl_Normal);
vVertex = vec3(gl_ModelViewMatrix * gl_Vertex);
}

Include

+
-

Description:

Using the {$INCLUDE} token you can add another shader file to the current file.
+
-

Syntax:

Include
{$INCLUDE Filepath }
Include ::= '{$INCLUDE' Filepath '}'
referenced by:
+
-

Example:

{$INCLUDE './path/to/file.shdr'}

Property

+
-

Description:

The {$PROPERTY} token defines a property. The value of the property can be changed inside the application code, before generating the resulting shader code.
+
-

Syntax:

Property
{$PROPERTY PropertyName StaticName Value }
Property ::= '{$PROPERTY' PropertyName ( StaticName | Value )? '}'
referenced by:
+
-

Example:

{$PROPERTY MyBoolProperty 'true'}

Static

+
-

Description:

The {$STATIC} token defines a static constant. It is used to name a magic value, for a better code.
+
-

Syntax:

Static
{$STATIC StaticName Value }
Static ::= '{$STATIC' StaticName Value? '}'
referenced by:
+
-

Example:

{$STATIC MyStaticDouble '123.4'}

If

+
-

Description:

Using the {$IF} token you can add another path to the decision tree.
+
-

Syntax Diagram:

If
{$IF Expression } Code {$ELIF {$ELSE} Code {$END}
If ::= '{$IF' Expression '}' Code ( '{$ELIF' Expression '}' Code )* ( '{$ELSE}' Code )? '{$END}'
referenced by:
+
-

Example:

simple example:
{$FUNC 'vec4' GetColor $INLINE}
{$IF UseColorMap}
{$UNIFORM 'sampler2D' 'uColorMap'}
returntexture2D(uColorMap, gl_TexCoord[0].st);
{$ELSE}
return gl_Color;
{$END}
{$END}

resulting code for UseColorMap = true
uniform sampler2D uColorMap;

void main(void)
{
gl_FragColor = (texture2D(uColorMap, gl_TexCoord[0].st));
}

Messages

+
-

Description:

Using the {$INFO}, {$WARNING} or {$ERROR} token you can generate a log message, when the resulting code is generated.
Using the {$THROW} token will throw a exception while generating the resulting code.
+
-

Syntax Diagram:

Info
{$INFO TextQuoted }
Info ::= '{$INFO' TextQuoted '}'
referenced by:
Warning
{$WARNING TextQuoted }
Warning ::= '{$WARNING' TextQuoted '}'
referenced by:
Error
{$ERROR TextQuoted }
Error ::= '{$ERROR' TextQuoted '}'
referenced by:
Throw
{$THROW TextQuoted }
Throw ::= '{$THROW' TextQuoted '}'
referenced by:
+
-

Example:

{$INFO 'This is a simple info message.'}

Meta

+
-

Description:

The {$META} token is used to add meta information like version and extension to the resulting code.
+
-

Syntax:

Meta
{$META TextQuoted $VERSION VersionNumber compatibility $EXTENSION ExtensionName ExtensionValue $LAYOUT LayoutValue }
Meta ::= '{$META' ( TextQuoted* | '$VERSION' VersionNumber 'compatibility'? | '$EXTENSION' ExtensionName ExtensionValue | '$LAYOUT' LayoutValue ) '}'
referenced by:
+
-

Example:

{$META $VERSION 130 compatibility}

Echo

+
-

Description:

The {$ECHO} token will add the value of a {$STATIC} or {$PROPERTY} to the resulting code.
+
-

Syntax:

Echo
{$ECHO StaticName PropertyName TextQuoted }
Echo ::= '{$ECHO' ( StaticName | PropertyName | TextQuoted ) '}'
referenced by:
+
-

Example:

simple example:
{$PROPERTY MyProperty '/* this is a test */'}
{$ECHO MyProperty}

resulting code:
/* this is a test */

Varying

+
-

Description:

The {$VARYING} token defines a varying inside the resuling code.
+
-

Syntax:

Varying
{$VARYING glslTypeQuoted IdentifierQuoted }
Varying ::= '{$VARYING' glslTypeQuoted IdentifierQuoted '}'
referenced by:
+
-

Example:

simple example:
{$VARYING 'vec4' 'vVertex'}

resulting code:
varying vec4 vVertex;

Uniform

+
-

Description:

The {$UNIFORM} token defines an uniform inside the resuling code.
+
-

Syntax:

Uniform
{$UNIFORM glslTypeQuoted IdentifierQuoted }
Uniform ::= '{$UNIFORM' glslTypeQuoted IdentifierQuoted '}'
referenced by:
+
-

Example:

simple example:
{$UNIFORM 'vec4' 'uColor'}

resulting code:
uniform vec4 uColor;

Var

+
-

Description:

The {$VAR} token defines a global variable inside the resuling code.
+
-

Syntax:

+
-

Example:

simple example:
{$VAR 'vec4' '_vertex' 'vec4(1.0)'}

resulting code:
vec4 _vertex = vec4(1.0);

Const

+
-

Description:

The {$CONST} token defines a global constant inside the resuling code.
+
-

Syntax:

+
-

Example:

simple example:
{$CONST 'vec4' 'VERTEX' 'vec4(1.0)'}

resulting code:
const vec4 VERTEX = vec4(1.0);

Types

+
-

Syntax Diagram:

Expression
PropertyName StaticName Value $NOT ! Expression ( Expression ) Expression $OR $AND $XOR + - * / = < > <= >= <> | & ^ Expression
Expression ::= PropertyName | StaticName | Value | ( '$NOT' | '!' ) Expression | '(' Expression ')' | Expression ( '$OR' | '$AND' | '$XOR' | '+' | '-' | '*' | '/' | '=' | '<' | '>' | '<=' | '>=' | '<>' | '|' | '&' | '^' ) Expression
referenced by:
ClassName
Identifier
ClassName ::= Identifier
referenced by:
ExtensionName
IdentifierQuoted
ExtensionName ::= IdentifierQuoted
referenced by:
glslValue
glslCodeQuoted
glslValue ::= glslCodeQuoted
referenced by:
ExtensionValue
glslCodeQuoted
ExtensionValue ::= glslCodeQuoted
referenced by:
LayoutValue
glslCodeQuoted
LayoutValue ::= glslCodeQuoted
referenced by:
TextQuoted
' Text '
TextQuoted ::= ['] Text [']
referenced by:
VersionNumber
[0-9]
VersionNumber ::= [0-9]
referenced by:
Identifier
[A-Z] [a-z] [0-9] _
Identifier ::= [A-Za-z0-9_]
referenced by:
Filepath
' [A-Z] [a-z] [0-9] \ / _ - '
Filepath ::= ['] [A-Za-z0-9\/_#x2D] [']
referenced by:
glslCodeQuoted
' glslCode '
glslCodeQuoted ::= ['] glslCode [']
referenced by:
glslTypeQuoted
' glslType '
glslTypeQuoted ::= ['] glslType [']
referenced by: