Разработчикам приложений

Написание логики приложений

Приложение Hello world!

Простейшее приложение на основе Blend4Web может иметь вид:

<!DOCTYPE html>
<html>
<head>
<script src="b4w.min.js"></script>
<script>
function hello() {
    var m_version = b4w.require("version");
    document.body.innerHTML = "Hello, Blend4Web " + m_version.version() + "!";
}
</script>
</head>

<body onload="hello()"></body>

</html>

Приложение выводит сообщение и текущую версию движка в окне браузера. Рассмотрим представленный пример. Базовый код движка подключается с помощью тега <script src="...">. Далее, приложение ожидает окончания загрузки страницы и выводит сообщение в окне браузера. В данном примере используется единственный модуль version, в котором находится одноимённая функция version(). Подробную информацию о предназначении модулей и функций движка можно найти в документации по API.

Файл b4w.min.js со скомпилированным кодом движка необходимо скопировать из директории SDK deploy/apps/common и разместить в той же директории, что и представленный HTML-файл.

Загрузка сцены в приложение

Для того, чтобы загрузить трёхмерную сцену, требуется выполнить следующую последовательность действий:

  1. Разместить на странице элемент <canvas>, на котором будет производиться рендеринг.

  2. После загрузки страницы, для инициализации контекста WebGL, вызвать функцию m_main.init() с идентификатором созданного элемента.

  3. Вызвать функцию m_data.load() для загрузки трёхмерной сцены.

<!DOCTYPE html>
<html>
<head>
<script src="b4w.min.js"></script>
<script>
function hello() {
    var m_main = b4w.require("main");
    var m_data = b4w.require("data");

    var canvas_elem = document.getElementById("canvas_id");
    m_main.init(canvas_elem);
    m_data.load("some_scene.json");
}
</script>
</head>

<body onload="hello()"><canvas id="canvas_id"></canvas></body>

</html>

Примечание

Следует отметить, что реальное приложение должно включать в себя проверку ошибок, настройку движка перед инициализацией, а также базовую систему взаимодействия с пользователем.

Система модулей

Хотя движок предоставляет разработчику приложения API из нескольких десятков модулей, все они занимают единое пространство имён b4w. Для вызова метода нужно сначала подключить соответствующий модуль с помощью функции b4w.require().

Допустима регистрация сторонних модулей, если их имена не пересекаются с имеющимися. Регистрация происходит посредством вызова b4w.register(). Проверка наличия модуля с некоторым именем может быть осуществлена с помощью b4w.module_check().

Пример:

// check if module exists
if (b4w.module_check("my_module"))
    throw "Failed to register module: my_module";

// register my_module
b4w.register("my_module", function(exports, require) {

    // import module "version"
    var m_version = require("version");

    // export print_build_date() from module "my_module"
    exports.print_build_date = function() {
        // exec function date() from module "version"
        console.log("Engine build date: " + m_version.date());
    }
});

// import module "my_module"
var m_my_module = b4w.require("my_module");

// exec function print_build_date() from module "my_module"
m_my_module.print_build_date();

Быстрое создание приложений

Поскольку создание приложения с нуля может быть достаточно сложной операцей, особенно для начинающих пользователей, в движке существует специальное дополнение app:

<!DOCTYPE html>
<html>
<head>
<script src="b4w.min.js"></script>
<script>

var m_app = b4w.require("app");
var m_data = b4w.require("data");

m_app.init({
    canvas_container_id: "container_id",
    callback: load_cb
})

function load_cb() {
    m_data.load("some_scene.json", loaded_cb);
}

function loaded_cb() {
    m_app.enable_camera_controls();
}

</script>
</head>

<body>
    <div id="container_id" style="width: 350px; height: 200px;"></div>
</body>

</html>

В данном случае модуль app создаст элемент <canvas> внутри контейнера с указанным идентификатором container_id, осуществит инициализацию движка при загрузке страницы и сообщит о её окончании с помощью обработчика load_cb().

Далее загружается сцена some_scene.json, аналогично предыдущему примеру, с тем лишь отличием, что по окончании загрузки этой сцены инициализируется подсистема управления и активируются средства для перемещения камеры с помощью клавиатуры и мыши (сенсорного экрана для мобильных устройств).

При использовании модуля app необходимо явно задавать размеры контейнерного элемента, поскольку в противном случае создаваемый элемент <canvas> будет иметь нулевые размеры.

