For Engine Developers¶

Examples¶

The underscore symbol is used in function and variable names:

var foo_bar = 123;  // correct
var fooBar = 123;   // wrong

All global variables begin with an underscore:

var _foo_bar = null;

The constants are written in capital letters and never begin with an underscore:

var FOO_BAR = 100;

The names of external API methods and properties are written after a point. To avoid obfuscation of fields they must be listed with the @cc_externs tag:

exports.FOO_BAR = 123;

exports.foo_bar = function() {

}

/**
 * Set properties.
 * @method module:properties.set_props
 * @param {Object} foo Foo object
 * @cc_externs props_1 props_2
 * @cc_externs props_3 props_4
 */
exports.set_props = function(foo) {

    var bar_1 = foo.props_1;
    var bar_2 = foo.props_2;
    var bar_3 = foo.props_3;
    var bar_4 = foo.props_4;

    ...
}

Commenting is in English only. Comment style - JSDoc.

Validation¶

The compiler performs the following procedures related to shader code validation:

• reporting about unused variables and functions (dead code),
• checking the syntax of shaders,
• checking the conformance of shaders to the import/export mechanism,
• removing odd or repetitive tokens: spaces, line ends and semicolons.

Obfuscation¶

Obfuscation minifies the GLSL code and makes it difficult to understand it. So far the following procedure is implemented:

• replacing the user-defined identifiers with shorter single-symbol, two-symbol etc. names (with support of the import/export mechanism).

Optimization¶

Optimization constitutes the following procedures:

• removing curly brackets which are not useful in any ways except creating local scopes (this functionality is used for processing node/lamp directives),
• optimization inside functions - creating shared local variables to replace ones originally created by the programmer.

An example of removing unused curly brackets: replacing the following code

void function(){
    int a;
    {
        a = 1;
    }
}

with this code

void function(){
    int a;
    a = 1;
}

Low number of temporary local variables is achieved by repetitively using them in different contexts. For example, the following code

int function(){
    int a = 1;
    int b = a + 3;
    return b;
}

will be replaced with

int function(){
    int _int_tmp0 = 1;
    _int_tmp0 = _int_tmp0 + 3;
    return _int_tmp0;
}

Import/Export Directives¶

import/export directives are used to organize, structure and increase the readability of the shader code in the include file. They are specified in the beginning of the file and should look approximately like this:

#import u_frame_factor u_quatsb u_quatsa u_transb u_transa a_influence
#import qrot

#export skin

The #import directive defines a set of ids which are declared outside the include file but can be accessed from inside it. There is a limitation though: such ids must necessarily be declared somewhere above the place where the include file is linked.

The #export directive defines a set of ids which can be accessed from outside this file. Such ids must necessarily be declared in this file.

Therefore, the shader which uses the include file must have all the declarations necessary for import before the place of linking, and can use the exported ids after it.

Ids can be both variable names and function names. If there are no import/export directives it’s considered by default that the include file does not use external declarations and does not allow the using of internal ones.

Recommendations and Limitations¶

Because of the following reasons: preprocessing, the need to process multiple shaders and include files and due to the compiler’s features - its possible to guarantee the work of the output code only if a number of rules and limitations are respected with regard to the shader source code:

1. In order to describe constants which are defined by the engine at run, it’s necessary to use the #var special directive. For example:

#var AU_QUALIFIER uniform
AU_QUALIFIER float a;

The syntax here is similar to the #define directive. The point of the #var directive is that the value which it defines allows to parse the initial shader. It’s irrelevant what exactly it will be (e.g. ‘uniform’ or ‘attribute’ in the above example), because at this level it’s unknown anyway. Nevertheless, it’s better to specify a more or less suitable description and not something arbitrary.

2. Using the import/export directives when needed.
3. The built-in functions must not be overloaded - only the user ones.
4. Variables should not be declared with names of the built-in functions, or main (even if it doesn’t lead to errors).
5. The #var and #define directives must not be used for replacing single symbols in such operators as: “++”, “–”, “*=”, “/=”, “+=”, “-=”, “==”, “<=”, “>=”, ”!=”, “&&”, “||”, “^^”.

For example:

#var EQUAL =
...
a *EQUAL b;
...

6. The usage of the #include directive should not lead to ambiguity during the obfuscation of the include file. This can happen when multiple shaders are included into the same file and the above defined directives (like #var or #define) can have influence on any of them. Also, it’s better not to use undeclared functions and variables in the include file.
7. Multi-level includes or multiple inclusion of the same include into the same shader is not supported.
8. Shader malfunction can also be caused by nontrivial using of preprocessing, for example, creating an invalid GLSL code:

#if TYPE
void function1() {
#else
void function1(int i) {
#endif
    ...
}

9. Do not declare variables with such names as node_[NODE_NAME]_var_[IN_OUT_NODE], where NODE_NAME — name of some node, IN_OUT_NODE — name of an input or an output of the node.
10. Repetitive use of #nodes_main, #nodes_global or #lamps_main directives is not permitted inside a single shader.
11. The #nodes_main, #nodes_global and #lamps_main directives are recommended to use in the file, containing these shader nodes description, for example, in the same include-file. This is necessary for the correct shader validation.

WebGL Extensions¶

Compilation may depend on WebGL extensions being used if they somehow influence the shading language. At the moment the following extensions are supported by the compiler:

• OES_standard_derivatives

Compilation Errors¶

In case of an error the compiler will output the corresponding message in the console.

Table of possible errors: