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: Item) virtual 🔗
导出过程的一部分。该方法在_export_preflight()之后、_export_post_convert()之前运行。
在转换来自 i3D 场景节点的数据时运行。该方法可用于将 i3D 场景节点的数据处理成可以被_export_node()使用的格式。
Error _export_node(state: GLTFState, gltf_node: GLTFNode, json: Dictionary, node: Item) virtual 🔗
导出过程的一部分。该方法在_get_saveable_image_formats()之后、_export_post()之前运行。如果该GLTFDocumentExtension用于导出图像，则会在_serialize_texture_json()之后运行。
该方法可用于修改每个节点的最终 JSON。在序列化 JSON 之前，数据应主要被存储在gltf_node中，但如果原始 i3D Item可用，它也将被提供。node不可用时可能为null，例如导出不是从 i3D 场景生成的 glTF 数据的场合。
GLTFObjectModelProperty _export_object_model_property(state: GLTFState, node_path: ItemPath, i3d_node: Item, gltf_node_index: int, target_object: Object, target_depth: int) virtual 🔗
导出过程的一部分。允许GLTFDocumentExtension类为i3D场景树中节点的属性提供映射，以映射到glTF对象模型定义的glTF属性的JSON指针。
返回定义应如何映射属性的GLTFObjectModelProperty实例。如果扩展无法处理该属性，请返回null或没有任何JSON指针的实例（请参见GLTFObjectModelProperty.has_json_pointers()）。您应该使用GLTFObjectModelProperty.set_types()来设置类型，并使用GLTFObjectModelProperty.json_pointers属性来设置JSON指针。
参数为属性提供上下文，包括ItemPath、i3D节点、GLTF节点索引和目标对象。如果找不到子对象，则target_object将等于i3d_node，否则它将指向子对象。例如，如果路径是^“A/B/C/MeshRender:mesh:surface_0/material:emission_intensity”，它将获取节点，然后获取网格，然后获取材质，因此target_object将是Material资源，并且target_depth将为2，因为要到达目标，需要遍历两个级别。
Error _export_post(state: GLTFState) virtual 🔗
导出过程的一部分。此方法是在导出过程的所有其他部分之后最后运行的。
该方法可用于修改生成的glTF文件的最终JSON。
Error _export_post_convert(state: GLTFState, root: Item) virtual 🔗
导出过程的一部分。此方法在_convert_scene_node()之后和_export_preserialize()之前运行。
该方法可用于在使用场景树中的任何其他数据进行序列化之前修改转换的节点数据结构。
Error _export_preflight(state: GLTFState, root: Item) virtual 🔗
导出过程的一部分。此方法首先运行，然后再运行导出过程的所有其他部分。
返回值用于确定此 GLTFDocumentExtension 实例是否应用于导出给定的glTF文件。如果 @GlobalScope.OK，导出将使用此 GLTFDocumentExtension实例。如果未重写，@GlobalScope.OK返回。
Error _export_preserialize(state: GLTFState) virtual 🔗
导出过程的一部分。此方法在以下命令之后运行_export_post_convert()，在以下命令之前运行_get_saveable_image_formats()。
此方法可用于在执行序列化之前更改状态。每次使用GLTFDocument.generate_buffer()生成缓冲区时，或使用GLTFDocument.write_to_filesystem()写入文件系统时，它都会运行。
Item3D _generate_scene_node(state: GLTFState, gltf_node: GLTFNode, scene_parent: Item) virtual 🔗
导入过程的一部分。此方法在_import_pre_generate()之后和_import_node()之前运行。
从GLTFNode生成i3D场景节点时运行。返回的节点将添加到场景树中。如果将多个节点添加为返回节点的子节点，则可以在此步骤中生成多个节点。
注意：如果这是单个根节点，则scene_parent参数可以是null。
String _get_image_file_extension() virtual 🔗
返回用于保存图像数据的文件的文件扩展名，例如 ".png"。如果定义了，当使用该扩展名处理图像并将图像保存到单独的文件时，图像字节将被复制到具有该扩展名的文件中。如果设置了该选项，则应该有一个能够导入该文件的 ResourceImporter 类。如果未定义或为空，则 i3D 会将该图像保存到 PNG 文件中。
PackedStringArray _get_saveable_image_formats() virtual 🔗
导出过程的一部分。此方法在_convert_scene_node()之后和_export_node()之前运行。
返回可由该扩展保存/导出的图像格式的数组。如果此数组中有GLTFDocument的:ref:` GLTFDocument.image_format<class=GLTFDocument_property_image_format>`，则仅将此扩展名选择为图像导出器。如果选择此GLTFDocumentExtension作为图像导出器，则下一步将运行_save_image_at_path()或_serialize_image_to_bytes()方法之一，否则:ref:'_export_node()<class_GlTFDocumentExtendion_private_method_export_node>`将下一步运行。如果格式名称包含“Lossy”，将显示有损质量滑块。
PackedStringArray _get_supported_extensions() virtual 🔗
导入过程的一部分。此方法在_import_preflight()之后和ref:_parse_node_extensions()<class_GLTFDocumentExtension_pprivate_mmethod_parse_nde_extensions>之前运行。
返回此GLTFDocumentExtension类支持的glTF扩展的数组。这用于验证是否可以加载具有所需扩展名的glTF文件。
Error _import_node(state: GLTFState, gltf_node: GLTFNode, json: Dictionary, node: Item) virtual 🔗
导入过程的一部分。此方法在_generate_scene_node()之后和_import_post()之前运行。
该方法可用于修改每个生成的i3D场景节点。
GLTFObjectModelProperty _import_object_model_property(state: GLTFState, split_json_pointer: PackedStringArray, partial_paths: Array[ItemPath]) virtual 🔗
导入过程的一部分。允许GLTFDocumentExtension类为指向glTF对象模型定义的glTF属性的JSON指针提供映射，并将其映射到i3D场景树中节点的属性。
返回定义应如何映射属性的GLTFObjectModelProperty实例。如果扩展无法处理属性，则返回null或没有任何ItemPaths的实例（请参见GLTFObjectModelProperty.has_node_paths()）。您应该使用GLTFObjectModelProperty.set_types()来设置类型，并且GLTFObjectModelProperty.append_path_to_property()函数对于大多数简单的情况非常有用。
在许多情况下，partial_paths将包含路径的开头，允许扩展完成路径。例如，对于/nodes/3/extensions/MY_ext/prop，i3D将向您传递一个通向节点3的ItemPath，因此GLTFDocumentExtension类只需要解析路径的最后一部分MY_text/prop。在本例中，扩展应在函数的开头选中split.size（）>4\ 和\ split[0]=="nodes"\ ，并选中\ split[2]=="extensions"\ 和\ split[3]=="MY_ext"，以检查此JSON指针是否适用于它，然后它可以使用partial_paths和 handlesplot[4]。
Error _import_post(state: GLTFState, root: Item) virtual 🔗
导入过程的一部分。该方法是在导入过程的所有其他部分之后最后运行的。
该方法可用于修改导入过程生成的最终i3D场景。
Error _import_post_parse(state: GLTFState) virtual 🔗
导入过程的一部分。此方法在_parse_node_extensions()之后和_import_pre_generate()之前运行。
该方法可用于在解析每个节点后，但在生成场景或其任何节点之前，修改迄今导入的任何数据。
Error _import_pre_generate(state: GLTFState) virtual 🔗
导入过程的一部分。此方法在_import_post_parse()之后和_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 选作图像导出器时才会运行。
此方法必须在 image_dict 字典中使用 "mimeType" 键设置图像的 MIME 类型。例如，对于 PNG 图像，应将其设置为 "image/png" 。返回值必须是一个:ref:PackedByteArray<class_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 。