Support controlling G4MF external data and URI-based buffer compression

Author: aaronfranke

addons/4d/doc_classes/G4MFState4D.xml

@@ -29,13 +29,26 @@
 				Gets the index of the G4MF node in the state's [member g4mf_nodes] array corresponding to the given Godot node. This will return [code]-1[/code] if the node is not found. Since it is possible for a G4MF node to generate multiple Godot nodes, if this returns [code]-1[/code], you may wish to call this function again with the parent node to give it another try.
 			</description>
 		</method>
+		<method name="is_text_file" qualifiers="const">
+			<return type="bool" />
+			<description>
+				Returns [code]true[/code] if [member filename] indicates this is a text-based G4MF file, meaning that it has 4 or more characters (handles [code]".g4tf"[/code] and other non-recommended cases like [code]".g4tf.json"[/code]). Returns [code]false[/code] with extensions shorter than 4 characters, or for an empty filename (indicating this is a byte array in memory).
+			</description>
+		</method>
 		<method name="reserve_unique_name">
 			<return type="String" />
 			<param index="0" name="requested" type="String" />
 			<description>
 				Reserves a unique name based on the requested name. This allows you to create a unique name for a node or resource in the G4MF file without conflicting with other names. If the requested name is already in use, a number will be appended to the name to make it unique. The number will be incremented until a unique name is found. The returned name is guaranteed to be unique relative to already reserved names.
 			</description>
 		</method>
+		<method name="should_separate_resource_files" qualifiers="const">
+			<return type="bool" />
+			<description>
+				Returns [code]true[/code] if resource files, such as images, should be separated into their own files. Returns [code]false[/code] if they should be embedded in the G4MF file. This is determined by the [member external_data_mode] property.
+				Extensions should call this method to determine if they should save their resources in separate files. For example, an audio extension should use this to determine if it should save audio files in separate files such as [code].mp3[/code] files, or if it should embed them in the G4MF file in buffer views.
+			</description>
+		</method>
 	</methods>
 	<members>
 		<member name="base_path" type="String" setter="set_base_path" getter="get_base_path" default="&quot;&quot;">
@@ -44,6 +57,12 @@
 		<member name="buffers" type="PackedByteArray[]" setter="set_buffers" getter="get_buffers" default="[]">
 			The array of buffers in the G4MF file. This is used to store binary blobs of data, such as mesh data. Each buffer is used by a [G4MFBufferView4D] to access a slice of the buffer, which is then used by [G4MFAccessor4D] to access the data in the buffer in a typed way.
 		</member>
+		<member name="external_data_mode" type="int" setter="set_external_data_mode" getter="get_external_data_mode" enum="G4MFState4D.ExternalDataMode" default="0">
+			When exporting a G4MF file, this determines where external data, such as images and binary buffers, should be stored.
+			The default value is [constant EXTERNAL_DATA_MODE_AUTOMATIC], which automatically determines if data should be embedded or separated based on the file extension used, embedding for [code].glb[/code] files and separating for [code].gltf[/code] files. If you want different behavior, you can set this to one of the [enum ExternalDataMode] values.
+			Saving resources like images to their own files can be useful for destinations where you need access to these files separately. For example, if the exported G4MF is added to the [code]res://[/code] folder of a Godot project, the default behavior of the Godot editor is to extract embedded images to their own files so they can be imported and compressed into GPU-optimized formats.
+			Extensions should respect this setting by calling [method should_separate_resource_files] to determine if they should save their resources in separate files.
+		</member>
 		<member name="filename" type="String" setter="set_filename" getter="get_filename" default="&quot;&quot;">
 			The filename of the G4MF file, including the file extension. If it ends with [code].g4tf[/code], this is a text-based G4MF, otherwise this is a binary G4MF. This will be set during import when appending from a file, and will be set during export when writing to a file. If writing to a buffer, this will be an empty string.
 		</member>
@@ -72,4 +91,28 @@
 			The array of Godot nodes corresponding to the G4MF nodes. This is used when importing a G4MF file and generating Godot nodes, after the nodes are generated, this array will have the same length as [member g4mf_nodes]. This is also used when converting a Godot scene to a G4MF file, after the nodes are converted, this array will have the same length as [member g4mf_nodes]. The node at each index corresponds to the G4MF node with the same index in the [member g4mf_nodes] array.
 		</member>
 	</members>
