diff --git a/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GlbReader.kt b/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GlbReader.kt index a736dc8..586f8a0 100644 --- a/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GlbReader.kt +++ b/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GlbReader.kt @@ -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") } diff --git a/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfAccessor.kt b/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfAccessor.kt index 1cab27e..c7d468d 100644 --- a/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfAccessor.kt +++ b/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfAccessor.kt @@ -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) } diff --git a/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfEnums.kt b/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfEnums.kt index edfc18e..3c5936c 100644 --- a/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfEnums.kt +++ b/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfEnums.kt @@ -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 { /** diff --git a/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfJson.kt b/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfJson.kt index 1252f67..b83452f 100644 --- a/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfJson.kt +++ b/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfJson.kt @@ -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 = 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, diff --git a/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfValidation.kt b/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfValidation.kt index 5b7b331..ea3493e 100644 --- a/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfValidation.kt +++ b/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfValidation.kt @@ -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 } diff --git a/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GlbContainerTest.kt b/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GlbContainerTest.kt index 7b7db1b..6e61cdc 100644 --- a/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GlbContainerTest.kt +++ b/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GlbContainerTest.kt @@ -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 { diff --git a/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GlbFixtures.kt b/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GlbFixtures.kt index 95ba577..1e3b338 100644 --- a/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GlbFixtures.kt +++ b/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GlbFixtures.kt @@ -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 diff --git a/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfAccessorTest.kt b/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfAccessorTest.kt index 0f74e17..86fa481 100644 --- a/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfAccessorTest.kt +++ b/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfAccessorTest.kt @@ -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 { - 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 { - readMatrixElements(file(notSixteen, bin), 0) + readMatrixElements(file(notFloat, bin), 0) } } diff --git a/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfSceneGraphTest.kt b/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfSceneGraphTest.kt index cbee8ec..d305e3e 100644 --- a/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfSceneGraphTest.kt +++ b/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfSceneGraphTest.kt @@ -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) diff --git a/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfValidationTest.kt b/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfValidationTest.kt index a47a869..5084f65 100644 --- a/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfValidationTest.kt +++ b/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfValidationTest.kt @@ -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 diff --git a/module/format/src/jvmTest/kotlin/org/umamo/format/gltf/GltfCorpusTest.kt b/module/format/src/jvmTest/kotlin/org/umamo/format/gltf/GltfCorpusTest.kt index 9960ed7..f5bbcb1 100644 --- a/module/format/src/jvmTest/kotlin/org/umamo/format/gltf/GltfCorpusTest.kt +++ b/module/format/src/jvmTest/kotlin/org/umamo/format/gltf/GltfCorpusTest.kt @@ -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 The sample files, empty when none are configured. */ private fun locateSamples(): List { 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") } } }