GLTF: Allow controlling how external data is handled on export

[aaronfranke]

In master, Godot gives you 2 options for exporting, determined only by file type:

• Exporting a .glb file embeds binary data into a self-contained file (so long as it fits in the 4 GiB limit).
  • This is equivalent to Blender's "glTF Binary (.glb)" export option.
• Exporting a .gltf file separates out all data into files, such as images into image files, and buffers into .bin files.
  • This is equivalent to Blender's "glTF Separate (.gltf + .bin + textures)" export option.

However, there are more possibilities available than just those two. Blender offers another option called "glTF Embedded (.gltf)" which embeds all data into a text-based .gltf. This PR allows doing that with the "Embed Everything" option. Still... there are more possibilities than just those three, so this PR adds a comprehensive enum:

The default option is "Automatic", which behaves the same as the current behavior in master.

---

• Automatic
  • When exporting a glTF file, automatically determines if data should be embedded or separated based on the file extension used and if base_path is valid. With this option, exporting a .gltf file with a valid [member base_path] will behave like "Separate All Files". If exporting a .glb file, exporting to an in-memory buffer, or exporting with base_path set to an empty string, this will behave like "Embed Everything".
  • This option is suitable for most use cases. It behaves like Blender's "glTF Binary (.glb)" export option for .glb files, and like Blender's "glTF Separate (.gltf + .bin + textures)" export option for .gltf files.
• Embed Everything
  • When exporting a glTF file, embeds all data in the glTF file, including images and binary buffers. For .glb files, this will use the binary blob chunk at the end of the file to store the data in buffer 0 (if present). For all other buffers, such as buffers in .gltf files, the data will be embedded as a base64-encoded string in the JSON of the buffer.
  • This option is useful when you want a single self-contained file. It behaves like Blender's "glTF Binary (.glb)" export option for .glb files, and like Blender's "glTF Embedded (.gltf)" export option for .gltf files.
• Separate All Files
  • When exporting a glTF 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 glTF buffers, into separate .bin files.
  • This option is useful when having the glTF 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.
• Separate Binary Blobs
  • When exporting a glTF file, separates all raw binary blobs, such as glTF buffers, into separate .bin files. Resources that can be saved in their own file formats, such as images, are embedded within glTF buffers, and are stored in the .bin 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 glTF file and a single .bin file next to it.
• Separate Resource Files
  • When exporting a glTF 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 glTF file.
  • This option is useful if the exported glTF 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.

---

For example, the options would look like this:

Embed Everything
file.gltf/glb (contains file.bin and texture.png)

Separate All Files
file.gltf/glb
file.bin
texture.png

Separate Binary Blobs
file.gltf/glb
file.bin (contains texture.png)

Separate Resource Files
file.gltf/glb (contains file.bin)
texture.png

---

Effectively, this enum serves to answer two questions:

• Should resource files, like images, be embedded in the buffers, or separated out into their own files?
• Should binary blobs, like buffers, be embedded into the glTF file, or separated out into their own files?

Extensions should respect these options by calling GLTFState.should_separate_resource_files() to determine if they should save their resources in separate files.

---

Test project: gltf_export_external_data_mode.zip

In the test project, each folder contains the same test cube exported with different choices for the enum. The glb/automatic/ and glb/embed_everything/ folders are equivalent, and the gltf/automatic/ and gltf/separate_all_files/ folders are equivalent, but are included for completeness.