glTF reader: the rules a real file corrected
Verification / build (pull_request) Failing after 9m17s
CI / verify (pull_request) Failing after 9m17s

Two rules the fixtures asserted in the wrong direction, found by reading CesiumMan.glb:

- MAT4 is an accessor type, and count is the number of elements rather than the number of floats.
  A skin's inverse bind matrices are one MAT4 Float32 accessor whose count is the number of joints,
  and the format allows the count to exceed the joints. The reader required SCALAR and refused the file.
- The BIN chunk type is spelled BIN in the spec and NUL in the files another tool writes, so both
  spellings are accepted, and the chunk codes are built from their characters rather than from a hex
  literal that had the bytes transposed.

The corpus gate now reads the inverse bind matrices, because that is the accessor a skin names and the
one the fixtures could not exercise.

node.matrix is column-major while Mat4 is row-major, and a skin's joints have to be resolved by node
index: in CesiumMan.glb the scene root holds only the mesh node and the nineteen joints hang off a
skeleton node the scene does not reach. Both are recorded on the shapes the reader returns.
This commit is contained in:
litruv
2026-11-03 21:05:43 +11:00
parent bfec51c184
commit da0d13e101
11 changed files with 172 additions and 43 deletions
@@ -14,11 +14,36 @@ public const val GLB_MAGIC: Int = 0x46546C67
/** glTF 2.0 §3.2: the only container version this reader accepts. */ /** glTF 2.0 §3.2: the only container version this reader accepts. */
public const val GLB_VERSION: Int = 2 public const val GLB_VERSION: Int = 2
/** glTF 2.0 §3.2: the chunk type for the JSON data chunk, "JSON" as a little-endian uint32. */ /**
private const val CHUNK_JSON: Int = 0x4E4F4A42 * A four-character chunk type as the little-endian uint32 the container stores.
*
* The codes are built from the characters, not written as hex literals: a little-endian four-character
* code is easy to transpose in hex. The JSON chunk's code here was `0x4E4F4A42`, which reads as "BJON",
* and every file written by another tool failed on it while the fixtures, which used the same wrong
* number, stayed green.
*/
internal fun chunkTypeOf(type: String): Int {
val bytes = type.encodeToByteArray()
return (bytes[0].toInt() and 0xFF) or
((bytes[1].toInt() and 0xFF) shl 8) or
((bytes[2].toInt() and 0xFF) shl 16) or
((bytes[3].toInt() and 0xFF) shl 24)
}
/** glTF 2.0 §3.2: the chunk type for the BIN data chunk, "BIN " as a little-endian uint32. */ /** glTF 2.0 §3.2: the chunk type for the JSON data chunk, "JSON" as a little-endian uint32. */
private const val CHUNK_BIN: Int = 0x004E4942 private val CHUNK_JSON: Int = chunkTypeOf("JSON")
/**
* glTF 2.0 §3.2: the chunk type for the BIN data chunk, "BIN " as a little-endian uint32.
*
* The spec's spelling ends with a space. Files in the wild also carry a NUL there — Khronos's own
* `Box.glb` does — so both are accepted. The character is not read anywhere else, so the two spellings
* name the same chunk, and a reader that accepted only one would reject a valid file.
*/
private val CHUNK_BIN: Int = chunkTypeOf("BIN ")
/** The BIN chunk type as files that spell it with a trailing NUL write it. */
private val CHUNK_BIN_NUL: Int = chunkTypeOf("BIN\u0000")
/** The header is magic, version, and total length: three uint32s. */ /** The header is magic, version, and total length: three uint32s. */
private const val HEADER_BYTES = 12 private const val HEADER_BYTES = 12
@@ -122,7 +147,7 @@ public fun readGlb(data: ByteArray): GlbChunks {
json = payload json = payload
} }
CHUNK_BIN -> { CHUNK_BIN, CHUNK_BIN_NUL -> {
if (bin != null) { if (bin != null) {
throw IllegalArgumentException("more than one BIN chunk") throw IllegalArgumentException("more than one BIN chunk")
} }
@@ -139,23 +139,20 @@ public fun readIndices(file: GltfFile, accessorIndex: Int): IntArray {
/** /**
* Reads one accessor as matrices, element-major, sixteen floats per matrix. * Reads one accessor as matrices, element-major, sixteen floats per matrix.
* *
* glTF 2.0 §3.2.4 states an accessor that carries matrices must be SCALAR Float32. The inverse bind matrices * glTF 2.0 §3.2.4 lists `MAT2`, `MAT3`, and `MAT4` as accessor types, and `count` is the number of elements,
* a skin reads are one accessor of `16 * joints` floats, so the count is the number of floats, not the number of * not the number of floats: a skin's inverse bind matrices are one `MAT4` accessor whose count is the number of
* matrices. * joints. This read takes `MAT4` only, because that is the shape a skin names; `MAT2` and `MAT3` are known to
* the format but nothing here consumes them.
* *
* @param GltfFile file The document and its buffers. * @param GltfFile file The document and its buffers.
* @param Int accessorIndex The accessor to read. * @param Int accessorIndex The accessor to read.
* @return FloatArray `count` floats, a multiple of sixteen. * @return FloatArray `count * 16` floats.
* @throws IllegalArgumentException When the accessor is not SCALAR Float32, or when its count is not a * @throws IllegalArgumentException When the accessor is not `MAT4` Float32, or when [readComponents] rejects it.
* multiple of sixteen.
*/ */
public fun readMatrixElements(file: GltfFile, accessorIndex: Int): FloatArray { public fun readMatrixElements(file: GltfFile, accessorIndex: Int): FloatArray {
val accessor = file.document.accessors[accessorIndex] val accessor = file.document.accessors[accessorIndex]
if (accessor.componentCount() != GltfComponentCount.Scalar || accessor.componentType() != GltfComponentType.Float32) { if (accessor.componentCount() != GltfComponentCount.Mat4) {
throw IllegalArgumentException("accessor $accessorIndex is ${accessor.componentCount()} ${accessor.componentType()}, and a matrix accessor must be SCALAR Float32") throw IllegalArgumentException("accessor $accessorIndex is ${accessor.componentCount()}, and a skin's matrices are MAT4")
}
if (accessor.count % 16 != 0) {
throw IllegalArgumentException("accessor $accessorIndex declares count ${accessor.count}, which is not a multiple of sixteen")
} }
return readFloats(file, accessorIndex) return readFloats(file, accessorIndex)
} }
@@ -44,12 +44,21 @@ public enum class GltfComponentType(val code: Int, val byteSize: Int) {
} }
} }
/** glTF 2.0 §3.2.4: how many components one element holds. */ /**
* glTF 2.0 §3.2.4: how many components one element holds.
*
* The matrix entries are part of the format's type enum even though a reference layer only reads `MAT4`. A
* reader that leaves them out reports a `MAT3` accessor as "not one glTF states", which is a false statement
* about the format rather than an error about the file.
*/
public enum class GltfComponentCount(val code: String, val components: Int) { public enum class GltfComponentCount(val code: String, val components: Int) {
Scalar("SCALAR", 1), Scalar("SCALAR", 1),
Vec2("VEC2", 2), Vec2("VEC2", 2),
Vec3("VEC3", 3), Vec3("VEC3", 3),
Vec4("VEC4", 4); Vec4("VEC4", 4),
Mat2("MAT2", 4),
Mat3("MAT3", 9),
Mat4("MAT4", 16);
public companion object { public companion object {
/** /**
@@ -148,7 +148,17 @@ public data class GltfPrimitive(
public fun mode(): GltfPrimitiveMode = GltfPrimitiveMode.fromCode(modeCode) public fun mode(): GltfPrimitiveMode = GltfPrimitiveMode.fromCode(modeCode)
} }
/** glTF 2.0 §3.2: one node of the scene graph. */ /**
* glTF 2.0 §3.2: one node of the scene graph.
*
* [matrix] is column-major, which is what the format states. Umamo's `Mat4` is row-major, so a caller that
* applies these sixteen values as they are stored applies the transpose - and a transpose is invisible whenever
* the matrix is diagonal, which is the case a test is most likely to pick.
*
* A real file shows why the transform matters: CesiumMan.glb's root node is named `Z_UP` and carries a matrix
* that turns the file's Y-up space into Z-up. The reader does not convert axes, so the caller decides whether
* an imported model arrives in the format's axes or in Umamo's.
*/
@Serializable @Serializable
public data class GltfNode( public data class GltfNode(
val name: String? = null, val name: String? = null,
@@ -161,7 +171,14 @@ public data class GltfNode(
val matrix: List<Float> = emptyList(), val matrix: List<Float> = emptyList(),
) )
/** glTF 2.0 §3.2: one skin - the joints it binds and the inverse bind matrices it reads. */ /**
* glTF 2.0 §3.2: one skin - the joints it binds and the inverse bind matrices it reads.
*
* [joints] are node indices, and they have to be resolved by index rather than by walking the scene: in
* CesiumMan.glb the scene root holds only the mesh node, and the nineteen joints hang off a skeleton node that
* the scene does not reach. A reader that walked the scene graph would find no joints and draw the mesh in its
* bind pose with nothing saying so.
*/
@Serializable @Serializable
public data class GltfSkin( public data class GltfSkin(
val name: String? = null, val name: String? = null,
@@ -212,8 +212,9 @@ private fun firstNodeProblem(file: GltfFile, nodeIndex: Int): String? {
} }
/** /**
* The skin rules for [skinIndex]: it must bind at least one joint, and its inverse bind matrices must be one * The skin rules for [skinIndex]: it must bind at least one joint, and its inverse bind matrices must be a MAT4
* accessor of sixteen floats per joint. * Float32 accessor holding at least one matrix per joint. The count may exceed the joints, which is what the
* format allows and what several exporters do.
* *
* @param GltfFile file The parsed document and its buffers. * @param GltfFile file The parsed document and its buffers.
* @param Int skinIndex The skin to check. * @param Int skinIndex The skin to check.
@@ -237,11 +238,11 @@ private fun firstSkinProblem(file: GltfFile, skinIndex: Int): String? {
return "skin $skinIndex names accessor $accessorIndex, the document has ${file.document.accessors.size}" return "skin $skinIndex names accessor $accessorIndex, the document has ${file.document.accessors.size}"
} }
val accessor = file.document.accessors[accessorIndex] val accessor = file.document.accessors[accessorIndex]
if (GltfComponentCount.fromCode(accessor.componentCountCode) != GltfComponentCount.Scalar || GltfComponentType.fromCode(accessor.componentTypeCode) != GltfComponentType.Float32) { if (GltfComponentCount.fromCode(accessor.componentCountCode) != GltfComponentCount.Mat4 || GltfComponentType.fromCode(accessor.componentTypeCode) != GltfComponentType.Float32) {
return "skin $skinIndex reads its inverse bind matrices from a ${accessor.componentCountCode} ${accessor.componentTypeCode} accessor, and glTF requires SCALAR Float32" return "skin $skinIndex reads its inverse bind matrices from a ${accessor.componentCountCode} ${accessor.componentTypeCode} accessor, and glTF requires MAT4 Float32"
} }
if (accessor.count != skin.joints.size * 16) { if (accessor.count < skin.joints.size) {
return "skin $skinIndex binds ${skin.joints.size} joints, and its inverse bind matrices accessor declares count ${accessor.count}, not ${skin.joints.size * 16}" return "skin $skinIndex binds ${skin.joints.size} joints, and its inverse bind matrices accessor declares count ${accessor.count}, fewer than the joints"
} }
return null return null
} }
@@ -20,6 +20,34 @@ class GlbContainerTest {
assertEquals(json, chunks.jsonText()) assertEquals(json, chunks.jsonText())
} }
@Test
fun chunkTypeCodesComeFromTheirCharacters() {
// The drift guard for a transposed hex literal. The reader carried 0x4E4F4A42 for "JSON", which
// reads as "BJON" little-endian, so every file written by another tool failed while the fixtures,
// built from the same wrong number, stayed green.
assertEquals(0x4E4F534A, chunkTypeOf("JSON"))
assertEquals(0x204E4942, chunkTypeOf("BIN "))
assertEquals(0x004E4942, chunkTypeOf("BIN\u0000"))
assertEquals(GLB_MAGIC, chunkTypeOf("glTF"))
}
@Test
fun acceptsABinChunkSpelledWithANul() {
// §3.2 states "BIN " with a trailing space; Khronos's Box.glb writes a NUL. Both name the same
// chunk, and a reader that accepted only the spec's spelling rejected a real file.
val json = """{"asset":{"version":"2.0"}}"""
val bin = byteArrayOf(1, 2, 3, 4)
val chunks = readGlb(
buildGlbFromChunks(
listOf(
GlbChunkTest(CHUNK_JSON_TEST, padToAlignment(json.encodeToByteArray(), ' '.code.toByte())),
GlbChunkTest(CHUNK_BIN_NUL_TEST, bin),
),
),
)
assertTrue(bin.contentEquals(chunks.binBytes))
}
@Test @Test
fun rejectsAFileShorterThanTheHeader() { fun rejectsAFileShorterThanTheHeader() {
assertFailsWith<IllegalArgumentException> { assertFailsWith<IllegalArgumentException> {
@@ -13,10 +13,13 @@ internal class GlbChunkTest(
) )
/** The JSON chunk type, as a test constant: [CHUNK_JSON] is private to the reader. */ /** The JSON chunk type, as a test constant: [CHUNK_JSON] is private to the reader. */
internal const val CHUNK_JSON_TEST = 0x4E4F4A42 internal val CHUNK_JSON_TEST = chunkTypeOf("JSON")
/** The BIN chunk type, as a test constant: [CHUNK_BIN] is private to the reader. */ /** The BIN chunk type, as a test constant: [CHUNK_BIN] is private to the reader. */
internal const val CHUNK_BIN_TEST = 0x004E4942 internal val CHUNK_BIN_TEST = chunkTypeOf("BIN ")
/** The BIN chunk type spelled with a trailing NUL, which files in the wild write. */
internal val CHUNK_BIN_NUL_TEST = chunkTypeOf("BIN\u0000")
/** An unknown chunk type a reader is required to skip. */ /** An unknown chunk type a reader is required to skip. */
internal const val CHUNK_UNKNOWN_TEST = 0x01000000 internal const val CHUNK_UNKNOWN_TEST = 0x01000000
@@ -127,17 +127,19 @@ class GltfAccessorTest {
} }
@Test @Test
fun readsMatricesOnlyFromAScalarFloat32Accessor() { fun readsMatricesOnlyFromAMat4Float32Accessor() {
val bin = floatBytes(1f, 0f, 0f, 0f, 0f, 1f, 0f, 0f, 0f, 0f, 1f, 0f, 0f, 0f, 0f, 1f) val bin = floatBytes(1f, 0f, 0f, 0f, 0f, 1f, 0f, 0f, 0f, 0f, 1f, 0f, 0f, 0f, 0f, 1f)
val json = jsonWith(bin.size, byteOffset = 0, componentTypeCode = 5126, componentCountCode = "SCALAR", count = 16) // A skin's inverse bind matrices are one MAT4 accessor whose count is the number of joints, so one joint
// is one element of sixteen floats. Reading count as the number of floats is what made a real file fail.
val json = jsonWith(bin.size, byteOffset = 0, componentTypeCode = 5126, componentCountCode = "MAT4", count = 1)
assertEquals(16, readMatrixElements(file(json, bin), 0).size) assertEquals(16, readMatrixElements(file(json, bin), 0).size)
val notScalar = jsonWith(bin.size, byteOffset = 0, componentTypeCode = 5126, componentCountCode = "VEC4", count = 4) val notMatrix = jsonWith(bin.size, byteOffset = 0, componentTypeCode = 5126, componentCountCode = "VEC4", count = 4)
assertFailsWith<IllegalArgumentException> { assertFailsWith<IllegalArgumentException> {
readMatrixElements(file(notScalar, bin), 0) readMatrixElements(file(notMatrix, bin), 0)
} }
val notSixteen = jsonWith(bin.size, byteOffset = 0, componentTypeCode = 5126, componentCountCode = "SCALAR", count = 12) val notFloat = jsonWith(bin.size, byteOffset = 0, componentTypeCode = 5123, componentCountCode = "MAT4", count = 1)
assertFailsWith<IllegalArgumentException> { assertFailsWith<IllegalArgumentException> {
readMatrixElements(file(notSixteen, bin), 0) readMatrixElements(file(notFloat, bin), 0)
} }
} }
@@ -57,7 +57,7 @@ class GltfSceneGraphTest {
val bin = floatBytes(1f, 0f, 0f, 0f, 0f, 1f, 0f, 0f, 0f, 0f, 1f, 0f, 0f, 0f, 0f, 1f) val bin = floatBytes(1f, 0f, 0f, 0f, 0f, 1f, 0f, 0f, 0f, 0f, 1f, 0f, 0f, 0f, 0f, 1f)
val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":${bin.size}}],""" + val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":${bin.size}}],""" +
""""bufferViews":[{"buffer":0,"byteOffset":0,"byteLength":${bin.size}}],""" + """"bufferViews":[{"buffer":0,"byteOffset":0,"byteLength":${bin.size}}],""" +
""""accessors":[{"bufferView":0,"byteOffset":0,"componentType":5126,"type":"SCALAR","count":16}],""" + """"accessors":[{"bufferView":0,"byteOffset":0,"componentType":5126,"type":"MAT4","count":1}],""" +
""""nodes":[{}],"skins":[{"joints":[0],"inverseBindMatrices":0}]}""" """"nodes":[{}],"skins":[{"joints":[0],"inverseBindMatrices":0}]}"""
val file = GltfFile(decodeGltfJson(json), listOf(bin)) val file = GltfFile(decodeGltfJson(json), listOf(bin))
val matrices = readMatrixElements(file, 0) val matrices = readMatrixElements(file, 0)
@@ -121,13 +121,34 @@ class GltfValidationTest {
} }
@Test @Test
fun refusesASkinWhoseInverseBindMatricesDoNotMatchItsJoints() { fun refusesASkinWhoseInverseBindMatricesAreNotMat4Float32() {
// The accessor is sound on its own, so the first problem is the skin's own count. val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":64}],""" +
val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":128}],""" + """"bufferViews":[{"buffer":0,"byteOffset":0,"byteLength":64}],""" +
""""bufferViews":[{"buffer":0,"byteOffset":0,"byteLength":128}],""" + """"accessors":[{"bufferView":0,"byteOffset":0,"componentType":5126,"type":"SCALAR","count":16}],""" +
""""accessors":[{"bufferView":0,"byteOffset":0,"componentType":5126,"type":"SCALAR","count":32}],""" +
""""skins":[{"joints":[0],"inverseBindMatrices":0}],"nodes":[{}]}""" """"skins":[{"joints":[0],"inverseBindMatrices":0}],"nodes":[{}]}"""
assertEquals("skin 0 binds 1 joints, and its inverse bind matrices accessor declares count 32, not 16", problem(json, ByteArray(128))) assertEquals("skin 0 reads its inverse bind matrices from a SCALAR 5126 accessor, and glTF requires MAT4 Float32", problem(json, ByteArray(64)))
}
@Test
fun refusesASkinWhoseInverseBindMatricesHaveFewerMatricesThanJoints() {
// The accessor is sound on its own - one MAT4 element is 64 bytes - so the first problem is the skin's own
// count, not the buffer view.
val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":64}],""" +
""""bufferViews":[{"buffer":0,"byteOffset":0,"byteLength":64}],""" +
""""accessors":[{"bufferView":0,"byteOffset":0,"componentType":5126,"type":"MAT4","count":1}],""" +
""""skins":[{"joints":[0,1],"inverseBindMatrices":0}],"nodes":[{},{}]}"""
assertEquals("skin 0 binds 2 joints, and its inverse bind matrices accessor declares count 1, fewer than the joints", problem(json, ByteArray(64)))
}
@Test
fun acceptsASkinWhoseMatrixAccessorHoldsMoreMatricesThanJoints() {
// The format allows count to exceed the joints, and exporters do write a padded accessor, so a reader
// that required an exact match rejected a sound file.
val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":192}],""" +
""""bufferViews":[{"buffer":0,"byteOffset":0,"byteLength":192}],""" +
""""accessors":[{"bufferView":0,"byteOffset":0,"componentType":5126,"type":"MAT4","count":3}],""" +
""""skins":[{"joints":[0],"inverseBindMatrices":0}],"nodes":[{}]}"""
assertNull(problem(json, ByteArray(192)))
} }
@Test @Test
@@ -19,11 +19,25 @@ class GltfCorpusTest {
* Locates every GLB sample: `-Dgltf.samples` when set, else the `test/corpus/gltf` directory found by walking * Locates every GLB sample: `-Dgltf.samples` when set, else the `test/corpus/gltf` directory found by walking
* up from the working directory. * up from the working directory.
* *
* The property may name files or a directory, because the corpus default the build forwards is the directory.
* A property that resolves to nothing is not silently dropped: the caller then falls back to the walk-up, so a
* gate that cannot find its samples still reports that it skipped rather than passing on an empty list.
*
* @return List<File> The sample files, empty when none are configured. * @return List<File> The sample files, empty when none are configured.
*/ */
private fun locateSamples(): List<File> { private fun locateSamples(): List<File> {
System.getProperty("gltf.samples")?.let { value -> System.getProperty("gltf.samples")?.let { value ->
return value.split(',').map { path -> File(path) }.filter(File::isFile).sortedBy { it.name } val named = value.split(',').map { path -> File(path) }
val files = named.flatMap { entry ->
if (entry.isDirectory) {
entry.listFiles { file -> file.isFile && file.extension.equals("glb", ignoreCase = true) }?.toList() ?: emptyList()
} else {
listOf(entry)
}
}
if (files.isNotEmpty()) {
return files.sortedBy { it.name }
}
} }
var directory: File? = File(System.getProperty("user.dir")) var directory: File? = File(System.getProperty("user.dir"))
while (directory != null) { while (directory != null) {
@@ -71,7 +85,19 @@ class GltfCorpusTest {
} }
} }
} }
println("read ${sample.name}: ${file.document.meshes.size} meshes, ${file.document.nodes.size} nodes, ${file.document.skins.size} skins, $positionComponentsRead position components") var skinsRead = 0
for (skin in file.document.skins) {
// When the file names no accessor, glTF says each matrix is the identity, so there is nothing to
// read; the point of the corpus is the files that do carry one.
val accessorIndex = skin.inverseBindMatricesAccessorIndex
if (accessorIndex != null) {
val matrices = readMatrixElements(file, accessorIndex)
assertTrue(matrices.size >= skin.joints.size * 16, "${sample.name}: skin ${file.document.skins.indexOf(skin)} read ${matrices.size} floats for ${skin.joints.size} joints")
assertTrue(matrices.all { value -> value.isFinite() }, "${sample.name}: every inverse bind matrix is finite")
skinsRead += 1
}
}
println("read ${sample.name}: ${file.document.meshes.size} meshes, ${file.document.nodes.size} nodes, ${file.document.skins.size} skins ($skinsRead with matrices), $positionComponentsRead position components")
} }
} }
} }