GLTFLoader - Руководство по Вердж3Д - Софт Эйт Софт
Description: Узнайте как использовать GLTFLoader в интерактивных 3Д-веб-приложениях сделанных на Вердж3Д

Loader →

# GLTFLoader

Загрузчик для ресурсов glTF 2.0.

glTF (GL Transmission Format) — это спецификация открытого формата для эффективной доставки и загрузки 3Д-контента. Ассеты могут предоставляться как в формате JSON (.gltf), так и в бинарном формате (.glb) (оба поддерживают компрессию LZMA). Внешние файлы хранят текстуры (.jpg, .png, .webp, .hdr) и дополнительные двоичные данные (.bin). Ассет glTF может предоставлять одну или несколько сцен, и включать меши, материалы, текстуры, скины, скелеты, морфинг, анимацию, свет, световые зонды, шрифты и камеры.

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

Чаще всего GLTFLoader вам не потребуется использовать напрямую. Вместо этого используйте метод App.loadScene и App.appendScene, скрывающие сложность обработки ассетов в формате glTF 2.0.

## Расширения

GLTFLoader поддерживает следующие S8S-расширения glTF 2.0:

- S8S_v3d_animation
- S8S_v3d_camera
- S8S_v3d_materials
- S8S_v3d_mesh
- S8S_v3d_node
- S8S_v3d_scene
- S8S_v3d_texture
- S8S_v3d_lights
- S8S_v3d_light_probes
- S8S_v3d_curves
- S8S_v3d_clipping_planes

А также стандартные расширения glTF 2.0:

- KHR_materials_unlit
- KHR_texture_basisu
- EXT_texture_webp

## Пример

`// создаёт экземпляр загрузчика const loader = new GLTFLoader(); // загружает glTF-ресурс loader.load( // УРЛ 'duck.gltf', // вызывается когда ресурс загружен function(gltf) { app.scene.add(gltf.scene); gltf.animations; // массив v3d.AnimationClip gltf.scene; // v3d.Scene gltf.scenes; // массив v3d.Scene gltf.cameras; // массив v3d.Camera gltf.asset; // object gltf.world; // object }, // прогресс function(xhr) { console.log((xhr.loaded / xhr.total * 100) + '% loaded'); }, // вызывается в случае ошибок function(error) { console.log('An error happened'); } );`

## Текстуры

Текстуры, содержащие информацию о цвете (напр. MeshStandardMaterial.map), всегда используют цветовое пространство sRGB, тогда как вертексные цвета и параметры материалов (напр. MeshStandardMaterial.color) используют линейное пространство. В типовом случае рендеринга, все текстуры конвертируются в линейное пространство, далее в этом производятся расчёты освещения, после чего результат конвертируется обратно в sRGB. За исключением случаев, когда требуется производить пост-обработку в линейном пространстве, всегда выставляйте пространство WebGLRenderer при использовании формата glTF в:

`renderer.outputEncoding = v3d.sRGBEncoding;`

GLTFLoader автоматически установит цветовое пространство текстур, загруженных из .gltf or .glb файла, только если указанная выше настройка произведена. Если же вы загружаете текстуры снаружи (например, с помощью TextureLoader) и применяете эти текстуры на glTF-моделях, цветовое пространство и ориентация должны быть установлены вручную:

`// устанавливаем цветовое пространство texture.encoding = v3d.sRGBEncoding; // делаем так, чтобы координата (0, 0) соответствовала верхнему левому краю текстуры texture.flipY = false;`

## Неизвестные расширения

Метаданные из неизвестных загрузчику расширений сохраняются в поле `.userData.gltfExtensions` экземпляров Object3D, Scene, и Material, либо назначаются на возвращаемом объекте `gltf`. Например:

`loader.load('foo.gltf', function(gltf) { const scene = gltf.scene; const mesh = scene.children[3]; const fooExtension = mesh.userData.gltfExtensions.EXT_foo; gltf.parser.getDependency('bufferView', fooExtension.bufferView).then(function(fooBuffer) { ... }); });`

## Конструктор

### GLTFLoader(manager)

manager — диспетчер загрузок, используемый загрузчиком. По умолчанию используется v3d.DefaultLoadingManager.

Создает новый GLTFLoader.

## Свойства

Смотрите свойства базового класса.

## Методы

### # .load(url : String, onLoad : Function, onProgress : Function, onError : Function)

- url — путь к файлу .gltf или .glb.
- onLoad — будет вызван после завершения загрузки. На вход этой функции передаётся результат [method:.parse парсинга] ресурса.
- onProgress — вызывается во время загрузки. Аргументом будет экземпляр XMLHttpRequest, содержащий байты .total и .loaded. Если сервер не устанавливает заголовок Content-Length, значение .total будет равно `0`.
- onError — (необ.) вызывается при ошибках загрузки. Ошибка передаётся на вход этой функции.

Загружает и парсит glTF-ресурс по указанному пути и вызывает коллбек с содержимым данного ресурса.

### # .setKTX2Loader(ktx2Loader : KTX2Loader) → this

ktx2Loader — экземпляр класса v3d.KTX2Loader, используемый для загрузки сжатых текстур формата KTX2.

### # .parse(data : ArrayBuffer, path : String, onLoad : Function, onError : Function)

- data — glTF ассет для парсинга, в виде ArrayBuffer, JSON или объекта.
- path — базовый путь для поиска текстур и .bin-файла.
- onLoad — функция вызываемся по окончании парсинга.
- onError — (необ.) функция вызываемая в случае ошибки парсинга. Ошибка передаётся на вход этой функции.

Парсит glTF-данные и выполняет коллбек по завершении. Аргументом коллбека будет объект, содержащий загруженные части: .scene, .scenes, .cameras, .animations и .asset.

## Пазлы

«Вердж3Д» поддерживает 2 пазла, упрощающие загрузку ресурсов в формате glTF 2.0:

- load scene — загружает и заменяет текущую сцену целиком.
- append scene — добавляет ресурс на текущую сцену.

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

О том как получить исходный код этого модуля читайте тут.