Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

GLTFDocument

继承: Resource < RefCounted < Object

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

描述

GLTFDocument 支持从 glTF 文件、缓冲区、或 Godot 场景中读取数据。然后可以将该数据写入文件系统、缓冲区、或用于创建 Godot 场景。

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 ( PackedByteArray bytes, String base_path, GLTFState state, int flags=0 )

Error

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

Error

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

PackedByteArray

generate_buffer ( GLTFState state )

Node

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

void

register_gltf_document_extension ( GLTFDocumentExtension extension, bool first_priority=false ) static

void

unregister_gltf_document_extension ( GLTFDocumentExtension extension ) static

Error

write_to_filesystem ( GLTFState state, String path )


枚举

enum RootNodeMode:

RootNodeMode ROOT_NODE_MODE_SINGLE_ROOT = 0

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

RootNodeMode ROOT_NODE_MODE_KEEP_ROOT = 1

将 Godot 场景的根节点视为 glTF 文件的根节点,但不要将其标记为任何特殊的东西。导入 Godot 时会生成一个额外的根节点。这仅使用普通 glTF 功能。这相当于 Godot 4.1 及更早版本中的行为。

RootNodeMode ROOT_NODE_MODE_MULTI_ROOT = 2

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


属性说明

String image_format = "PNG"

  • void set_image_format ( String value )

  • String get_image_format ( )

导出图像格式的用户友好名称。这被用于导出 GLTF 文件,包括写入文件和写入字节数组。

默认情况下,Godot 允许以下选项:“无”、“PNG”、“JPEG”、“无损 WebP”、和“有损 WebP”。可以使用 GLTFDocumentExtension 类添加对更多图像格式的支持。


float lossy_quality = 0.75

  • void set_lossy_quality ( float value )

  • float get_lossy_quality ( )

如果 image_format 是有损图像格式,则这决定了该图像的有损质量。在 0.01.0 范围内,其中 0.0 是最低质量,1.0 是最高质量。1.0 的有损质量不同于无损质量。


RootNodeMode root_node_mode = 0

导出时如何处理根节点。详见 RootNodeMode。默认和推荐值为 ROOT_NODE_MODE_SINGLE_ROOT

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


方法说明

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

接收一个定义 GLTF 的 PackedByteArray,并通过 state 参数将数据导入给定的 GLTFState 对象。

注意:base_pathappend_from_buffer 用作依赖关系的查找路径,可以为空。


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

接收一个 GLTF 文件的路径,并通过 state 参数将该文件路径上的数据导入到给定的 GLTFState 对象。

注意:base_pathappend_from_file 用作依赖关系的查找路径,可以为空。


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

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


PackedByteArray generate_buffer ( GLTFState state )

通过 state 参数接收一个 GLTFState 对象,并返回一个 GLTF PackedByteArray


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

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


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

使用 GLTFDocument 注册给定的 GLTFDocumentExtension 实例。如果 first_priority 为 true,则该扩展将被首先运行。否则,它将被最后运行。

注意:与 GLTFDocument 本身一样,所有 GLTFDocumentExtension 类都必须是无状态的才能正常运行。如果需要存储数据,使用 GLTFStateGLTFNode 中的 set_additional_dataget_additional_data 方法。


void unregister_gltf_document_extension ( GLTFDocumentExtension extension ) static

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


Error write_to_filesystem ( GLTFState state, String path )

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

注意:glTF 文件的扩展名决定了它是一个 .glb 二进制文件还是一个 .gltf 文件。