App — Руководство по Вердж3Д — Софт Эйт Софт
Description: App это класс содержащий базовый код для создания и управления Вердж3Д-приложениями.

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`.
preloader
  Экземпляр класса Preloader приложения.

Конструктор экземпляра приложения. Этот конструктор делает следующее:

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

## Свойства

### # .aaMethod : String

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

- 'AUTO'
- 'MSAA4'
- 'MSAA8'
- 'MSAA16'
- 'FXAA'

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

### # .actions : Array

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

### # .camera : Camera

Главная камера приложения. Если вы хотите поменять главную камеру, не заменяйте это свойство. Вместо этого воспользуйтесь методом .setCamera.

### # .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 для установки этого значения.

### # .cssRenderer : CSS3DRenderer

CSS-рендерер приложения. Значение по умолчанию `null` указывает на то, что приложение не содержит CSS-трансформируемых объектов. Это свойство не следует назначать напрямую, вместо этого следует использовать метод .enableCSSRenderer.

### # .cssScene : Scene

Сцена, содержащая объекты CSS-рендерера. Значение по умолчанию `null` указывает на то, что приложение не содержит CSS-трансформируемых объектов. Это свойство не следует назначать напрямую, вместо этого следует использовать метод .enableCSSRenderer.

### # .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 : Integer

Разрешение кубической текстуры, представляющей материал мира. Значение по умолчанию — `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)

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

### # .disableCSSRenderer()

Очищает экземпляры .cssRenderer и .cssScene и возвращает контролы приложения в нормальное состояние.

### # .disablePostprocessing(keepOutline : Boolean, keepGTAO : Boolean)

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

### # .disableRendering(after : Integer)

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

### # .dispose()

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

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

### # .disposeEnvironment()

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

### # .enableControls(element : HTMLElement)

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

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

### # .enableCSSRenderer()

Создаёт новые экземпляры классов .cssRenderer и .cssScene и перенастраивает контролы приложения для работы с CSS-трансформируемыми объектами.

Этот метод обычно вызывается пазлом create object → plane with html.

### # .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)

- mode — `"immersive-vr"` для ВР-сессии, `"immersive-ar"` для ДР-сессии.
- referenceSpaceType — один из `"viewer"`, `"local"`, `"local-floor"`, `"bounded-floor"`, `"unbounded"`.
- successCb — коллбек, вызываемый в случае успеха.
- failureCb — коллбек, вызываемый в случае неудачи.
- exitCb — коллбек, вызываемый в момент окончания WebXR-сессии.
- options — объект-словарь с дополнительными параметрами, такими как `domOverlay` чтобы разрешить использование HTML вёрстки в ДР-сессии.

Инициализирует сессию 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Д» поддерживает ряд пазлов:

- configure application — чтобы настроить процесс инициализации приложения.
- load scene — чтобы загрузить новую сцену.
- append scene — чтобы добавить сцену к приложению.
- enable rendering/disable rendering — чтобы включить/выключить рендеринг (с возможностью анти-алиасинга).
- postprocessing — чтобы включить-выключить тот или иной эффект постобработки.

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

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