PR 1 — :format: glTF/GLB reader for the reference layer #2

Open
litruv wants to merge 2 commits from issue-1-gltf-glb-reader into main
11 changed files with 172 additions and 43 deletions
Showing only changes of commit da0d13e101 - Show all commits
@@ -14,11 +14,36 @@ public const val GLB_MAGIC: Int = 0x46546C67
/** glTF 2.0 §3.2: the only container version this reader accepts. */
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. */
private const val CHUNK_BIN: Int = 0x004E4942
/** glTF 2.0 §3.2: the chunk type for the JSON data chunk, "JSON" as a little-endian uint32. */
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. */
private const val HEADER_BYTES = 12
@@ -122,7 +147,7 @@ public fun readGlb(data: ByteArray): GlbChunks {
json = payload
}
CHUNK_BIN -> {
CHUNK_BIN, CHUNK_BIN_NUL -> {
if (bin != null) {
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.
*
* glTF 2.0 §3.2.4 states an accessor that carries matrices must be SCALAR Float32. The inverse bind matrices
* a skin reads are one accessor of `16 * joints` floats, so the count is the number of floats, not the number of
* matrices.
* glTF 2.0 §3.2.4 lists `MAT2`, `MAT3`, and `MAT4` as accessor types, and `count` is the number of elements,
* not the number of floats: a skin's inverse bind matrices are one `MAT4` accessor whose count is the number of
* 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 Int accessorIndex The accessor to read.
* @return FloatArray `count` floats, a multiple of sixteen.
* @throws IllegalArgumentException When the accessor is not SCALAR Float32, or when its count is not a
* multiple of sixteen.
* @return FloatArray `count * 16` floats.
* @throws IllegalArgumentException When the accessor is not `MAT4` Float32, or when [readComponents] rejects it.
*/
public fun readMatrixElements(file: GltfFile, accessorIndex: Int): FloatArray {
val accessor = file.document.accessors[accessorIndex]
if (accessor.componentCount() != GltfComponentCount.Scalar || accessor.componentType() != GltfComponentType.Float32) {
throw IllegalArgumentException("accessor $accessorIndex is ${accessor.componentCount()} ${accessor.componentType()}, and a matrix accessor must be SCALAR Float32")
}
if (accessor.count % 16 != 0) {
throw IllegalArgumentException("accessor $accessorIndex declares count ${accessor.count}, which is not a multiple of sixteen")
if (accessor.componentCount() != GltfComponentCount.Mat4) {
throw IllegalArgumentException("accessor $accessorIndex is ${accessor.componentCount()}, and a skin's matrices are MAT4")
}
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) {
Scalar("SCALAR", 1),
Vec2("VEC2", 2),
Vec3("VEC3", 3),
Vec4("VEC4", 4);
Vec4("VEC4", 4),
Mat2("MAT2", 4),
Mat3("MAT3", 9),
Mat4("MAT4", 16);
public companion object {
/**
@@ -148,7 +148,17 @@ public data class GltfPrimitive(
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
public data class GltfNode(
val name: String? = null,
@@ -161,7 +171,14 @@ public data class GltfNode(
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
public data class GltfSkin(
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
* accessor of sixteen floats per joint.
* The skin rules for [skinIndex]: it must bind at least one joint, and its inverse bind matrices must be a MAT4
* 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 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}"
}
val accessor = file.document.accessors[accessorIndex]
if (GltfComponentCount.fromCode(accessor.componentCountCode) != GltfComponentCount.Scalar || 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"
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 MAT4 Float32"
}
if (accessor.count != skin.joints.size * 16) {
return "skin $skinIndex binds ${skin.joints.size} joints, and its inverse bind matrices accessor declares count ${accessor.count}, not ${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}, fewer than the joints"
}
return null
}
@@ -20,6 +20,34 @@ class GlbContainerTest {
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
fun rejectsAFileShorterThanTheHeader() {
assertFailsWith<IllegalArgumentException> {
@@ -13,10 +13,13 @@ internal class GlbChunkTest(
)
/** 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. */
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. */
internal const val CHUNK_UNKNOWN_TEST = 0x01000000
@@ -127,17 +127,19 @@ class GltfAccessorTest {
}
@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 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)
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> {
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> {
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 json = """{"asset":{"version":"2.0"},"buffers":[{"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}]}"""
val file = GltfFile(decodeGltfJson(json), listOf(bin))
val matrices = readMatrixElements(file, 0)
@@ -121,13 +121,34 @@ class GltfValidationTest {
}
@Test
fun refusesASkinWhoseInverseBindMatricesDoNotMatchItsJoints() {
// 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":128}],""" +
""""bufferViews":[{"buffer":0,"byteOffset":0,"byteLength":128}],""" +
""""accessors":[{"bufferView":0,"byteOffset":0,"componentType":5126,"type":"SCALAR","count":32}],""" +
fun refusesASkinWhoseInverseBindMatricesAreNotMat4Float32() {
val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":64}],""" +
""""bufferViews":[{"buffer":0,"byteOffset":0,"byteLength":64}],""" +
""""accessors":[{"bufferView":0,"byteOffset":0,"componentType":5126,"type":"SCALAR","count":16}],""" +
""""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
@@ -19,11 +19,25 @@ class GltfCorpusTest {
* Locates every GLB sample: `-Dgltf.samples` when set, else the `test/corpus/gltf` directory found by walking
* 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.
*/
private fun locateSamples(): List<File> {
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"))
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")
}
}
}