GLTFDocument

Наследует: Resource < RefCounted < Object

Наследуется от: FBXDocument

Класс для импорта и экспорта файлов glTF в Godot и из него.

Описание

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

Все данные в сцене glTF хранятся в классе GLTFState. GLTFDocument обрабатывает объекты состояния, но не содержит никаких данных самой сцены. GLTFDocument имеет переменные-члены для хранения параметров конфигурации экспорта, таких как формат изображения, но в остальном не имеет состояния. Несколько сцен можно обрабатывать с теми же настройками, используя тот же объект GLTFDocument и разные объекты GLTFState.

GLTFDocument можно расширить с помощью произвольной функциональности, расширив класс GLTFDocumentExtension и зарегистрировав его в GLTFDocument через register_gltf_document_extension(). Это позволяет импортировать и экспортировать пользовательские данные.

Обучающие материалы

Свойства

String	fallback_image_format	`"None"`
float	fallback_image_quality	`0.25`
String	image_format	`"PNG"`
float	lossy_quality	`0.75`
RootNodeMode	root_node_mode	`0`
VisibilityMode	visibility_mode	`0`

Методы

Error	append_from_buffer(bytes: PackedByteArray, base_path: String, state: GLTFState, flags: int = 0)
Error	append_from_file(path: String, state: GLTFState, flags: int = 0, base_path: String = "")
Error	append_from_scene(node: Node, state: GLTFState, flags: int = 0)
GLTFObjectModelProperty	export_object_model_property(state: GLTFState, node_path: NodePath, godot_node: Node, gltf_node_index: int) static
PackedByteArray	generate_buffer(state: GLTFState)
Node	generate_scene(state: GLTFState, bake_fps: float = 30, trimming: bool = false, remove_immutable_tracks: bool = true)
PackedStringArray	get_supported_gltf_extensions() static
GLTFObjectModelProperty	import_object_model_property(state: GLTFState, json_pointer: String) static
void	register_gltf_document_extension(extension: GLTFDocumentExtension, first_priority: bool = false) static
void	unregister_gltf_document_extension(extension: GLTFDocumentExtension) static
Error	write_to_filesystem(state: GLTFState, path: String)

Перечисления

enum RootNodeMode: 🔗

RootNodeMode ROOT_NODE_MODE_SINGLE_ROOT = 0

Обрабатывать корневой узел сцены Godot как корневой узел файла glTF и отмечать его как единственный корневой узел с помощью расширения glTF GODOT_single_root. Это будет проанализировано так же, как ROOT_NODE_MODE_KEEP_ROOT, если реализация не поддерживает GODOT_single_root.

RootNodeMode ROOT_NODE_MODE_KEEP_ROOT = 1

Обрабатывайте корневой узел сцены Godot как корневой узел файла glTF, но не помечайте его как что-то особенное. При импорте в Godot будет сгенерирован дополнительный корневой узел. Это использует только функции vanilla glTF. Это эквивалентно поведению в Godot 4.1 и более ранних версиях.

RootNodeMode ROOT_NODE_MODE_MULTI_ROOT = 2

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

enum VisibilityMode: 🔗

VisibilityMode VISIBILITY_MODE_INCLUDE_REQUIRED = 0

Если сцена содержит какие-либо невидимые узлы, включите их, отметьте их как невидимые с помощью KHR_node_visibility и потребуйте, чтобы импортеры учитывали их невидимость. Недостаток: если импортер не поддерживает KHR_node_visibility, файл не может быть импортирован.

VisibilityMode VISIBILITY_MODE_INCLUDE_OPTIONAL = 1

Если сцена содержит какие-либо невидимые узлы, включите их, отметьте их как невидимые с помощью KHR_node_visibility и не предъявляйте никаких требований к импортерам. Недостаток: если импортер не поддерживает KHR_node_visibility, невидимые объекты будут видны.

VisibilityMode VISIBILITY_MODE_EXCLUDE = 2

Если сцена содержит какие-либо невидимые узлы, не включайте их в экспорт. Это то же самое, что и в Godot 4.4 и более ранних версиях. Недостаток: невидимые узлы не будут существовать в экспортированном файле.

Описания свойств

String fallback_image_format = "None" 🔗

void set_fallback_image_format(value: String)
String get_fallback_image_format()

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

Это свойство может быть только одним из "None", "PNG" или "JPEG" и используется только тогда, когда image_format не является одним из "None", "PNG" или "JPEG". Если требуется иметь несколько форматов изображений с расширением, это можно сделать с помощью класса GLTFDocumentExtension — это свойство охватывает только вариант использования предоставления базового резервного изображения glTF при использовании пользовательского формата изображения.

float fallback_image_quality = 0.25 🔗

void set_fallback_image_quality(value: float)
float get_fallback_image_quality()

Качество резервного изображения, если таковое имеется. Для файлов PNG это уменьшает изображение по обоим измерениям на этот коэффициент. Для файлов JPEG это качество изображения с потерями. Рекомендуется низкое значение, поскольку включение нескольких высококачественных изображений в файл glTF сводит на нет выигрыш в размере файла за счет использования более эффективного формата изображения.

String image_format = "PNG" 🔗

void set_image_format(value: String)
String get_image_format()

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

По умолчанию Godot допускает следующие параметры: «None», «PNG», «JPEG», «Lossless WebP» и «Lossy WebP». Поддержка дополнительных форматов изображений может быть добавлена в классы GLTFDocumentExtension. Один класс расширения может предоставлять несколько параметров для конкретного используемого формата или даже параметр, который использует несколько форматов одновременно.

float lossy_quality = 0.75 🔗

void set_lossy_quality(value: float)
float get_lossy_quality()

Если image_format — это формат изображения с потерями (lossy), это определяет качество изображения с потерями. В диапазоне от 0.0 до 1.0, где 0.0 — самое низкое качество, а 1.0 — самое высокое качество. Качество с потерями 1.0 не то же самое, что и без потерь.

RootNodeMode root_node_mode = 0 🔗

void set_root_node_mode(value: RootNodeMode)
RootNodeMode get_root_node_mode()

Как обрабатывать корневой узел во время экспорта. Значение по умолчанию и рекомендуемое значение — ROOT_NODE_MODE_SINGLE_ROOT.

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

VisibilityMode visibility_mode = 0 🔗

void set_visibility_mode(value: VisibilityMode)
VisibilityMode get_visibility_mode()

Как работать с видимостью узлов во время экспорта. Эта настройка ничего не делает, если все узлы видны. Значение по умолчанию и рекомендуемое значение — VISIBILITY_MODE_INCLUDE_REQUIRED, которое использует расширение KHR_node_visibility.

Описания метода

Error append_from_buffer(bytes: PackedByteArray, base_path: String, state: GLTFState, flags: int = 0) 🔗

Принимает PackedByteArray, определяющий glTF, и импортирует данные в заданный объект GLTFState через параметр state.

Примечание: base_path сообщает append_from_buffer(), где найти зависимости, и может быть пустым.

Error append_from_file(path: String, state: GLTFState, flags: int = 0, base_path: String = "") 🔗

Берет путь к файлу glTF и импортирует данные по этому пути к файлу в указанный объект GLTFState через параметр state.

Примечание: Параметр base_path сообщает append_from_file(), где искать зависимости, и может быть пустым.

Error append_from_scene(node: Node, state: GLTFState, flags: int = 0) 🔗

Берет узел сцены Godot Engine и экспортирует его и его потомков в заданный объект GLTFState через параметр state.

GLTFObjectModelProperty export_object_model_property(state: GLTFState, node_path: NodePath, godot_node: Node, gltf_node_index: int) static 🔗

Определяет сопоставление между заданным Godot node_path и соответствующим указателем(ями) JSON объектной модели glTF в сгенерированном файле glTF. Подробности этого сопоставления возвращаются в объекте GLTFObjectModelProperty. Дополнительные сопоставления могут быть предоставлены с помощью метода обратного вызова GLTFDocumentExtension._import_object_model_property().

PackedByteArray generate_buffer(state: GLTFState) 🔗

Принимает объект GLTFState через параметр state и возвращает glTF PackedByteArray.

Node generate_scene(state: GLTFState, bake_fps: float = 30, trimming: bool = false, remove_immutable_tracks: bool = true) 🔗

Принимает объект GLTFState через параметр state и возвращает узел сцены Godot Engine.

Параметр bake_fps переопределяет bake_fps в state.

PackedStringArray get_supported_gltf_extensions() static 🔗

Возвращает список всех поддерживаемых расширений glTF, включая расширения, поддерживаемые непосредственно движком, и расширения, поддерживаемые пользовательскими плагинами, регистрирующими классы GLTFDocumentExtension.

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

GLTFObjectModelProperty import_object_model_property(state: GLTFState, json_pointer: String) static 🔗

Определяет сопоставление между заданной моделью объекта glTF json_pointer и соответствующим путям узла Godot в сгенерированной сцене Godot. Подробности этого сопоставления возвращаются в объекте GLTFObjectModelProperty. Дополнительные сопоставления могут быть предоставлены с помощью метода обратного вызова GLTFDocumentExtension._export_object_model_property().

void register_gltf_document_extension(extension: GLTFDocumentExtension, first_priority: bool = false) static 🔗

Регистрирует заданный экземпляр GLTFDocumentExtension с GLTFDocument. Если first_priority равен true, это расширение будет запущено первым. В противном случае оно будет запущено последним.

Примечание: Как и сам GLTFDocument, все классы GLTFDocumentExtension должны быть без состояния для правильной работы. Если вам нужно сохранить данные, используйте методы set_additional_data и get_additional_data в GLTFState или GLTFNode.

void unregister_gltf_document_extension(extension: GLTFDocumentExtension) static 🔗

Отменяет регистрацию указанного экземпляра GLTFDocumentExtension.

Error write_to_filesystem(state: GLTFState, path: String) 🔗

Принимает объект GLTFState через параметр state и записывает файл glTF в файловую систему.

Примечание: Расширение файла glTF определяет, является ли он двоичным файлом .glb или текстовым файлом .gltf.