Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[3.x] Backport the GLTFDocumentExtension system #70411

Merged
merged 1 commit into from
Dec 22, 2022
Merged

[3.x] Backport the GLTFDocumentExtension system #70411

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions modules/gltf/config.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ def get_doc_classes():
"GLTFBufferView",
"GLTFCamera",
"GLTFDocument",
"GLTFDocumentExtension",
"GLTFLight",
"GLTFMesh",
"GLTFNode",
Expand Down
22 changes: 22 additions & 0 deletions modules/gltf/doc_classes/GLTFDocument.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,28 @@
<tutorials>
</tutorials>
<methods>
<method name="register_gltf_document_extension">
<return type="void" />
<argument index="0" name="extension" type="GLTFDocumentExtension" />
<argument index="1" name="first_priority" type="bool" default="false" />
<description>
Registers the given [GLTFDocumentExtension] instance with GLTFDocument. If [code]first_priority[/code] is true, this extension will be run first. Otherwise, it will be run last.
[b]Note:[/b] Like GLTFDocument itself, all GLTFDocumentExtension classes must be stateless in order to function properly. If you need to store data, use the [code]set_additional_data[/code] and [code]get_additional_data[/code] methods in [GLTFState] or [GLTFNode].
</description>
</method>
<method name="unregister_all_gltf_document_extensions">
<return type="void" />
<description>
Unregisters all [GLTFDocumentExtension] instances.
</description>
</method>
<method name="unregister_gltf_document_extension">
<return type="void" />
<argument index="0" name="extension" type="GLTFDocumentExtension" />
<description>
Unregisters the given [GLTFDocumentExtension] instance.
</description>
</method>
</methods>
<constants>
</constants>
Expand Down
118 changes: 118 additions & 0 deletions modules/gltf/doc_classes/GLTFDocumentExtension.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="GLTFDocumentExtension" inherits="Resource" version="3.6" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../doc/class.xsd">
<brief_description>
[GLTFDocument] extension class.
</brief_description>
<description>
Extends the functionality of the [GLTFDocument] class by allowing you to run arbitrary code at various stages of GLTF import or export.
[b]Note:[/b] Like GLTFDocument itself, all GLTFDocumentExtension classes must be stateless in order to function properly. If you need to store data, use the [code]set_additional_data[/code] and [code]get_additional_data[/code] methods in [GLTFState] or [GLTFNode].
</description>
<tutorials>
</tutorials>
<methods>
<method name="_convert_scene_node" qualifiers="virtual">
<return type="void" />
<argument index="0" name="state" type="Object" />
<argument index="1" name="gltf_node" type="Object" />
<argument index="2" name="scene_node" type="Object" />
<description>
Part of the export process. This method is run after [method _export_preflight] and before [method _export_node].
Runs when converting the data from a Godot scene node. This method can be used to process the Godot scene node data into a format that can be used by [method _export_node].
</description>
</method>
<method name="_export_node" qualifiers="virtual">
<return type="int" />
<argument index="0" name="state" type="Object" />
<argument index="1" name="gltf_node" type="Object" />
<argument index="2" name="json" type="Dictionary" />
<argument index="3" name="node" type="Object" />
<description>
Part of the export process. This method is run after [method _convert_scene_node] and before [method _export_post].
This method can be used to modify the final JSON of each node.
</description>
</method>
<method name="_export_post" qualifiers="virtual">
<return type="int" />
<argument index="0" name="state" type="Object" />
<description>
Part of the export process. This method is run last, after all other parts of the export process.
This method can be used to modify the final JSON of the generated GLTF file.
</description>
</method>
<method name="_export_preflight" qualifiers="virtual">
<return type="int" />
<argument index="0" name="state" type="Object" />
<argument index="1" name="root" type="Object" />
<description>
Part of the export process. This method is run first, before all other parts of the export process.
The return value is used to determine if this [GLTFDocumentExtension] instance should be used for exporting a given GLTF file. If [constant OK], the export will use this [GLTFDocumentExtension] instance. If not overridden, [constant OK] is returned.
</description>
</method>
<method name="_generate_scene_node" qualifiers="virtual">
<return type="Object" />
<argument index="0" name="state" type="Object" />
<argument index="1" name="gltf_node" type="Object" />
<argument index="2" name="scene_parent" type="Object" />
<description>
Part of the import process. This method is run after [method _parse_node_extensions] and before [method _import_post_parse].
Runs when generating a Godot scene node from a GLTFNode. The returned node will be added to the scene tree. Multiple nodes can be generated in this step if they are added as a child of the returned node.
</description>
</method>
<method name="_get_supported_extensions" qualifiers="virtual">
<return type="Array" />
<description>
Part of the import process. This method is run after [method _import_preflight] and before [method _parse_node_extensions].
Returns an array of the GLTF extensions supported by this GLTFDocumentExtension class. This is used to validate if a GLTF file with required extensions can be loaded.
</description>
</method>
<method name="_import_node" qualifiers="virtual">
<return type="int" />
<argument index="0" name="state" type="Object" />
<argument index="1" name="gltf_node" type="Object" />
<argument index="2" name="json" type="Dictionary" />
<argument index="3" name="node" type="Object" />
<description>
Part of the import process. This method is run after [method _import_post_parse] and before [method _import_post].
This method can be used to make modifications to each of the generated Godot scene nodes.
</description>
</method>
<method name="_import_post" qualifiers="virtual">
<return type="int" />
<argument index="0" name="state" type="Object" />
<argument index="1" name="root" type="Object" />
<description>
Part of the import process. This method is run last, after all other parts of the import process.
This method can be used to modify the final Godot scene generated by the import process.
</description>
</method>
<method name="_import_post_parse" qualifiers="virtual">
<return type="int" />
<argument index="0" name="state" type="Object" />
<description>
Part of the import process. This method is run after [method _generate_scene_node] and before [method _import_node].
This method can be used to modify any of the data imported so far, including any scene nodes, before running the final per-node import step.
</description>
</method>
<method name="_import_preflight" qualifiers="virtual">
<return type="int" />
<argument index="0" name="state" type="Object" />
<argument index="1" name="extensions" type="PoolStringArray" />
<description>
Part of the import process. This method is run first, before all other parts of the import process.
The return value is used to determine if this [GLTFDocumentExtension] instance should be used for importing a given GLTF file. If [constant OK], the import will use this [GLTFDocumentExtension] instance. If not overridden, [constant OK] is returned.
</description>
</method>
<method name="_parse_node_extensions" qualifiers="virtual">
<return type="int" />
<argument index="0" name="state" type="Object" />
<argument index="1" name="gltf_node" type="Object" />
<argument index="2" name="extensions" type="Dictionary" />
<description>
Part of the import process. This method is run after [method _get_supported_extensions] and before [method _generate_scene_node].
Runs when parsing the node extensions of a GLTFNode. This method can be used to process the extension JSON data into a format that can be used by [method _generate_scene_node]. The return value should be a member of the [enum Error] enum.
</description>
</method>
</methods>
<constants>
</constants>
</class>
20 changes: 20 additions & 0 deletions modules/gltf/doc_classes/GLTFNode.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,33 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="GLTFNode" inherits="Resource" version="3.6" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../doc/class.xsd">
<brief_description>
GLTF node class.
</brief_description>
<description>
Represents a GLTF node. GLTF nodes may have names, transforms, children (other GLTF nodes), and more specialized properties (represented by their own classes).
[b]Note:[/b] This class is only compiled in editor builds. Run-time glTF loading and saving is [i]not[/i] available in exported projects. References to [GLTFNode] within a script will cause an error in an exported project.
</description>
<tutorials>
<link title="GLTF scene and node spec">https://github.com/KhronosGroup/glTF-Tutorials/blob/master/gltfTutorial/gltfTutorial_004_ScenesNodes.md"</link>
</tutorials>
<methods>
<method name="get_additional_data">
<return type="Variant" />
<argument index="0" name="extension_name" type="String" />
<description>
Gets additional arbitrary data in this [GLTFNode] instance. This can be used to keep per-node state data in [GLTFDocumentExtension] classes, which is important because they are stateless.
The argument should be the [GLTFDocumentExtension] name (does not have to match the extension name in the GLTF file), and the return value can be anything you set. If nothing was set, the return value is null.
</description>
</method>
<method name="set_additional_data">
<return type="void" />
<argument index="0" name="extension_name" type="String" />
<argument index="1" name="additional_data" type="Variant" />
<description>
Sets additional arbitrary data in this [GLTFNode] instance. This can be used to keep per-node state data in [GLTFDocumentExtension] classes, which is important because they are stateless.
The first argument should be the [GLTFDocumentExtension] name (does not have to match the extension name in the GLTF file), and the second argument can be anything you want.
</description>
</method>
</methods>
<members>
<member name="camera" type="int" setter="set_camera" getter="get_camera" default="-1">
Expand Down
25 changes: 25 additions & 0 deletions modules/gltf/doc_classes/GLTFState.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,27 @@
<tutorials>
</tutorials>
<methods>
<method name="add_used_extension">
<return type="void" />
<argument index="0" name="extension_name" type="String" />
<argument index="1" name="required" type="bool" />
<description>
Appends an extension to the list of extensions used by this GLTF file during serialization. If [code]required[/code] is true, the extension will also be added to the list of required extensions. Do not run this in [method GLTFDocumentExtension._export_post], as that stage is too late to add extensions. The final list is sorted alphabetically.
</description>
</method>
<method name="get_accessors">
<return type="Array" />
<description>
</description>
</method>
<method name="get_additional_data">
<return type="Variant" />
<argument index="0" name="extension_name" type="String" />
<description>
Gets additional arbitrary data in this [GLTFState] instance. This can be used to keep per-file state data in [GLTFDocumentExtension] classes, which is important because they are stateless.
The argument should be the [GLTFDocumentExtension] name (does not have to match the extension name in the GLTF file), and the return value can be anything you set. If nothing was set, the return value is null.
</description>
</method>
<method name="get_animation_player">
<return type="AnimationPlayer" />
<argument index="0" name="idx" type="int" />
Expand Down Expand Up @@ -113,6 +129,15 @@
<description>
</description>
</method>
<method name="set_additional_data">
<return type="void" />
<argument index="0" name="extension_name" type="String" />
<argument index="1" name="additional_data" type="Variant" />
<description>
Sets additional arbitrary data in this [GLTFState] instance. This can be used to keep per-file state data in [GLTFDocumentExtension] classes, which is important because they are stateless.
The first argument should be the [GLTFDocumentExtension] name (does not have to match the extension name in the GLTF file), and the second argument can be anything you want.
</description>
</method>
<method name="set_animations">
<return type="void" />
<argument index="0" name="animations" type="Array" />
Expand Down
Loading