Прозрачный фон

Параметры background_color и alpha передаются в метод init, который вызывается из callback-функции загрузчика (т.е., из функции, которая вызывается сразу после загрузки сцены), например, так:

m_app.init ({
    alpha: true,
    background_color: [0.7, 0.7, 0.7, 1]
   //this method sets the background to an opaque light grey color
});

Комбинация параметров, передаваемых в метод, определяет, как смешиваются цвета приложения Blend4Web и HTML-страницы. Возможны следующие варианты:

  1. alpha = false

    Цвет фона определяется параметром background_color приложения Blend4Web, цвет фона HTML-страницы не принимается в расчёт.

_images/developers_background_opaque.png
  1. alpha = true

    Фон HTML-страницы влияет на фон приложения Blend4Web в зависимости от его прозрачности, выражаемой четвёртой компонентой параметра background_color (alpha = background_color[3], не путать с параметром alpha, упомянутым выше).

    background_color[3] = 1

    Приводит к тому же результату, как если бы прозрачность была отключена (alpha = false)

    background_color[3] = 0

    Используется аддитивное смешение.

    _images/developers_background_add.png

    Изображение выше демонстрирует HTML-страницу, содержащую приложение Blend4Web с синим [0, 0, 1] цветом, который смешивается с красным (Red) цветом фона самой страницы, создавая более светлый оттенок.

    background_color[3] > 0

    Также используется аддитивное смешивание, но цвет background_color имеет большее влияние.

    _images/developers_background_semiopaque.png

    На этом изображении приводится та же HTML-страница с тем же приложением Blend4Web, но параметр alpha имеет значение 0.5, из-за чего фон приложения имеет более тёмный оттенок.

Более подробно смешивание прозрачности описано в главе “Работа с цветом”.

Параметр alpha включен по умолчанию, а в качестве background_color используется прозрачный чёрный цвет [0, 0, 0, 0], т.е. в этом случае в качестве фона приложения используется фон HTML-страницы без какого-либо влияния фона самого приложения.

Прозрачный фон также может использоваться в приложениях для Веб-плеера: в них за прозрачность отвечает URL-атрибут alpha. Для использования этой возможности необходимо при создании приложения активировать параметр Background transparency (alpha) из группы параметров Web Player Params.

При использовании рендеринга неба canvas приложения Blend4Web полностью перекрывается объектами (в т.ч. небом), так что фон приложения будет полность непрозрачным вне зависимости от настроек прозрачности.

Примечание

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

Конвертация ресурсов

Существующие браузеры не полностью поддерживают основные форматы медиаданных, поэтому для создания кроссбраузерных приложений, а также с целью оптимизации, необходимо использовать конвертер ресурсов.

В состав дистрибутива включен Python скрипт (scripts/converter.py) для конвертации исходных файлов в другие форматы с целью расширения спектра поддерживаемых платформ, а также для уменьшения размера ресурсов.

Запустить скрипт можно одним из двух способов.

Во-первых, вы можете воспользоваться менеджером проектов. Кнопка Convert Resources находится на главной странице менеджера проектов, в разделе Operations, расположенном в правой части экрана.

_images/developers_convert_resources.png

Во-вторых, вы можете запустить скрипт вручную:

> cd <path_to_sdk>/scripts
> python3 converter.py [options] resize_textures | convert_dds | convert_media

Для пользователей ОС Windows:

cd <path_to_sdk>\scripts
python converter.py [options] resize_textures | convert_dds | convert_media

Примечание

Стоит отдельно отметить, что для запуска скриптов требуется интерпретатор языка Python версии 3.x

С помощью опции -d можно указать путь к директории, в которой будет производится конвертация.

При необходимости исключить некоторую директорию при конвертации, достаточно разместить в ней файл с именем .b4w_no_conv. На конвертацию во вложенных директориях это не повлияет.

Аргумент resize_textures используется для изменения размера текстур в режиме LOW.

Зависимости

Убедитесь, что у вас установлены все необходимые для конвертации программы. Это можно сделать следующей командой:

> python3 <path_to_sdk>/scripts/converter.py check_dependencies

Если какая-либо программа отсутствует, то будет выведено сообщения вида:

Couldn’t find PROGRAM_NAME.

Linux

Список необходимых программ можно посмотреть в таблице:

Название

Пакет в дистрибутиве Ubuntu 16.04

ImageMagick imagemagick
NVIDIA Texture Tools libnvtt-bin
Libav libav-tools
FFmpeg ffmpeg
PVRTC

устанавливается вручную

Примечание

Пользователи Linux могут дополнительно установить пакет qt-faststart, служащий для оптимизации загрузки медиаданных.

Windows

Для пользователей ОС Windows нет необходимости устанавливать эти пакеты, так как они уже находятся в составе SDK.

macOS

Пользователи mac OS могут установить менеджер пакетов brew, а затем с его помощью установить некоторые недостающие пакеты.

Перед началом установки пакетов произведите установку библиотек libpng и libjpeg, выполнив следующие команды в консоли:

> brew install libpng
> brew install libjpeg

Теперь можно приступать к установке необходимых зависимостей:

> brew install imagemagick
> brew install --with-theora --with-libvpx --with-fdk-aac ffmpeg

Для установки NVIDIA Texture Tools необходимо склонировать репозиторий, выполнив следующую команду:

> git clone https://github.com/TriumphLLC/NvidiaTextureTools.git

Теперь можно произвести сборку и установку пакета:

> cd NvidiaTextureTools
> ./configure
> make
> make install

Форматы данных

Преобразование происходит по схеме:

для аудио (convert_media):
  • ogg (ogv, oga) -> mp4
  • mp3 -> oga
  • mp4 (m4v, m4a) -> oga
  • webm -> m4a

Рекомендуется использовать в качестве базового формата ogg, в этом случае для обеспечения кросс-браузерной совместимости потребуется только преобразование из ogg в mp4. Пример файла на входе: file_name.ogg, пример файла на выходе: file_name.altconv.mp4.

для видео (convert_media):
  • ogg (ogv, oga) -> m4v / seq
  • mp3 -> webm / seq
  • mp4 (m4v, m4a) -> webm / seq
  • webm -> m4v / seq

Рекомендуется использовать в качестве базового формата WebM, в этом случае для обеспечения кросс-браузерной совместимости потребуется только преобразование из webm в m4v (из webm в seq для iPhone). Пример файла на входе: file_name.webm, пример файла на выходе: file_name.altconv.m4v.

для изображений (convert_dds):
  • png -> dds/pvr
  • jpg -> dds/pvr
  • bmp -> dds/pvr
  • gif -> dds

Пример файла на входе: file_name.jpg, пример файла на выходе: file_name.jpg.dds.

В целях оптимизации работы приложения существует возможность использования текстур min50 (уменьшенных вдвое) и текстур в форматах DDS и PRVTC. Для этого при инициализации приложения необходимо передать следующие параметры:

exports.init = function() {
    m_app.init({
        // . . .
        assets_dds_available: true,
        assets_min50_available: true,
        // . . .
    });
    // . . .
}

Примечание

Для использования текстур, сжатых в формате PVRTC, необходимо заменить эту строку кода

assets_dds_available: true,

следующей:

assets_pvr_available: true,

В этом случае движок будет загружать текстуры в формате PVRTC, если они есть в папке ../assets/.

Формат компрессии текстур DDS

Текстуры в формате DDS занимают меньше места в памяти (в 4 раза меньше для изображения в формате RGBA и в 6 раз меньше для изображения в формате RGB), но при их использовании следует иметь в виду, что:

  • Текстуры DDS могут не работать на некоторых устройствах, особенно мобильных, т.к. не все такие устройства поддерживают расширение WEBGL_compressed_texture_s3tc;

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

_images/compression_artifacts.png

Артефакты сжатия формата DDS особенно хорошо заметны на границах тени.

При экспорте сцены из Blender в формат JSON (но не в формат HTML), DDS-текстуры будут подключены автоматически, если они имеются в наличии.

Текстуры могут быть конвертированы в формат DDS с помощью менеджера проектов или с помощью скрипта scripts/converter.py, который был описан выше.

Формат компрессии текстур PVRTC

PVRTC - другой формат компрессии текстур, преимущественно используемый на устройствах iOS. В некоторых случаях он позволяет создавать файлы текстур размером вдвое меньше, чем при использовании формата DDS.

Движок поддерживает два метода сжатия: 2-bpp (два бита на пиксель) и 4-bpp (четыре бита на пиксель).

Как и в случае с форматом DDS, текстуры, сжатые с использованием алгоритма PVRTC, могут не работать на некоторых устройствах, особенно мобильных, так как для корректной работы этого формата сжатия требуется поддержка расширения WebGL IMG_texture_compression_pvrtc.

Библиотеки и SDK PVRTC доступны в версиях для операционных систем Windows, Linux и macOS. Дистрибутивы можно загрузить с веб-сайта Power VR Insider.

Движок Blend4Web использует консольную утилиту PVRTC. Для того, чтобы использовать её, необходимо добавить путь к ней в переменную окружающей среды PATH, например, так:

export PATH = <InstallDir>\PVRTexTool\CLI\<PLATFORM>\

Здесь <InstallDir> - директория, в которой находится PVRTexTool, а <PLATFORM> - папка, содержащая версию утилиты, подходящую для вашей операционной системы, например, \Windows_x86_64\ для 64-битной версии Windows.

Примечание

В Windows переменные окружающей среды можно установить из диалогового окна Система (для Windows 8 и 10) или Свойства (для Windows 7 и Vista), выбрав Дополнительные параметры системы -> Переменные среды, или с помощью консольных команд:

SET PATH = <InstallDir>\PVRTexTool\CLI\<PLATFORM>\

После этого текстуры можно будет преобразовать в формат PVR с помощью команды convert_dds скрипта converter.py.

Формат видео SEQ

Файл формата .seq представляет собой раскадрированное видео. Применяется на IE 11 и iPhone, поскольку на них возникают трудности при использовании видео стандартного формата в качестве текстуры. Использование dds-формата для изображений является более оптимальным по сравнению с другими форматами.

Движком могут использоваться файлы, созданные пользователем вручную и имеющие следующие наименования: file_name.altconv.m4v, file_name.altconv.mp3 и т.д. Такие файлы необходимо размещать в одной директории с медиафайлом, используемым в Blender’e.

Вы также можете использовать бесплатную кроссплатформенную программу Miro Video Converter для конвертации медиаданных.

Примеры кода

В составе SDK присутствует приложение Code Snippets, демонстрирующее примеры использования функционала движка.

На данный момент приложение включает в себя следующие примеры:

  • Bone API - пример управления положением отдельных костей скелета

  • Camera Animation - создание процедурной анимации камеры

  • Camera Move Styles - переключение режимов управления камерой

  • Canvas Texture - пример работы с canvas-текстурой

  • Change Image - пример изменения текстуры на лету

  • Custom Anchors - процедурное создание аннотаций

  • Dynamic Geometry - процедурное изменение геометрии

  • Gamepad - пример управления персонажем с помощью геймпада

  • Gyro (Mobile Only) - пример работы с гироскопом мобильных устройств

  • Instancing - копирование объектов сцены

  • Lines - рендеринг процедурных линий

  • Material API - изменение свойств материалов и замена материалов объекта

  • Morphing - использование ключей деформации объекта

  • Multitouch (только для мобильных устройств) - использование мультитач-сенсора

  • Pathfinding - рассчёт пути с использованием навигационного меша

  • Ray Test - использование функционала испускания лучей для определения препятствий

  • Webcam - пример использования потока медиаданных с веб-камеры

Приложение Code Snippets доступно по пути ./apps_dev/code_snippets/code_snippets_dev.htm. Также оно доступно по ссылке из файла index.html в корне SDK.

Загрузка медиаресурсов приложения.

Для упрощения обслуживания проектов и развертывания сервера храните медиаданные приложений (сцены, текстуры, звуки и т.п.) отдельно от прочих файлов проекта (JavaScript, CSS, HTML и пр.). Папка медиаресурсов располагается по адресу deploy/assets/my_project в каталоге SDK.

Для загрузки файлов из директории (например, с помощью метода load()) используйте метод get_std_assets_path():

m_data.load(m_config.get_std_assets_path() + "my_project/my_project.json", load_cb);

Такой подход гарантирует, что приложение (как разрабатываемое, так и собранное или развёрнутое) сможет загружать медиаресурсы вне зависимости от того, на какой стадии разработки оно находится.

Событийная модель

Событийная модель предоставляет унифицированный интерфейс для описания изменения состояний 3D сцены, упрощая обработку событий физики и действий пользователя.

Сенсоры

Основным блоком событийной модели является сенсор (sensor). Сенсор является программной сущностью, которая выдаёт на выходе единственное числовое значение, в большинстве случаев это либо 1 (единица), либо 0 (ноль). Некоторые сенсоры также несут полезную нагрузку (payload), которую можно получить в фунции-обработчике множества с помощью соответствующего API. Например, сенсор трассировки лучей (Ray Sensor) предоставляет относительную длину луча пересечения.

Опрос значений сенсоров не доступен пользователю в виде API. Вместо этого, каждый сенсор должен присутствовать в одном или нескольких множествах (sensor manifold). Множество является логическим контейнером, ассоциированным с объектом на сцене. Оно генерирует ответ на определенный набор событий сенсоров в виде вызова функции-обработчика. Для определения множества необходимо иметь следующую информацию (см. также описание функции create_sensor_manifold в документации по API):

  • Объект-носитель множества (например, бросаемый объект).

  • Уникальный идентификатор множества (например, “IMPACT”).

  • Тип вызова функции-обработчика (варианты: CT_POSITIVE - положительный результат логической функции, CT_CONTINUOUS - каждый кадр при положительном результате логической функции и один раз при нулевом, CT_LEVEL - любое изменение значения результата логической функции, CT_SHOT - одномоментный скачок результата логической функции, CT_TRIGGER - переключение результата логической функции, CT_CHANGE - любое изменение любого из сенсоров).

  • Массив сенсоров.

  • Логическая функция, определяющая при какой комбинации состояний сенсоров вызывается функция-обработчик.

  • Функция-обработчик.

  • Необязательный параметр, который может быть передан в функцию-обработчик.

Более подробно об API, используемых в событийной модели движка, описано в документации модуля controls.

Пример

Поставлена задача озвучить удар бросаемого камня так, чтобы при ударе о различные среды (например, земля и стена) выводился характерный звук. На сцене в Blender’е имеются ограничивающие меши с физическими материалами, их идентификаторы “TERRAIN” и “WALL”. На сцене также присутствует бросаемый физический объект с названием “Stone”.

Определим по одному сенсору соударения (Collision Sensor) для каждой среды, по типу издаваемого звука.

// import the modules
var m_scenes = b4w.require("scenes");
var m_controls = b4w.require("controls");

// get the object being thrown
var stone = m_scenes.get_object_by_name("Stone");

// create the sensors
var sensor_impact_terrain = m_controls.create_collision_sensor(stone, "TERRAIN");
var sensor_impact_wall    = m_controls.create_collision_sensor(stone, "WALL");

Добавим сенсоры в массив. В качестве логической функции используем логическое ИЛИ. В обработчике напишем код для воспроизведения звука. Создадим множество сенсоров с идентификатором “IMPACT” и типом CT_SHOT (одномоментный).

// array of the sensors
var impact_sens_array = [sensor_impact_terrain, sensor_impact_wall];

// manifold logic function
var impact_sens_logic = function(s) {return (s[0] || s[1])};

// callback
var impact_cb = function(obj, manifold_id, pulse) {

    // NOTE: it's possible to play both sounds simultaneously

    if (m_controls.get_sensor_value(obj, manifold_id, 0) == 1) {
        // ...
        console.log("play the terrain impact sound");
    }

    if (m_controls.get_sensor_value(obj, manifold_id, 1) == 1) {
        // ...
        console.log("play the wall impact sound");
    }
}

// create the manifold
m_controls.create_sensor_manifold(stone, "IMPACT", m_ctl.CT_SHOT,
    impact_sens_array, impact_sens_logic, impact_cb);

При столкновении объекта “Stone” с любым из физических материалов “TERRAIN” или “WALL” происходит вызов функции-обработчика. Внутри этой функции получим значения обоих сенсоров по их индексу в массиве сенсоров (0 - “TERRAIN”, 1 - “WALL”). Значение сенсора = 1 (активный) означает, что произошло столкновение с соответствующим физическим материалом. В результате воспроизводится соответствующий звук (код не показан).

Файловая структура SDK

addons
blend4web

аддон Blender

apps_dev

исходный код приложений SDK

code_snippets

исходные файлы приложения Code Snippets

scripts

исходные файлы самих примеров использования API Blend4Web

dairy_plant

исходные файлы приложения “Молочный завод” (доступно только в SDK Pro)

demos_animation

исходные файлы анимационных примеров

demos_environment

исходные файлы примеров работы с окружающей средой

demos_interactivity

исходные файлы примеров интерактивности

demos_materials

исходные файлы примеров материалов

demos_media

исходные файлы примеров работы с медиаресурсами

demos_particles

исходные файлы примеров работы с частицами

demos_physics

исходные файлы примеров работы с физикой

demos_postprocessing

исходные файлы примеров работы со спецэффектами

farm

исходные файлы приложения “Ферма” (доступно только в SDK Pro)

fashion

исходные файлы приложения “Показ мод” (доступно только в SDK Pro)

flight

исходные файлы приложения “Остров”

new_year

исходные файлы открытки “С новым годом 2015”

project.py

скрипт для разработчиков приложений

space_disaster

исходные файлы приложения Space Disaster

tutorials

исходные файлы обучающих примеров Blend4Web

victory_day_2015

исходные файлы открытки “День победы 70”

viewer

исходные файлы приложения для просмотра сцен Viewer

webplayer

исходные файлы веб-плеера

website

исходные файлы приложений, размещаемых на официальном сайте Blend4Web

blender

исходные файлы сцен в формате Blender

csrc

исходный код бинарной части экспортера движка и других утилит на языке C

deploy

директория с ресурсами для размещения на сервере (исходные файлы сцен, скомпилированные приложения и документация)

api_doc

документация API движка для разработчиков (собирается автоматически, на основе исходного кода движка)

apps

3D-приложения, предназначенные для развертывания, директория дублирует apps_dev

common

Файлы скомпилированного движка. Используются приложениями из состава SDK (отсюда и название).

assets

медиаданные приложения: сцены, текстуры, звуковые файлы

doc

настоящее руководство пользователя в формате HTML, собирается автоматически из doc_src

webglreport

Приложения, выводящее информацию о WebGL

distfiles

списки сборщика дистрибутивов

doc_src

исходный код настоящего руководства пользователя на языке разметки reST

index.html и index_assets

файлы главной веб-страницы SDK

license

файлы с текстами лицензионных соглашений

Makefile

файл сборки для компиляции движка, приложений и документации

README.rst

файл README

scripts

скрипты

check_resources.py

скрипт для проверки и сообщения о неиспользуемых ресурсах (изображения и звуки, на которые ссылаются экспотируемые файлы)

compile_b4w.py

скрипт для сборки кода движка и приложений

converter.py

скрипт, осуществляющий: уменьшение разрешения текстур вдвое, компрессию текстур в формат DDS, конвертацию звуковых файлов в форматы mp4 и ogg

custom_json_encoder.py

форк Python-модуля json, сортирует ключи по алфавиту в обратном порядке

gen_glmatrix.sh

скрипт для генерации математического модуля на основе исходных файлов из репозитория glMatrix 2

graph.sh

генератор текущего графа сцены в формате svg, используется для отладки рендеринга

make_dist.py

сборщик дистрибутивов

memory.sh

скрипт для проверки обычной (RAM) и видео-памяти (VRAM)

mod_list.py

скрипт для генерации списка модулей, используемых в приложениях

plot.sh

построитель графиков отладочной информации

process_blend.py

скрипт для автоматического переэкспорта всех сцен из состава SDK

remove_alpha_channel.sh

скрипт для удаления альфа-канала изображения

screencast.sh

скрипт для записи видео с экрана

shader_analyzer.py

скрипт, запускающий локальный веб-сервер, который осуществляет подсчет сложности шейдеров

translator.py

скрипт для сборки файлов с переводами аддона

shaders

GLSL-шейдеры движка

src

основной исходный код ядра движка

addons

исходный код дополнений движка

ext

исходный код внешних объявлений, формирующих API движка

libs

исходный код библиотек

tmp
directory for temporary files (e.g. Fast Preview)
tools

различные инструменты для сборки движка, приложений и конвертации ресурсов

converter_utils

сборки утилит для конвертации ресурсов

closure-compiler

компилятор Google Closure, файлы исключений к нему, генераторы файлов исключений

glsl
compiler

компилятор GLSL-шейдеров движка

pegjs

грамматики парсер-генератора PEG.js для реализации препроцессора GLSL, а также скрипт для генерации модулей парсеров из этих грамматик

yuicompressor

утилита для сжатия файлов CSS

uranium

исходный код и скрипты сборки физического движка Uranium (форк Bullet)

VERSION

содержит текущую версию движка

Загрузка локальных ресурсов

Рендерер движка является Web-приложением, и его работа происходит при просмотре HTML-файла в браузере. После инициализации происходит загрузка ресурсов (сцен, текстур), которая подчиняется правилу ограничения домена, запрещающему, в частности, загрузку из локальной директории.

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

Профили качества изображения

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

  • низкое качество (P_LOW) - отключен ряд функций (тени, динамическое отражение, постпроцессинг), размер текстур для сборочной версии уменьшен вдвое, антиалиасинг отключен

  • высокое качество (P_HIGH) - используются все запрошенные сценой функции, метод антиалиасинга FXAA

  • максимальное качество (P_ULTRA) - вдвое увеличено разрешение рендеринга, увеличено разрешение карт теней, метод антиалиасинга SMAA (используется более высокое качество, скорость работы ниже).

  • пользовательское качество (P_CUSTOM) - любой параметр качества может иметь любое доступное значение. Используется, если необходимо вручную задать некоторые параметры. По умолчанию используются настройки, аналогичные профилю High.

_images/developers_quality.png

Переключение профилей качества осуществляется программно, до инициализации контекста WebGL. Профиль по умолчанию P_HIGH.

var m_cfg = b4w.require("config");
var m_main = b4w.require("main");

m_cfg.set("quality", m_cfg.P_LOW);
m_main.init(...);

Разработчики приложений могут также установить параметр quality при инициализации движка с использованием дополнения app.js:

var m_cfg = b4w.require("config");
var m_app = b4w.require("app");

m_app.init({
    canvas_container_id: "body_id",
    quality: m_cfg.P_HIGH
});

Специфика неполноэкранных приложений

Элемент Canvas, на котором осуществляется рендеринг, может изменять своё местоположение относительно окна браузера. Это может происходить в результате манипуляций, проводимых над DOM-деревом, либо в результате скроллинга страницы, что особенно актуально для неполноэкранных приложений.

В большинстве случаев это не будет никак сказываться на работе приложения. Однако для событий, связанных с положением курсора мыши или позицией касания на touch-устройстве, возможно получение некорректных результатов. Это происходит, потому что координаты, получаемые из соответствующих событий, принадлежат системе отсчета относительно окна браузера, а движок работает с координатами в системе отсчета именно Canvas элемента (верхний левый угол элемента).

  1. Если верхний левый угол Canvas’а совпадает с верхним левым углом окна браузера, и его местоположение не будет изменяться, то достаточно использовать координаты event.clientX и event.clientY соответствующего события либо функции API get_coords_x() и get_coords_y():

var m_mouse   = require("mouse");

// . . .
var x = event.clientX;
var y = event.clientY;
// . . .
var x = m_mouse.get_coords_x(event);
var y = m_mouse.get_coords_y(event);
// . . .
  1. Если на странице присутствует только скроллинг окна браузера, то достаточно использовать координаты event.pageX и event.pageY:

// . . .
var x = event.pageX;
var y = event.pageY;
// . . .
  1. В случае более сложных манипуляций с положением элемента Canvas (скроллинг отдельных элементов страницы, смещение относительно левого верхнего угла окна браузера, манипуляции с DOM-деревом) требуется корректный пересчет координат. Чтобы получить координаты, подходящие для использования в движке, можно провести преобразование при помощи метода client_to_canvas_coords():

var m_cont   = require("container");
var _vec2_tmp = new Float32Array(2);
// . . .
var canvas_xy = m_cont.client_to_canvas_coords(event.clientX, event.clientY, _vec2_tmp);
// . . .

Для получения координат в системе отсчета Canvas элемента, движок должен знать его положение относительно окна браузера. Однако, если оно будет меняться во время работы приложения (тот же скроллинг), то необходимо будет как-то пересчитывать позицию Canvas’а. Для того, чтобы это происходило автоматически, нужно выставить настройку track_container_position при инициализации приложения:

exports.init = function() {
    m_app.init({
        // . . .
        track_container_position: true,
        // . . .
    });
    // . . .
}

При её использовании в некоторых браузерах (например, Firefox) возможно незначительное снижение производительности вследствие частого обращения к DOM-дереву. Если этот момент критичен, то вместо флага track_container_position можно пользоваться методами force_offsets_updating(), update_canvas_offsets() или более низкоуровневым set_canvas_offsets() для обновления положения элемента Canvas вручную, когда это действительно необходимо:

var m_cont = require("container");
// . . .
m_cont.force_offsets_updating();
// . . .
m_cont.update_canvas_offsets();
// . . .
m_cont.set_canvas_offsets(offset_left, offset_top);
// . . .

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

<meta name="viewport" content="user-scalable=no">