+	<constants>
+		<constant name="EXTERNAL_DATA_MODE_AUTOMATIC" value="0" enum="ExternalDataMode">
+			When exporting a G4MF file, automatically determines if data should be embedded or separated based on the file extension used and if [member base_path] is valid. With this option, exporting a [code].g4tf[/code] file with a valid [member base_path] will behave like [constant EXTERNAL_DATA_MODE_SEPARATE_ALL_FILES]. If exporting a [code].g4b[/code] file, exporting to an in-memory buffer, or exporting with [member base_path] set to an empty string, this will behave like [constant EXTERNAL_DATA_MODE_EMBED_EVERYTHING].
+			This option is suitable for most use cases. It behaves like Blender's "glTF Binary (.glb)" export option for [code].g4b[/code] files, and like Blender's "glTF Separate (.gltf + .bin + textures)" export option for [code].g4tf[/code] files.
+		</constant>
+		<constant name="EXTERNAL_DATA_MODE_EMBED_EVERYTHING" value="1" enum="ExternalDataMode">
+			When exporting a G4MF file, embeds all data in the G4MF file, including images and binary buffers. For [code].g4b[/code] files, this will use the binary blob chunks at the end of the file to store the data in buffers.
+			This option is useful when you want a single self-contained file. It behaves like Blender's "glTF Binary (.glb)" export option for [code].g4b[/code] files, and like Blender's "glTF Embedded (.gltf)" export option for [code].gltf[/code] files.
+		</constant>
+		<constant name="EXTERNAL_DATA_MODE_SEPARATE_ALL_FILES" value="2" enum="ExternalDataMode">
+			When exporting a G4MF file, separates all files that can be saved in their own file formats into their own files, and also save all raw binary blobs, such as G4MF buffers, into separate [code].bin[/code] files.
+			This option is useful when having the G4MF file's contents spread out over multiple files is desired, resulting in maximum human readability. It behaves like Blender's "glTF Separate (.gltf + .bin + textures)" export option.
+			Extensions should respect this setting by calling [method should_separate_resource_files] to determine if they should save their resources in separate files.
+		</constant>
+		<constant name="EXTERNAL_DATA_MODE_SEPARATE_BINARY_BLOBS" value="3" enum="ExternalDataMode">
+			When exporting a G4MF file, separates all raw binary blobs, such as G4MF buffers, into separate [code].bin[/code] files. Resources that can be saved in their own file formats, such as images, are embedded within G4MF buffers, and are stored in the [code].bin[/code] files.
+			This option is useful if you need efficient storage of binary data while also keeping the number of files low. In the typical case, this option will result in only two files: the G4MF file and a single [code].bin[/code] file next to it.
+		</constant>
+		<constant name="EXTERNAL_DATA_MODE_SEPARATE_RESOURCE_FILES" value="4" enum="ExternalDataMode">
+			When exporting a G4MF file, separates all resources that can be saved in their own file formats into their own files, such as images. This option does not separate buffers, meaning that binary blob data without a file type, such as mesh data, animation data, skin/skeleton data, and so on, are still embedded in the G4MF file.
+			This option is useful if the exported G4MF file is intended to be added to the project folder in a game engine, so that the game engine can import the resources files separately, and optionally use them separately. Otherwise, game engines may extract embedded resources to their own files, resulting in duplicate data in the project folder.
+			Extensions should respect this setting by calling [method should_separate_resource_files] to determine if they should save their resources in separate files.
+		</constant>
+	</constants>
 </class>

editor/import/g4mf/editor_export_dialog_g4mf_4d.cpp

@@ -52,6 +52,7 @@ void EditorExportDialogG4MF4D::_export_scene_as_g4mf(const String &p_path) {
 	ERR_FAIL_COND_SHOW_DIALOG(scene_root == nullptr, "G4MF error: Cannot export scene without a root node.");
 	Ref<G4MFState4D> g4mf_state;
 	g4mf_state.instantiate();
+	g4mf_state->set_external_data_mode(_export_settings->get_external_data_mode());
 	Error err = _g4mf_document->export_append_from_godot_scene(g4mf_state, scene_root);
 	ERR_FAIL_COND_SHOW_DIALOG(err != OK, "G4MF editor export: Error while running export_append_from_godot_scene.");
 	err = _g4mf_document->export_write_to_file(g4mf_state, p_path);

editor/import/g4mf/editor_export_settings_g4mf_4d.cpp

@@ -21,5 +21,9 @@ void EditorExportSettingsG4MF4D::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("set_compression_format", "compression_format"), &EditorExportSettingsG4MF4D::set_compression_format);
 	ADD_PROPERTY(PropertyInfo(Variant::INT, "compression_format", PROPERTY_HINT_ENUM, "None,Zstd"), "set_compression_format", "get_compression_format");
 
+	ClassDB::bind_method(D_METHOD("get_external_data_mode"), &EditorExportSettingsG4MF4D::get_external_data_mode);
+	ClassDB::bind_method(D_METHOD("set_external_data_mode", "external_data_mode"), &EditorExportSettingsG4MF4D::set_external_data_mode);
+	ADD_PROPERTY(PropertyInfo(Variant::INT, "external_data_mode", PROPERTY_HINT_ENUM, "Automatic,Embed Everything,Separate All Files,Separate Binary Blobs,Separate Resource Files"), "set_external_data_mode", "get_external_data_mode");
+
 	ClassDB::bind_method(D_METHOD("setup", "g4mf_document"), &EditorExportSettingsG4MF4D::setup);
 }

editor/import/g4mf/editor_export_settings_g4mf_4d.h

@@ -6,6 +6,7 @@ class EditorExportSettingsG4MF4D : public RefCounted {
 	GDCLASS(EditorExportSettingsG4MF4D, RefCounted);
 
 	Ref<G4MFDocument4D> _g4mf_document;
+	G4MFState4D::ExternalDataMode _external_data_mode = G4MFState4D::ExternalDataMode::EXTERNAL_DATA_MODE_AUTOMATIC;
 
 protected:
 	static void _bind_methods();
@@ -14,5 +15,8 @@ class EditorExportSettingsG4MF4D : public RefCounted {
 	G4MFDocument4D::CompressionFormat get_compression_format() const;
 	void set_compression_format(const G4MFDocument4D::CompressionFormat p_compression_format);
 
+	G4MFState4D::ExternalDataMode get_external_data_mode() const { return _external_data_mode; }
+	void set_external_data_mode(const G4MFState4D::ExternalDataMode p_external_data_mode) { _external_data_mode = p_external_data_mode; }
+
 	void setup(Ref<G4MFDocument4D> p_g4mf_document);
 };