KhronosGroup / KhronosGroup/glTF

[glTF 2.1] Unified File References

Open
#2,590 0 comments 0 reactions 0 assignees View on GitHub
2.1
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.