Skip to content

feat: Add support for importing 64-bit GLB version 3 files#51

Open
aaronfranke wants to merge 1 commit into
Unity-Technologies:mainfrom
aaronfranke:support-glb3
Open

feat: Add support for importing 64-bit GLB version 3 files#51
aaronfranke wants to merge 1 commit into
Unity-Technologies:mainfrom
aaronfranke:support-glb3

Conversation

@aaronfranke

@aaronfranke aaronfranke commented Jun 22, 2026

Copy link
Copy Markdown

This PR adds the ability for glTFast to import 64-bit glTF binary format version 3 files. This GLB version 3 format is being defined as part of glTF 2.1, but the format itself is not tied to glTF 2.1: you can use a version 2 file to hold glTF 2.1 data, or use a version 3 file to hold glTF 2.0 data. It's this latter case which this PR supports. KhronosGroup/glTF#2594

This is not all of the changes to the .glb format that will be required for glTF 2.1. There will also be a more flexible chunk layout and support for multiple binary chunks. However, that will require changes to the parsing of the actual glTF JSON data as well, and that part has not yet been standardized, and I want to try and avoid sending in a massive unreviewable blob of all the changes all at once, so I am submitting this PR to just add support for GLB version 3 with the same layout.

I have added a new test case for this, and ran the tests to confirm it works. The file is named FormatVariantsGLB3.glb. This file is an exact duplicate of the existing FormatVariants.glb test asset except with the binary format version changed. I also tested that this file loads in my experimental Godot Engine branch for glTF 2.1.

Here is a bulleted list of what specifically this PR changes and why:

  • GlbBinChunk is primarily used to store buffers, not chunks. And furthermore, it stores the Start and Length, but not any actual data. Therefore, I renamed it to GltfBufferRange.
  • Rename m_BinChunks to m_BufferRanges. The old name was incorrect, it's not the bin chunks, it's the buffers, since it includes buffers read from URIs. This new name correctly identifies what it does.
  • Renamed m_Buffers to m_BufferData to clarify that this holds the actual data.
  • Change the data types of GltfBufferRange to long. While NativeArray is limited to 32-bit sizes, we should still use larger data types in glTFast code, for alignment with glTF, and to enable better debugging and error messages.
  • Add ReadUInt64 and also change ReadUInt32 to accept long as input.
  • Add GltfBinaryTooLarge and GltfUnsupportedChunkEncoding to the log message enum.
  • Change the data types of totalLength and index to long, and set them differently based on version 2 or 3.
  • Introduce a new k_MaxByteArraySize constant and compare the total file length to it. While the input data is already limited by NativeArray, this explicitly guards the declared file size, which might help with truncated files. In practice it's not super important, though, I can remove it if desired.
  • Read chunk headers differently depending on binary format version.
  • Error on any non-zero chunk encoding (only for binary format version 3 files). Plain encoding is the only type that is required to be supported by glTF 2.1. We could add more in the future if desired, for example Godot will support Zstd compression, but for now just support plain encoding.
  • Ensure the start of chunks is aligned properly.
  • Improve the docs for IBufferView.ByteStride.
  • Improve the description of GltfBufferRange in graph.json (idk what this file is but may as well).

I made a similar PR to UnityGLTF: KhronosGroup/UnityGLTF#905

@cla-assistant-unity

cla-assistant-unity Bot commented Jun 22, 2026

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant