GLTFDocumentExtension

继承： Resource < RefCounted < Object

派生： GLTFDocumentExtensionConvertImporterMesh

GLTFDocument 扩展类。

描述

通过允许在 GLTF 导入或导出的各个阶段运行任意代码，来扩展 GLTFDocument 类的功能。

要使用它，请创建一个扩展 GLTFDocumentExtension 的新类，覆盖需要的任何方法，创建你的类的实例，然后使用 GLTFDocument.register_gltf_document_extension 注册它。

注意：与 GLTFDocument 本身一样，所有 GLTFDocumentExtension 类都必须是无状态的才能正常运行。如果需要存储数据，请使用 GLTFState 或 GLTFNode 中的 set_additional_data 和 get_additional_data 方法。

教程

• 运行时文件加载与保存

方法

方法说明

void _convert_scene_node(state: GLTFState, gltf_node: GLTFNode, scene_node: Node) virtual 🔗

导出过程的一部分。该方法在 _export_preflight 之后和 _export_preserialize 之前运行。

在转换来自 Godot 场景节点的数据时运行。该方法可用于将 Godot 场景节点的数据，处理成可以被 _export_node 使用的格式。

Error _export_node(state: GLTFState, gltf_node: GLTFNode, json: Dictionary, node: Node) virtual 🔗

导出过程的一部分。该方法在 _get_saveable_image_formats 之后 _export_post 之前运行。如果该 GLTFDocumentExtension 用于导出图像，则会在 _serialize_texture_json 之后运行。

该方法可用于修改每个节点的最终 JSON。在序列化 JSON 之前，数据应主要被存储在 gltf_node 中，但如果原始 Godot node 可用，它也将被提供。如果该节点不可用，例如当导出不是从 Godot 场景生成的 GLTF 数据时，该节点可能为 null。

Error _export_post(state: GLTFState) virtual 🔗

导出过程的一部分。该方法在最后运行，在导出过程的所有其他部分之后。

该方法可用于修改生成的 GLTF 文件的最终 JSON。

Error _export_preflight(state: GLTFState, root: Node) virtual 🔗

导出过程的一部分。该方法将最初运行，在导出过程的所有其他部分之前。

返回值用于确定该 GLTFDocumentExtension 实例是否应该用于导出一个给定的 GLTF 文件。如果为 @GlobalScope.OK，则导出将使用该 GLTFDocumentExtension 实例。如果没有被重写，则返回 @GlobalScope.OK。

Error _export_preserialize(state: GLTFState) virtual 🔗

导入过程的一部分。该方法在 _convert_scene_node 之后 _get_saveable_image_formats 之前运行。

该方法可用于在执行序列化之前更改状态。每次使用 GLTFDocument.generate_buffer 生成缓冲区或使用GLTFDocument.write_to_filesystem写入文件系统时，它都会运行。

Node3D _generate_scene_node(state: GLTFState, gltf_node: GLTFNode, scene_parent: Node) virtual 🔗

导入过程的一部分。该方法在 _import_post_parse 之后 _import_node 之前运行。

当从 GLTFNode 生成一个 Godot 场景节点时运行。返回的节点将被添加到场景树中。如果将多个节点添加为返回节点的子节点，则可以在该步骤中生成这些节点。

注意：如果这是单个根节点，则 scene_parent 参数可以为 null。

String _get_image_file_extension() virtual 🔗

返回用于保存图像数据的文件的文件扩展名，例如 ".png"。如果定义了，当使用该扩展名处理图像并将图像保存到单独的文件时，图像字节将被复制到具有该扩展名的文件中。如果设置了该选项，则应该有一个能够导入该文件的 ResourceImporter 类。如果未定义或为空，则 Godot 会将该图像保存到 PNG 文件中。

PackedStringArray _get_saveable_image_formats() virtual 🔗

导出过程的一部分。该方法在 _convert_scene_node 之后和 _export_node 之前运行。

返回可以由该扩展保存/导出的图像格式的数组。仅当 GLTFDocument 的 GLTFDocument.image_format 在该数组中时，才会选择该扩展作为图像导出器。如果选择该 GLTFDocumentExtension 作为图像导出器，则接下来将运行 _save_image_at_path 或 _serialize_image_to_bytes 方法之一，否则接下来将运行 _export_node。如果格式名称包含 "Lossy"，则会显示有损质量滑块。

PackedStringArray _get_supported_extensions() virtual 🔗

导入过程的一部分。该方法在 _import_preflight 之后 _parse_node_extensions 之前运行。

返回一组被该 GLTFDocumentExtension 类支持的 GLTF 扩展。这用于验证是否可以加载一个具有所需扩展名的 GLTF 文件。

Error _import_node(state: GLTFState, gltf_node: GLTFNode, json: Dictionary, node: Node) virtual 🔗

导入过程的一部分。该方法在 _generate_scene_node 之后 _import_post 之前运行。

该方法可用于对生成的每个 Godot 场景节点进行修改。

Error _import_post(state: GLTFState, root: Node) virtual 🔗

导入过程的一部分。该方法在最后运行，在导入过程的所有其他部分之后。

该方法可用于修改导入过程生成的最终 Godot 场景。

Error _import_post_parse(state: GLTFState) virtual 🔗

导入过程的一部分。该方法在 _parse_node_extensions 之后 _generate_scene_node 之前运行。

该方法可用于在解析后、生成节点并运行最终的各节点导入步骤之前，修改到目前为止导入的任何数据。

Error _import_preflight(state: GLTFState, extensions: PackedStringArray) virtual 🔗

导入过程的一部分。该方法在最初运行，在导入过程的所有其他部分之前。

返回值用于确定该 GLTFDocumentExtension 实例是否应该用于导入一个给定的 GLTF 文件。如果为 @GlobalScope.OK，导入将使用该 GLTFDocumentExtension 实例。如果没有被重写，则返回 @GlobalScope.OK。

Error _parse_image_data(state: GLTFState, image_data: PackedByteArray, mime_type: String, ret_image: Image) virtual 🔗

导入过程的一部分。该方法在 _parse_node_extensions 之后 _parse_texture_json 之前运行。

从 GLTF 文件中解析图像数据时运行。数据可以从单独的文件、URI 或缓冲中获取，然后作为字节数组传递。

Error _parse_node_extensions(state: GLTFState, gltf_node: GLTFNode, extensions: Dictionary) virtual 🔗

导入过程的一部分。该方法在 _get_supported_extensions 之后和 _import_post_parse 之前运行。

在解析 GLTFNode 的节点扩展时运行。该方法可用于将扩展 JSON 数据，处理成可被 _generate_scene_node 使用的格式。该返回值应该是 Error 枚举中的一个成员。

Error _parse_texture_json(state: GLTFState, texture_json: Dictionary, ret_gltf_texture: GLTFTexture) virtual 🔗

导入过程的一部分。该方法在 _parse_image_data 之后 _generate_scene_node 之前运行。

从 GLTF 纹理数组中解析纹理 JSON 时运行。可用于设置用作纹理的源图像索引。

Error _save_image_at_path(state: GLTFState, image: Image, file_path: String, image_format: String, lossy_quality: float) virtual 🔗

导入过程的一部分。该方法在 _get_saveable_image_formats 之后 _serialize_texture_json 之前运行。

当与 GLTF 文件分开保存图像时运行该方法。嵌入图像时，将运行 _serialize_image_to_bytes。请注意，这些方法仅在选择该 GLTFDocumentExtension 作为图像导出器时运行。

PackedByteArray _serialize_image_to_bytes(state: GLTFState, image: Image, image_dict: Dictionary, image_format: String, lossy_quality: float) virtual 🔗

导出过程的一部分。该方法在 _get_saveable_image_formats 之后和 _serialize_texture_json 之前运行。

在 GLTF 文件中嵌入图像时运行该方法。当图像单独保存时，将运行 _save_image_at_path。请注意，这些方法仅在选择该 GLTFDocumentExtension 作为图像导出器时运行。

该方法必须使用 "mimeType" 键在 image_dict 中设置该图像的 MIME 类型。例如，对于 PNG 图像，它将被设置为 "image/png"。该返回值必须是包含该图像数据的 PackedByteArray。

Error _serialize_texture_json(state: GLTFState, texture_json: Dictionary, gltf_texture: GLTFTexture, image_format: String) virtual 🔗

导出过程的一部分。该方法在 _save_image_at_path 或 _serialize_image_to_bytes 之后、_export_node 之前运行。请注意，该方法仅在选择该 GLTFDocumentExtension 作为图像导出器时运行。

该方法可用于通过编辑 texture_json 设置该纹理 JSON 的扩展。还必须使用 GLTFState.add_used_extension 将该扩展添加为使用的扩展，如果你不提供后备，请务必将 required 设置为 true。