Разработчикам движка¶

Примеры¶

В именах переменных и функций используется знак подчеркивания:

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

Все глобальные переменные начинаются со знака подчеркивания:

var _foo_bar = null;

Константы пишутся прописными буквами и никогда не начинаются со знака подчеркивания:

var FOO_BAR = 100;

Для внешних API названия методов и свойств задаются через точку. Поля, требующие защиту от обфускации, помещаются в специальный тэг @cc_externs:

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;

    ...
}

Комментарии только на английском языке. Стиль комментирования - JSDoc.

Валидация¶

Компилятор шейдеров выполняет следующие процедуры, связанные с проверкой кода:

• вывод сообщений о неиспользуемых переменных и функциях (dead code),

• проверка синтаксиса шейдеров,

• проверка шейдеров на соответствие import/export-механизма,

• удаление лишних пробелов, переводов строк и повторяющихся символов ”;”.

Обфускация¶

Обфускация служит для сокращения объема и затруднения понимания GLSL-кода. На данный момент в нем реализована следующая процедура:

• замена пользовательских идентификаторов более короткими односимвольными, двухсимвольными и т.д. именами (с поддержкой import/export-механизма).

Оптимизация¶

Оптимизация заключается в выполнении следующих процедур:

• удаление фигурных скобок, которые не несут функциональной нагрузки, но порождают новые области видимости (данный функционал полезен при обработке директив node/lamp),

• внутрифункциональная оптимизация, связанная с использованием малого числа буферных локальных переменных взамен локальных переменных, заданных программистом.

Примером удаления бесполезных фигурных скобок может служить замена кода

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

следующим кодом

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

Использование малого числа буферных локальных переменных заключается в том, что они повторно используются в разных контекстах. Например, следующий код

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

будет заменен на

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

Директивы import/export¶

В целях упорядочивания, структурирования и повышения удобочитаемости кода шейдеров в include-файлах используются директивы import и export. Они указываются в начале файла и должны выглядеть примерно следующим образом:

#import u_frame_factor u_quatsb u_quatsa u_transb u_transa a_influence
#import qrot

#export skin

Директива #import определяет набор идентификаторов, которые объявлены вне этого include-файла, но доступны для использования в нем. Имеется ограничение: такие идентификаторы должны быть обязательно объявлены где-либо выше места подключения include-файла.

Директива #export определяет набор идентификаторов, доступных для использования вне данного файла. Такие идентификаторы должны быть обязательно объявлены в этом файле.

Таким образом, шейдер, использующий include-файл, обязан до места подключения содержать объявления, необходимые для импорта, а после него может использовать экспортируемые идентификаторы.

Идентификаторами могут быть как имена переменных, так и имена функций. По умолчанию при отсутствии директив import/export считается, что include-файл не использует внешние объявления и не предоставляет пользование внутренними.

Рекомендации и ограничения¶

В связи с наличием препроцессинга, необходимостью совместной обработки нескольких шейдеров и include-файлов, а также особенностями реализации компилятора гарантировать работоспособность полученного на выходе кода можно только при соблюдении ряда правил или ограничений на текст исходных шейдеров:

1. Обязательное использование специальной директивы #var для описания констант, определяемых движком в момент запуска. Например:

#var AU_QUALIFIER uniform
AU_QUALIFIER float a;

Синтаксис здесь схож с директивой #define. Смысл директивы #var в том, чтобы определяемое ею значение позволило распарсить исходный шейдер. Что это будет конкретно (например, ‘uniform’ или ‘attribute’ в примере выше), не важно, т.к. на этом этапе оно все равно неизвестно. Однако, желательно указывать более-менее подходящее описание, а не что-то совершенно произвольное.

2. Использование при необходимости директив import/export.

3. Не следует перегружать встроенные функции, только пользовательские.

4. Не следует объявлять переменные с именем одной из встроенных функций, либо main (даже если это не приводит к ошибке).

5. Нельзя использовать директивы #var и #define для замены отдельных символов в таких операторах, как: “++”, “–”, “*=”, “/=”, “+=”, “-=”, “==”, “<=”, “>=”, ”!=”, “&&”, “||”, “^^”.

Например:

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

6. Использование директивы #include, не должно приводить к неоднозначности при обфускации содержимого include-файла. Это может произойти в том случае, когда один и тот же файл включается в несколько разных шейдеров, и в каком-то из них могут повлиять определенные выше директивы, вроде #var или #define. Также не стоит использовать в include-файле необъявленные функции и переменные.

7. Использование вложенных include’ов или множественного включения одного и того же include’a в один и тот же шейдер не поддерживается.

8. К неработоспособности шейдера может привести нетривиальное использование препроцессинга, например, создающее невалидный GLSL-код:

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

9. Не следует объявлять переменные с именами вида node_[NODE_NAME]_var_[IN_OUT_NODE], где NODE_NAME — название некоторой ноды, IN_OUT_NODE — название одного из входов или выходов ноды.

10. Не разрешается множественное использование одной и той же директивы #nodes_main, #nodes_global или #lamps_main в одном шейдере.

11. Директивы #nodes_main, #nodes_global и #lamps_main рекомендуется использовать в том же файле, в котором содержится описание шейдерных нод, например, в одном и том же include-файле - это необходимо для корректной валидации шейдеров.

Расширения WebGL¶

Работа обфускатора может зависеть от используемых WebGL-расширений, если они каким-либо образом влияют на шейдерный язык. На данный момент поддерживаются следующие расширения:

• OES_standard_derivatives

Ошибки компилятора¶

В случае ошибки компилятор выведет соответствующее сообщение в консоли.

Перечень возможных ошибок: