EventDispatcher

App

Класс App позволяет упростить настройку 3Д-приложения. Он включает код для инициализации WebGL-рендерера, загрузки glTF-сцен, автоматического запуска анимации, а также логику для основных элементов управления камерой.

Пример

// загружаемый glTF-ассет const url = 'template.gltf'; // создать приложение с простым крутящимся прелоадером const app = new v3d.App('v3d-container', null, new v3d.SimplePreloader({ container: 'v3d-container' })); // загрузить главную сцену app.loadScene(url, function() { app.enableControls(); app.run(); runCode(); }); function runCode() { // поместите ваш код здесь }

Конструктор

App(container : String | HTMLElement, ctxSettings : Object, preloader : Preloader)

container
Идентификатор HTML-элемента или сам HTML-элемент для размещения холста ("3Д-холста").
ctxSettings
Атрибуты контекста WebGL, которые должны быть переданы в методе canvas.getContext():
alpha
Использовать прозрачный холст. По умолчанию false.
antialias
Использовать мультисампловый анти-алиасинг (MSAA). По умолчанию true.
depth
Использовать буфер глубины. По умолчанию true.
desynchronized
Создать рассинхронизированный контекст для CAD-приложений. По умолчанию false.
failIfMajorPerformanceCaveat
Не разрешать использование медленного 3Д-контекста (например в случае программной отрисовки). По умолчанию false.
powerPreference
Предпочитать мощный ("high-performance") или слабый ("low-power") графический процессор для систем с 2-мя GPU. По умолчанию "default".
premultipliedAlpha
Премультиплицировать альфа-канал во время рендеринга. По умолчанию true.
preserveDrawingBuffer
Сохранять содержимое 3Д-контекста между кадрами. По умолчанию false.
stencil
Разрешить использование буфера шаблонов (stencil). По умолчанию true.
xrCompatible
Разрешить использование технологии виртуально и дополненной реальности WebXR. По умолчанию false.
preloader
Экземпляр класса Preloader приложения.

Этот конструктор делает следующее:

  1. Создает новый элемент контейнера (если необходимо).
  2. Проверяет, поддерживается ли технология WebGL, если нет, выводит диалог об ошибке.
  3. Инициализирует часы приложения.
  4. Создает новый 3Д-холст с контекстом WebGL 1.0 или WebGL 2.0 и добавляет его к элементу контейнера.
  5. Инициализирует загрузчик glTF.
  6. Подготавливает модуль текстурной компрессии.
  7. Инициализирует методы ускоренной трассировки лучей (BVH).
  8. Добавляет экземпляр приложения в список v3d.apps (в случае немодулированного движка).

Свойства

.aaMethod : String

Метод анти-алиасинга, используемый для улучшения визуального качества сцены:

Это значение устанавливается методом .loadScene, поэтому должно использоваться только для чтения.

.actions : Array

Массив actions, используемый для планирования анимаций приложения. Вместо прямого доступа к этому списку можно также использовать метод SceneUtils.getAnimationActionByName для поиска действия по имени клипа.

.camera : Camera

Главная камера приложения.

.clearBkgOnLoad : Boolean

Устанавливает фон сцены на null после загрузки сцены glTF. По умолчанию false.

.clock : Clock

Объект часов приложения.

.container : HTMLElement

Элемент контейнера. Это родительский элемент для 3Д-холста, используемого для рендеринга сцены.

.compileCallbacks : Array

Массив функций, которые будут вызваны непосредственно перед компиляцией шейдера. Компиляция шейдеров происходит во время загрузки сцены, сразу после того, как все ассеты (метаданные glTF, бинарные файлы, текстуры) были получены.

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

function initFog(appInstance) { appInstance.scene.fog = new v3d.FogExp2('green', 0.01); } // загружаемый glTF 2.0 ассет const url = 'my_scene.gltf'; // создать приложение с простым крутящимся прелоадером const app = new v3d.App('v3d-container', null, new v3d.SimplePreloader({ container: 'v3d-container' })); // инициализировать туман перед загрузкой сцены app.compileCallbacks.push(initFog); // загрузить главную сцену app.loadScene(url, function() { app.enableControls(); app.run(); });

.controls : Object

Объект управления главной камерой приложения. Используйте метод .enableControls для установки этого значения.

.disableRenderTrigger : Integer

Используется в работе метода .disableRendering. Не изменять!

.elapsed : Float

Время в секундах прошедшее с предыдущего кадра.

.enableRender : Boolean

Только для чтения. Свойство установлено в true если рендеринг включён, иначе false. Для непосредственного включения/выключения рендеринга используются методы .enableRendering и .disableRendering.

.frame : Integer

Текущий кадр рендеринга приложения.

.frameRateDivider : Integer

Делитель FPS приложения. Используйте .setFrameRateDivider для установки этого значения.

.loader : GLTFLoader

glTF-загрузчик приложения.

.mixer : AnimationMixer

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

.preloader : Preloader

Элемент предзагрузки приложения (существует только во время загрузки сцены)

.registerServiceKeys : Boolean

Зарегистрировать сервисные комбинации клавиш, например тройную тильду (~~~) для показа сервисного меню. По умолчанию true. Если вам необходимо выключить сервисные комбинации, установите это значение в false сразу после создания экземпляра класса App.

const app = new v3d.App(containerId, ctxSettings, preloader); app.registerServiceKeys = false;

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

.renderCallbacks : Array

Массив функций, которые будут вызываться каждый раз, когда начинается очередной кадр рендеринг.

.renderer : WebGLRenderer

Рендерер WebGL-приложения.

.scene : Scene

Главная сцена приложения.

.ssaaOnPause : Boolean

Запускать SSAA (суперсемплинг) в момент паузы. По умолчанию false.

.stats : Stats

Инстанс класса статистики, используемый для отображения счётчика кадров. Создаётся и уничтожается с помощью методов .showFPS и .hideFPS.

.useHDR : Boolean

Показывает, включен или нет рендеринг с высоким динамическим диапазоном (HDR). HDR-рендеринг включён когда а) он запрошен в главном glTF-ресурсе приложения и б) он поддерживается на оборудовании пользователя.

.worldCubemapRes : Number

Разрешение кубической текстуры, представляющей материал мира. Значение по умолчанию — 1024.

.xrCameraParent : Object3D

Родительский объект камеры, используемый для перемещения этой камеры в WebXR-сессии.

.xrControllers : Array

Массив объектов контроллера для активной сессии WebXR.

.xrSession : XRSession

Активная сессия WebXR. Не устанавливайте сессию напрямую, используйте метод .initWebXR.

Методы

.animate()

Обработчик обновлений сцены: рендеринга, анимации и управления камерой. Обычно этот обработчик не требует изменения.

.appendScene(url : String, loadCb : Function, progressCb : Function, errorCb : Function, loadCameras : Boolean, loadLights : Boolean)

Добавляет сцену из указанного файла glTF к текущей сцене. loadCb получит загруженную сцену в качестве параметра после завершения загрузки.

Если в приложении нет активной сцены, то ничего добавлено не будет.

Такие параметры, как loadCameras и loadLights, используются для указания того, будут ли камеры и освещение добавлены из загруженной сцены. По умолчанию оба эти параметра имеют значение true.

.assignClippingPlanes(scene : Scene)

Подготовить плоскости отсечения для данной сцены.

.disablePostprocessing(keepOutline : Boolean, keepGTAO : Boolean)

Отключить все эффекты постобработки (кроме контура, когда keepOutline=true и эмбиент окклюжн, когда keepGTAO=true).

.disableRendering(after : Integer)

Отключает обновление графики в цикле анимации после заданного количества кадров (укажите 0, чтобы отключить сразу). Элементы управления и микшер анимации будут продолжать обновляться, а обратные вызовы рендеринга - вызываться.

.dispose()

Выгружает сцену (вызывая unload) и утилизирует приложение, что включает очистку рендерера приложения и удаление элемента холста из DOM. Также отправляет сообщение dispose.

После утилизации приложение больше не может использоваться. Этот способ лучше всего подходит для случаев, когда требуется полная очистка.

.disposeEnvironment()

Удаляет буферы фона и окружения.

.enableControls(element : HTMLElement)

Включает элементы управления для главной камеры приложения. В зависимости от типа управления, указанного для камеры, этот метод предоставит вам 'ORBIT', 'FLYING' или статичную камеру.

Необязательный параметр element используется для указания элемента, получающего события мыши/клавиатуры/тачскрина. Если элемент не указан, события будет назначены на элементе WebGLRenderer.domElement рендерера приложения.

.enablePostprocessing(effects : Array)

Включает заданные эффекты постобработки. Эффекты задаются в виде следующих объектов:

Afterimage
{ type: 'afterimage', damp: 0.85 }
Bloom
{ type: 'bloom', threshold: 0.8, strength: 0.3, radius: 0.5 }
Brightness/Contrast
{ type: 'brightnessContrast', brightness: 0.1, contrast: 0.3 }
DOF
{ type: 'dof', focus: 10, aperture: 1, maxblur: 0.001, depthLeakThreshold: 0.2 }
Grayscale
{ type: 'grayscale' }
GTAO
{ type: 'gtao', distance: 0.2, factor: 1.0, precision: 0.250, bentNormals: true, bounceApprox: true }
Outline
{ type: 'outline', edgeStrength: 3.0, edgeGlow: 0.0, edgeThickness: 1.0, pulsePeriod: 0.0, visibleEdgeColor: new Vector4(1, 1, 1, 1), hiddenEdgeColor: new Vector4(0.1, 0.04, 0.02, 1) }
SSR (отражение или рефракция)
{ type: 'ssr', useRefract: false, objects: [], steps: 100, stride: 5, binarySearchSteps: 4, thickness: 0.01, maxDistance: 100, renderTargetScale: 0.5, jitter: 0.1, renderAfter: [] }

.enableRendering()

Включает обновление графики в цикле анимации.

.enableSSAA(sampleLevel, iterative)

Включить сглаживание. Количество выборок рассчитывается как 2^sampleLevel (например, укажите 4, чтобы включить 16x SSAA).

.endWebXR()

Завершает сессию WebXR.

.generateRTargetPMREM(cubeRT : WebGLRenderTarget) → WebGLRenderTarget

Конвертирует рендер-таргет указанный в cubeRT в рендер-таргет формата PMREM. Этот метод вызывается методом .updateEnvironment и редко требуется сам по себе.

.getCamera(tryXrIfAvail : Boolean) → Camera

Возвращает главную камеру приложения. Рекомендуется использовать этот метод вместо свойства .camera поскольку он работает как в обычном режиме, так и для сессии WebXR (ВР/ДР). Чтобы вернуть камеру, используемую в WebXR, подайте tryXrIfAvail=true.

.getHeight() → Float

Возвращает рассчитанную высоту элемента контейнера.

.getWidth() → Float

Возвращает рассчитанную ширину элемента контейнера.

.hideFPS()

Скрывает счетчик частоты кадров.

.initWebXR(mode : String, referenceSpaceType : String, successCb : Function, failureCb : Function, exitCb : Function, options : Object)

Инициализирует сессию WebXR (виртуальная и дополненная реальность).

.loadScene(url : String, loadCb : Function, progressCb : Function, errorCb : Function)

Загружает glTF-сцену. Коллбек loadCb получит загруженную сцену в качестве параметра после завершения загрузки. Метод отправляет сообщение sceneLoad.

Если активная сцена уже существует (например, загружена ранее с помощью метода .loadScene), используйте unload, чтобы избежать конфликтов между существующей и загруженной сценами.

.onResize()

Обработчик события изменения размеров холста. Не изменяйте этот обработчик, если не знаете, что делаете. Если вам необходимо добавить свою логику в момент изменения размеров, делайте как на примере ниже:

const onResizeOld = app.onResize; app.onResize = function() { // вызвать старый onResizeOld.call(app); // ваш код console.log("Размеры изменились!"); }

.pause()

Ставит приложение на паузу, включая анимацию, контролы, рендер-коллбеки и рендеринг. Отправляет событие pause.

.printPerformanceInfo(delta)

Оценивает и распечатывает профиль производительности рендеринга. delta — необязательный параметр, определяющий период оценки в секундах (по умолчанию 1).

.render()

Обработчик для рендеринга сцены. Не изменяйте его, если не знаете, что делаете. Отправляет события beforeRender и afterRender.

.resume()

Убирает приложение с паузы, включая анимацию, контролы, рендер-коллбеки и рендеринг. Отправляет событие resume.

.run()

Запускает приложение, удаляя прелоадер и запуская цикл рендеринга.

.setCamera(camera : Camera) → Camera

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

.setFrameRateDivider(divider : Integer)

Уменьшает максимальный кадр, деля его на заданное целое число. По умолчанию движок пытается рендерить сцены со скоростью 60 кадров в секунду. Если делитель установлен, например, на 2, FPS будет снижен до 30.

.showFPS()

Показать счетчик частоты кадров.

.unload(rootObj)

rootObj — (необ.) объект для выгрузки вместе с его дочерними объектами; если объект не задан или заданный объект является основной сценой приложения, метод выполняет полную очистку сцены.

Выгружает либо часть, либо всю сцену в зависимости от параметра.

Если заданный rootObj является одним из объектов сцены, то этот метод удаляет данный объект и его потомков из сцены, а также освобождает связанные с ним ресурсы (геометрию, материалы, текстуры и т.д.). Если данный rootObj является самим экземпляром сцены, то этот метод выполняет полную очистку сцены, которая включает удаление всех объектов, окружения сцены, камер и элементов управления камерами, анимации, постобработки, внутренних объектов WebGL и т.д.

После того как сцена приложения была полностью выгружена, метод .loadScene может быть использован для загрузки новой сцены. Этот подход лучше подходит для загрузки/выгрузки сцен без удаления самого приложения.

.updateConstraints(scene : Scene)

Обновляет ограничители на сцене. Обычно вам не нужно вызывать этот метод напрямую, поскольку все ограничители обновляются при загрузке сцены (в методах .loadScene и .appendScene).

.updateEnvironment(wMat)

Обновление мирового окружения на основе материала, указанного в качестве параметра. Данный материал обычно хранится в свойстве сцены Scene.worldMaterial.

.updateReflectionProbes(object3d)

object3d — объект или сцена для поиска объектов-зондов среди его потомков.

Обновить все объекты CubeReflectionProbe, которые являются преемниками данного объекта object3d.

События

afterFirstRender

Событие отправляемое сразу после отрисовки первого кадра. Вы можете подписаться на него следующим образом:

app.addEventListener('afterFirstRender', e => ...); // свойства объекта е: type ('afterFirstRender'), target (экземпляр App)

afterRender

Событие отправляемое после каждого кадра (in the beginning of the render method). Вы можете подписаться на него следующим образом:

app.addEventListener('afterRender', e => ...); // свойства объекта е: type ('afterRender'), target (экземпляр App)

beforeRender

Событие отправляемое до каждого кадра (in the end of the render method). Вы можете подписаться на него следующим образом:

app.addEventListener('beforeRender', e => ...); // свойства объекта е: type ('beforeRender'), target (экземпляр App)

dispose

Событие отправляемое сразу после уничтожения приложения методом dispose. Вы можете подписаться на него следующим образом:

app.addEventListener('dispose', e => ...); // свойства объекта е: type ('dispose'), target (экземпляр App)

pause

Событие отправляемое когда приложение ставится на паузу методом pause. Вы можете подписаться на него следующим образом:

app.addEventListener('pause', e => ...); // свойства объекта е: type ('pause'), target (экземпляр App)

resume

Событие отправляемое когда приложение убирается с паузы методом resume. Вы можете подписаться на него следующим образом:

app.addEventListener('resume', e => ...); // свойства объекта е: type ('resume'), target (экземпляр App)

sceneLoad

Событие отправляемое после того как сцена приложения загружена, осуществлён парсинг и компиляция шейдеров. Это событие отправляется методом loadScene. Вы можете подписаться на него следующим образом:

app.addEventListener('sceneLoad', e => ...); // свойства объекта е: type ('sceneLoad'), target (экземпляр App)

Пазлы

Для управления приложением «Вержд3Д» поддерживает ряд пазлов:

Исходный файл

Исходный файл модуля приложения доступен по следующему пути src/extras/App.js внутри установочной папки «Вердж3Д».