GLTFDocument¶

用于在 i3D 中导入和导出 glTF 文件的类。

描述¶

GLTFDocument 支持从 glTF 文件、缓冲区或 i3D 场景中读取数据。这些数据随后可以写入文件系统、缓冲区，或者用于创建一个新的 i3D 场景。

一个 glTF 场景中的所有数据都存储在 GLTFState 类中。GLTFDocument 处理状态对象，但本身并不包含任何场景数据。GLTFDocument 有成员变量用于存储诸如图像格式之类的导出配置设置，但除此之外它是无状态的。可以使用同一个 GLTFDocument 对象和不同的 GLTFState 对象以相同的设置来处理多个场景。

通过扩展 GLTFDocumentExtension 类并使用 register_gltf_document_extension() 方法将其注册到 GLTFDocument 中，可以为 GLTFDocument 添加任意功能。这使得能够导入和导出自定义数据。

属性¶

String	image_format	`"PNG"`
float	lossy_quality	`0.75`
RootNodeMode	root_node_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: Item, state: GLTFState, flags: int = 0)
GLTFObjectModelProperty	export_object_model_property(state: GLTFState, node_path: ItemPath, i3d_node: Item, gltf_node_index: int) static
PackedByteArray	generate_buffer(state: GLTFState)
Item	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

将 i3D 场景的根节点视为 glTF 文件的根节点，并通过 I3D_single_root glTF 扩展将其标记为单根节点。如果实现不支持 I3D_single_root，这将与 ROOT_NODE_MODE_KEEP_ROOT 进行相同的解析。

RootNodeMode ROOT_NODE_MODE_KEEP_ROOT = 1

将 i3D 场景的根节点视为 glTF 文件的根节点，但不要将其标记为任何特殊的东西。导入 i3D 时会生成一个额外的根节点。这仅使用普通 glTF 功能。

RootNodeMode ROOT_NODE_MODE_MULTI_ROOT = 2

将 i3D 场景的根节点视为 glTF 场景的名称，并将其所有子节点添加为 glTF 文件的根节点。这仅使用普通 glTF 功能。这避免了额外的根节点，但只会保留 i3D 场景根节点的名称，因为它不会被保存为节点。

属性说明¶

String image_format = "PNG" 🔗

void set_image_format(value: String)
String get_image_format()

该导出图像格式的用户友好名称。在导出 glTF 文件时会使用到这个名称，包括将文件写入文件系统以及将数据写入字节数组。

默认情况下，i3D 允许以下选项 "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 是有损图像格式，则这决定了该图像的有损质量。在 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()

在导出过程中如何处理根节点。详情请参阅 RootNodeMode 。默认且推荐的值为 ROOT_NODE_MODE_SINGLE_ROOT 。

注意: 无论如何导出 glTF 文件，在导入时，都可以在场景导入设置选项卡中更改根节点的类型和名称。

方法说明¶

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

传入一个 PackedByteArray 对象，该对象用于定义 glTF 格式的数据，并通过 state 参数将数据导入到给定的 GLTFState 对象中。

注意: base_path 参数用于指示 append_from_buffer() 应从何处查找依赖项，该路径可以为空。

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

按照指定的路径访问 glTF 文件，并通过 state 参数将该文件路径中的数据导入到给定的 GLTFState 对象中。

注意: base_path 参数用于指示 append_from_file() 应从何处查找依赖项，该参数可以为空。

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

接收一个 i3D 引擎的场景节点，并通过 state 参数将其及其后代导出到给定的 GLTFState 对象。

GLTFObjectModelProperty export_object_model_property(state: GLTFState, node_path: ItemPath, i3d_node: Item, gltf_node_index: int) static 🔗

确定给定 i3D node_path 与生成的 glTF 文件中相应的 glTF 对象模型 JSON 指针之间的映射。该映射的详细信息以 GLTFObjectModelProperty 对象的形式返回。可以通过 GLTFDocumentExtension._import_object_model_property() 回调方法提供额外的映射。

PackedByteArray generate_buffer(state: GLTFState) 🔗

通过 state 参数接收一个 GLTFState 对象，并返回一个 glTF PackedByteArray。

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

通过 state 参数接收一个 GLTFState 对象，并返回一个 i3D 引擎场景节点。

bake_fps 参数会覆盖 state 中的 bake_fps 值。

PackedStringArray get_supported_gltf_extensions() static 🔗

返回所有支持的 glTF 扩展的列表，其中包括引擎直接支持的扩展以及由用户插件（通过注册 GLTFDocumentExtension 类）支持的扩展。

注意: 如果在注册 GLTFDocumentExtension 之前运行此方法，那么其扩展将不会被包含在列表中。请务必在所有扩展都注册完毕后再运行此方法。如果在引擎启动时运行此方法，请考虑在调用此方法之前等待一帧，以确保所有扩展均已注册。

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

确定给定 glTF 对象模型 json_pointer 与生成的 i3D 场景中相应的 i3D 节点路径之间的映射。该映射的详细信息以 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 类都必须是无状态的，这样才能正常运行。如果您需要存储数据，请使用 GLTFState 或 GLTFNode 中的 set_additional_data 和 get_additional_data 方法来进行操作。

void unregister_gltf_document_extension(extension: GLTFDocumentExtension) static 🔗

将给定的 GLTFDocumentExtension 实例取消注册。

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

通过 state 参数接收一个 GLTFState 对象，并将一个 glTF 文件写入文件系统中。

注意: glTF 文件的扩展名决定了它是以 .glb 格式（二进制文件）还是以 .gltf 格式（文本文件）的形式存在。