KhronosGroup / KhronosGroup/glTF
[glTF 2.1] Unified File References
- Dominant language
- HTML
- Stars
- 7.8k
- Forks
- 1.2k
- Avg merge
- 17h 26m
- Merged PRs (30d)
- 5
Description
# Unified File References
glTF 2.1 defines a new `files` array for referencing external files in a unified way. This array works like the existing `buffers` and `images` arrays, but can be used for any type of file. Additionally, the `"mimeType"` property is required for files.
The `files` array will be used for all new types of files added in the future. The existing `buffers` and `images` arrays are kept as-is for those file types.
Cyclical references between files are strictly prohibited.
## Use cases
With glTF 2.0, extensions which reference external files need to define their own arrays for those files. This approach quickly runs into 2 problems:
- Extensions need to redefine the same pattern over and over: an array of files, each with `"uri"`, `"bufferView"`, and `"mimeType"` properties.
- Tools cannot reliably discover external file dependencies without understanding every extension.
For example, the `EXT_lights_ies` extension added an additional `lights` array repeating the aforementioned pattern inside the extension object.
glTF 2.1 solves these problems by providing a unified way to reference external files, simplifying both extensions and tools.
There are basic operations that should be possible to do with trivial simple implementations of glTF, but which actually end up being impossible unless they support every single extension that defines external file references. For example:
- A packing tool that packs glTF file(s) into a self-contained `.glb` file.
- A file picker dialog that allows the user to select a `.gltf` file, and then uploads the entire model including all of its dependencies.
- A validation tool that checks if a glTF file is valid and needs to check for all the files used by the glTF.
With glTF 2.1, tools only need to look in 3 places for external files: `buffers`, `images`, and `files`.
## Example
> [!NOTE]
> Examples are illustrative and not exhaustive.
```json
{
"buffers": [
{
"uri": "buffer0.bin"
}
],
"images": [
{
"mimeType": "image/png",
"uri": "texture.png"
}
],
"files": [
{
"mimeType": "model/gltf-binary",
"uri": "model.glb"
},
{
"mimeType": "audio/mpeg",
"uri": "audio.mp3"
},
{
"mimeType": "video/mp4",
"uri": "video.mp4"
}
]
}
```
## Why this design
Without unified file references, the glTF file would need to look like this instead, which causes the problems described above:
```json
{
"buffers": [
{
"uri": "buffer0.bin"
}
],
"images": [
{
"mimeType": "image/png",
"uri": "texture.png"
}
],
"externalAssets": [
{
"mimeType": "model/gltf-binary",
"uri": "model.glb"
}
],
"extensions": {
"KHR_audio_emitter": {
"audio": [
{
"mimeType": "audio/mpeg",
"uri": "audio.mp3"
}
]
},
"KHR_texture_video": {
"videos": [
{
"mimeType": "video/mp4",
"uri": "video.mp4"
}
]
}
}
}
```
Contributor guide
Research direction
No repository files, tests, or entry points are identified in the issue, so first locate where the glTF specification defines buffers and images. Review the surrounding schema and reference rules, then determine how the proposed files array, required mimeType, and prohibition on cyclical references should be represented while preserving the existing buffers and images arrays.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- json
- Domain
- computer-graphics
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100