From 385b8fafa66699028263819d8fa82a8de49f4ddf Mon Sep 17 00:00:00 2001 From: litruv Date: Tue, 3 Nov 2026 19:18:42 +1100 Subject: [PATCH] glTF/GLB reader for the reference layer (#1) Container rules: JSON chunk first, BIN second, chunk length multiple of 4, declared total length must equal actual, unknown chunk types skipped, duplicate known types refused. Accessor rules: byteOffset must be a multiple of the component size, reads must stay inside byteLength, sparse refused, normalized not applied, component type 5124 (INT) added. FileRole.Reference and FileKind.Gltf added; codec registered in FormatRegistry. Tests: 58 glTF tests, `:format:jvmTest` green. --- module/format/build.gradle.kts | 3 + .../kotlin/org/umamo/format/FileKind.kt | 17 ++ .../kotlin/org/umamo/format/gltf/GlbReader.kt | 177 ++++++++++++ .../kotlin/org/umamo/format/gltf/Gltf.kt | 78 +++++ .../org/umamo/format/gltf/GltfAccessor.kt | 161 +++++++++++ .../kotlin/org/umamo/format/gltf/GltfEnums.kt | 144 ++++++++++ .../kotlin/org/umamo/format/gltf/GltfFile.kt | 27 ++ .../kotlin/org/umamo/format/gltf/GltfJson.kt | 178 ++++++++++++ .../org/umamo/format/gltf/GltfValidation.kt | 268 ++++++++++++++++++ .../org/umamo/format/gltf/GlbContainerTest.kt | 147 ++++++++++ .../org/umamo/format/gltf/GlbFixtures.kt | 156 ++++++++++ .../org/umamo/format/gltf/GltfAccessorTest.kt | 174 ++++++++++++ .../umamo/format/gltf/GltfJsonDepthTest.kt | 36 +++ .../umamo/format/gltf/GltfSceneGraphTest.kt | 68 +++++ .../umamo/format/gltf/GltfValidationTest.kt | 147 ++++++++++ .../kotlin/org/umamo/format/FormatRegistry.kt | 13 +- .../org/umamo/format/gltf/GltfCodecTest.kt | 72 +++++ .../org/umamo/format/gltf/GltfCorpusTest.kt | 77 +++++ 18 files changed, 1937 insertions(+), 6 deletions(-) create mode 100644 module/format/src/commonMain/kotlin/org/umamo/format/gltf/GlbReader.kt create mode 100644 module/format/src/commonMain/kotlin/org/umamo/format/gltf/Gltf.kt create mode 100644 module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfAccessor.kt create mode 100644 module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfEnums.kt create mode 100644 module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfFile.kt create mode 100644 module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfJson.kt create mode 100644 module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfValidation.kt create mode 100644 module/format/src/commonTest/kotlin/org/umamo/format/gltf/GlbContainerTest.kt create mode 100644 module/format/src/commonTest/kotlin/org/umamo/format/gltf/GlbFixtures.kt create mode 100644 module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfAccessorTest.kt create mode 100644 module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfJsonDepthTest.kt create mode 100644 module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfSceneGraphTest.kt create mode 100644 module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfValidationTest.kt create mode 100644 module/format/src/jvmTest/kotlin/org/umamo/format/gltf/GltfCodecTest.kt create mode 100644 module/format/src/jvmTest/kotlin/org/umamo/format/gltf/GltfCorpusTest.kt diff --git a/module/format/build.gradle.kts b/module/format/build.gradle.kts index 1cdd986..f71f18b 100644 --- a/module/format/build.gradle.kts +++ b/module/format/build.gradle.kts @@ -167,6 +167,9 @@ umamoTestCorpus { // dump never floods build/ on a plain test run. "cmo3.resave", ) + // GltfCorpusTest walks the whole gltf/ corpus. A module-specific default rather than a shared-table + // entry: no other module reads glTF yet, and a table entry would switch its gate on as a side effect. + sampleWithCorpusDefault("gltf.samples", "gltf") // ModelGenerator's on-switch — a boolean, not a path, so it goes through `flag` and skips the // file-existence check. Without the forwarding the generator reads a property nobody set and // returns immediately: a @Test reporting PASSED while generating nothing. diff --git a/module/format/src/commonMain/kotlin/org/umamo/format/FileKind.kt b/module/format/src/commonMain/kotlin/org/umamo/format/FileKind.kt index 1423c10..f5f130b 100644 --- a/module/format/src/commonMain/kotlin/org/umamo/format/FileKind.kt +++ b/module/format/src/commonMain/kotlin/org/umamo/format/FileKind.kt @@ -17,6 +17,13 @@ enum class FileRole { /** Read beside a document, never opened as one: the MOC3 JSON family. */ Sidecar, + + /** + * Read into the editor as a reference, not as the document and not as source art: a poseable 3D model drawn + * behind or above the puppet. It is never merged into the puppet, so it cannot replace what is open (the + * Document role) or add layers to it (the Artwork role). + */ + Reference, } /** @@ -142,4 +149,14 @@ sealed interface FileKind { override val writable = false override val role = FileRole.Artwork } + + // --- glTF 3D Reference Model --- + data object Gltf : FileKind { + /** A GLB is the binary container; the extension the format is named for is the alias. */ + override val extension = "glb" + override val extensionAliases = listOf("gltf") + override val readable = true + override val writable = false + override val role = FileRole.Reference + } } \ No newline at end of file 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 new file mode 100644 index 0000000..a736dc8 --- /dev/null +++ b/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GlbReader.kt @@ -0,0 +1,177 @@ +package org.umamo.format.gltf + +import org.umamo.format.binary.ByteReader + +/* + * The GLB container (glTF 2.0 §3.2): a 12-byte header, then chunks of a declared length and a four-character + * type. This is the part of the reader most likely to be wrong, and it is testable without a GPU or an asset, + * which is why it is its own seam rather than a step inside the JSON parse. + */ + +/** glTF 2.0 §3.2: the header magic, "glTF" read as a little-endian uint32. */ +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 + +/** 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 + +/** The header is magic, version, and total length: three uint32s. */ +private const val HEADER_BYTES = 12 + +/** A chunk is its length and its type: two uint32s before the data. */ +private const val CHUNK_HEADER_BYTES = 8 + +/** glTF 2.0 §3.2: chunk data is padded to a 4-byte boundary, so every chunk length is a multiple of four. */ +private const val CHUNK_ALIGNMENT = 4 + +/** glTF 2.0 §3.2: the byte the JSON chunk pads with. */ +private const val JSON_PADDING_BYTE = 0x20 + +/** + * The two chunks a GLB carries, in the order they were read. + * + * @property ByteArray jsonBytes The JSON chunk as the file holds it, padding included. + * @property ByteArray binBytes The BIN chunk, or an empty array when the file carries none. + */ +public class GlbChunks( + public val jsonBytes: ByteArray, + public val binBytes: ByteArray, +) { + /** + * The JSON chunk as text, with its trailing padding removed. + * + * The padding is part of the chunk length, so handing [jsonBytes] to the parser as content would feed it + * bytes the format says are not part of the JSON value. + * + * @return String The JSON text. + */ + public fun jsonText(): String = jsonBytes.decodeToString().trimEnd { character -> character == ' ' } + + /** + * Whether the BIN chunk holds [byteLength] bytes, the length buffer 0 declares. + * + * @param Int byteLength The declared buffer length. + * @return Boolean True when the chunk is at least that long. + */ + public fun binHolds(byteLength: Int): Boolean = binBytes.size >= byteLength +} + +/** + * Reads the GLB container. + * + * Four rules that are easy to get wrong, enforced here rather than assumed: + * + * 1. The declared total length must equal the actual length. A file that declares more than it holds reads + * as a truncated chunk, and a truncated chunk is an error, not a short read. + * 2. Chunk data is padded to a 4-byte boundary, so a chunk length that is not a multiple of four is not a + * chunk the format allows. + * 3. The JSON chunk must be the first chunk, and the BIN chunk must follow it when present. + * 4. An unknown chunk type is skipped, not rejected: a GLB with an extra chunk is still a valid GLB. More + * than one chunk of a known type is not. + * + * @param ByteArray data The whole file. + * @return GlbChunks The JSON and BIN chunks. + * @throws IllegalArgumentException When the header, the declared length, the alignment, the chunk order, or a + * duplicate chunk type does not match what glTF 2.0 §3.2 states. + */ +public fun readGlb(data: ByteArray): GlbChunks { + if (data.size < HEADER_BYTES) { + throw IllegalArgumentException("shorter than the $HEADER_BYTES-byte GLB header") + } + val reader = ByteReader(data, littleEndian = true) + if (reader.u32AsInt(0) != GLB_MAGIC) { + throw IllegalArgumentException("magic is not 'glTF'") + } + val version = reader.u32AsInt(4) + if (version != GLB_VERSION) { + throw IllegalArgumentException("container version $version, this reader accepts $GLB_VERSION") + } + val declared = reader.u32(8) + if (declared != data.size.toLong()) { + throw IllegalArgumentException("declared length $declared, actual ${data.size}") + } + + var json: ByteArray? = null + var bin: ByteArray? = null + var position = HEADER_BYTES + var chunkIndex = 0 + while (position + CHUNK_HEADER_BYTES <= data.size) { + val length = reader.u32AsInt(position) + val type = reader.u32AsInt(position + 4) + val start = position + CHUNK_HEADER_BYTES + if (start + length > data.size) { + throw IllegalArgumentException("the chunk at $position declares $length bytes, only ${data.size - start} remain") + } + if (length % CHUNK_ALIGNMENT != 0) { + throw IllegalArgumentException("the chunk at $position declares $length bytes, which is not a multiple of $CHUNK_ALIGNMENT") + } + val payload = data.copyOfRange(start, start + length) + when (type) { + CHUNK_JSON -> { + if (json != null) { + throw IllegalArgumentException("more than one JSON chunk") + } + if (chunkIndex != 0) { + throw IllegalArgumentException("the JSON chunk is the ${chunkIndex + 1}th chunk; glTF states it must be the first") + } + json = payload + } + + CHUNK_BIN -> { + if (bin != null) { + throw IllegalArgumentException("more than one BIN chunk") + } + if (json == null) { + throw IllegalArgumentException("the BIN chunk comes before the JSON chunk") + } + bin = payload + } + + // An unknown type is skipped, not rejected. + else -> {} + } + position = start + length + chunkIndex++ + } + + if (json == null) { + throw IllegalArgumentException("no JSON chunk") + } + return GlbChunks(json, bin ?: ByteArray(0)) +} + +/** + * Whether [candidateBytes] opens with the GLB magic. + * + * @param ByteArray candidateBytes The file contents to test. + * @return Boolean True when the leading four bytes are the GLB magic. + */ +public fun isGlb(candidateBytes: ByteArray): Boolean = + candidateBytes.size >= HEADER_BYTES && ByteReader(candidateBytes, littleEndian = true).u32AsInt(0) == GLB_MAGIC + +/** + * Whether the JSON chunk's padding is what the format states it must be. + * + * The padding size cannot be recovered from the chunk length, because the length already includes it, so this + * checks the trailing bytes of a chunk whose content length is known. + * + * @param ByteArray chunk The chunk data, padding included. + * @param Int contentLength The length of the content before padding. + * @return Boolean True when every byte after the content is [JSON_PADDING_BYTE]. + */ +public fun jsonPaddingIsSpaces(chunk: ByteArray, contentLength: Int): Boolean { + if (contentLength > chunk.size || chunk.size % CHUNK_ALIGNMENT != 0) { + return false + } + for (paddingIndex in contentLength until chunk.size) { + if (chunk[paddingIndex].toInt() and 0xFF != JSON_PADDING_BYTE) { + return false + } + } + return true +} diff --git a/module/format/src/commonMain/kotlin/org/umamo/format/gltf/Gltf.kt b/module/format/src/commonMain/kotlin/org/umamo/format/gltf/Gltf.kt new file mode 100644 index 0000000..a2a6c92 --- /dev/null +++ b/module/format/src/commonMain/kotlin/org/umamo/format/gltf/Gltf.kt @@ -0,0 +1,78 @@ +package org.umamo.format.gltf + +import org.umamo.format.FileKind +import org.umamo.format.FormatVersion +import org.umamo.format.ReadOnlyCodec +import org.umamo.format.binary.ByteReader + +/** + * The glTF codec, as [FileKind.Gltf] declares it: read-only. + * + * Umamo reads a glTF as a drawing reference and never writes one, so [write] is the refusal [ReadOnlyCodec] + * provides. A reference layer is not part of the puppet, and a format that can be written would eventually be + * asked to carry the pose, which is the wrong place for it. + */ +public object Gltf : ReadOnlyCodec { + override val kind: FileKind = FileKind.Gltf + + /** + * Whether [candidateBytes] opens with the GLB magic. + * + * @param ByteArray candidateBytes The file contents to test. + * @return Boolean True when the leading four bytes are the GLB magic. + */ + override fun matches(candidateBytes: ByteArray): Boolean = isGlb(candidateBytes) + + /** + * The container version, from the header alone. + * + * Never throws: a file that is not a GLB, or is shorter than the header, reports null, which is what the + * contract states a probe must do for input it cannot read. + * + * @param ByteArray bytes The complete file contents. + * @return FormatVersion? The probed version, or null. + */ + override fun getVersion(bytes: ByteArray): FormatVersion? { + if (!isGlb(bytes)) { + return null + } + return GltfVersion(ByteReader(bytes, littleEndian = true).u32AsInt(4)) + } + + /** + * Parses a GLB into the document plus its buffer bytes, and refuses the first thing that does not match what + * glTF 2.0 states. + * + * @param ByteArray bytes The complete file contents. + * @return GltfFile The parsed document and its buffers. + * @throws IllegalArgumentException When the container, the JSON, or the structure is not what glTF 2.0 states. + */ + override fun read(bytes: ByteArray): GltfFile { + val chunks = readGlb(bytes) + val document = decodeGltfJson(chunks.jsonText()) + val file = GltfFile(document, listOf(chunks.binBytes)) + firstGltfProblem(file)?.let { problem -> throw IllegalArgumentException("glTF: $problem") } + return file + } +} + +/** + * The GLB container version as a probe result. + * + * @property Int containerVersion The version the header declares. + */ +public class GltfVersion(public val containerVersion: Int) : FormatVersion { + override val label = "glTF $containerVersion" + + /** + * A human-readable support summary. + * + * @return String The summary sentence. + */ + override fun describe(): String = + if (containerVersion == GLB_VERSION) { + "glTF 2.0, read-only. Materials, animation, and external buffers are not read." + } else { + "glTF container version $containerVersion, which this reader refuses." + } +} 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 new file mode 100644 index 0000000..1cab27e --- /dev/null +++ b/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfAccessor.kt @@ -0,0 +1,161 @@ +package org.umamo.format.gltf + +import org.umamo.format.binary.ByteReader + +/* + * Reading one accessor: the run of components a buffer view holds, read the way the accessor says. + * + * Two rules are enforced here rather than assumed, because both fail quietly somewhere else. + * + * 1. glTF 2.0 §3.2.4 states `byteOffset` must be a multiple of the component size. A reader that ignores the + * requirement reads a shifted value and returns a plausible wrong number instead of an error, which is the + * most common glTF corruption and the hardest one to notice in a mesh. + * 2. A read must stay inside the buffer view's `byteLength`. Reading past it is an error, not a zero fill: a + * zero-filled vertex collapses part of the mesh without saying anything. + * + * `normalized` is not applied. A reference layer needs raw positions and weights, and normalizing a position + * would scale it by 65535. + */ + +/** + * Reads one accessor as its components, each as a [Long]: unsigned types keep their full range, signed types + * are sign-extended, and a float is carried as its raw bits so the caller can decide what it means. + * + * This is the primitive the other reads are built on, and it is public because a normalized attribute such as + * `COLOR_0` is a run of unsigned bytes that has no float and no index meaning. + * + * @param GltfFile file The document and its buffers. + * @param Int accessorIndex The accessor to read. + * @return LongArray `count * components` values, element-major. + * @throws IllegalArgumentException When the accessor is sparse, has no buffer view, has a `byteOffset` that is + * not a multiple of the component size, or reads past the buffer view's `byteLength`. + */ +public fun readComponents(file: GltfFile, accessorIndex: Int): LongArray { + val accessor = file.document.accessors[accessorIndex] + if (accessor.sparse != null) { + throw IllegalArgumentException("accessor $accessorIndex is sparse, and a reference layer needs the concrete values") + } + if (accessor.count <= 0) { + throw IllegalArgumentException("accessor $accessorIndex declares count ${accessor.count}, glTF requires it to be greater than zero") + } + val bufferView = accessor.bufferViewIndex?.let { viewIndex -> file.document.bufferViews[viewIndex] } + ?: throw IllegalArgumentException("accessor $accessorIndex has no buffer view, so it can only be sparse") + val componentType = accessor.componentType() + val componentCount = accessor.componentCount() + if (accessor.byteOffset % componentType.byteSize != 0) { + throw IllegalArgumentException( + "accessor $accessorIndex has byteOffset ${accessor.byteOffset}, which is not a multiple of the ${componentType.byteSize}-byte component size", + ) + } + val buffer = file.bufferOf(bufferView) + if (bufferView.byteOffset + bufferView.byteLength > buffer.size) { + throw IllegalArgumentException("buffer view ${bufferView.byteOffset} + ${bufferView.byteLength} runs past the ${buffer.size}-byte buffer ${bufferView.bufferIndex}") + } + val elementSize = componentCount.components * componentType.byteSize + val stride = bufferView.byteStride ?: elementSize + if (stride < elementSize) { + throw IllegalArgumentException("accessor $accessorIndex's buffer view declares byteStride $stride, smaller than the $elementSize-byte element") + } + val lastElementEnd = bufferView.byteOffset + accessor.byteOffset + (accessor.count - 1) * stride + elementSize + if (lastElementEnd > bufferView.byteOffset + bufferView.byteLength) { + throw IllegalArgumentException( + "accessor $accessorIndex reads ${accessor.count} elements of $elementSize bytes at stride $stride, which runs past the ${bufferView.byteLength}-byte buffer view", + ) + } + + val reader = ByteReader(buffer, littleEndian = true) + val values = LongArray(accessor.count * componentCount.components) + for (elementIndex in 0 until accessor.count) { + for (componentIndex in 0 until componentCount.components) { + val at = bufferView.byteOffset + accessor.byteOffset + elementIndex * stride + componentIndex * componentType.byteSize + values[elementIndex * componentCount.components + componentIndex] = componentValue(reader, at, componentType) + } + } + return values +} + +/** + * One component at [at], as a [Long]. + * + * @param ByteReader reader The reader over the buffer. + * @param Int at Absolute offset inside the buffer. + * @param GltfComponentType componentType The component type the accessor declares. + * @return Long The unsigned value, the sign-extended value, or the raw float bits. + */ +private fun componentValue(reader: ByteReader, at: Int, componentType: GltfComponentType): Long = + when (componentType) { + GltfComponentType.Int8 -> reader.u8(at).toByte().toLong() + GltfComponentType.Uint8 -> reader.u8(at).toLong() + GltfComponentType.Int16 -> reader.u16(at).toShort().toLong() + GltfComponentType.Uint16 -> reader.u16(at).toLong() + GltfComponentType.Int32 -> reader.u32AsInt(at).toLong() + GltfComponentType.Uint32 -> reader.u32(at) + GltfComponentType.Float32 -> reader.u32AsInt(at).toLong() + } + +/** + * Reads one accessor as floats, element-major. + * + * @param GltfFile file The document and its buffers. + * @param Int accessorIndex The accessor to read. + * @return FloatArray `count * components` values. + * @throws IllegalArgumentException When the accessor is not Float32, or when [readComponents] rejects it. + */ +public fun readFloats(file: GltfFile, accessorIndex: Int): FloatArray { + val accessor = file.document.accessors[accessorIndex] + if (accessor.componentType() != GltfComponentType.Float32) { + throw IllegalArgumentException("accessor $accessorIndex holds ${accessor.componentType()}, and floats can only be read from Float32") + } + val components = readComponents(file, accessorIndex) + return FloatArray(components.size) { index -> Float.fromBits(components[index].toInt()) } +} + +/** + * Reads one accessor as indices. + * + * glTF 2.0 §3.2.4 restricts an index accessor to an unsigned component type. A signed one is refused rather + * than read: a negative index is not an index, and a reader that sign-extended it would draw a vertex outside + * the mesh. + * + * @param GltfFile file The document and its buffers. + * @param Int accessorIndex The accessor to read. + * @return IntArray `count` indices. + * @throws IllegalArgumentException When the accessor is not a scalar unsigned type, or when [readComponents] + * rejects it. + */ +public fun readIndices(file: GltfFile, accessorIndex: Int): IntArray { + val accessor = file.document.accessors[accessorIndex] + if (accessor.componentCount() != GltfComponentCount.Scalar) { + throw IllegalArgumentException("accessor $accessorIndex is ${accessor.componentCount()}, and an index accessor must be SCALAR") + } + val componentType = accessor.componentType() + if (componentType != GltfComponentType.Uint8 && componentType != GltfComponentType.Uint16 && componentType != GltfComponentType.Uint32) { + throw IllegalArgumentException("accessor $accessorIndex holds $componentType, and an index accessor must be unsigned") + } + val components = readComponents(file, accessorIndex) + return IntArray(components.size) { index -> components[index].toInt() } +} + +/** + * 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. + * + * @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. + */ +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") + } + 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 new file mode 100644 index 0000000..edfc18e --- /dev/null +++ b/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfEnums.kt @@ -0,0 +1,144 @@ +package org.umamo.format.gltf + +/* + * The format's own constants, as enums. Every one of these is a place where a reader can guess: an unknown + * component code, an unknown primitive mode, an unknown target. A guess here changes bytes into plausible + * wrong numbers rather than into an error, so each enum refuses what it does not know instead of defaulting. + */ + +/** + * glTF 2.0 §3.2.4: the component types an accessor may carry. The codes are the format's constants, not + * Umamo's, and [byteSize] is what every alignment and bounds check is computed from. + */ +public enum class GltfComponentType(val code: Int, val byteSize: Int) { + Int8(5120, 1), + Uint8(5121, 1), + Int16(5122, 2), + Uint16(5123, 2), + Int32(5124, 4), + Uint32(5125, 4), + Float32(5126, 4); + + public companion object { + /** + * The component type for [code]. + * + * @param Int code The accessor's `componentType`. + * @return GltfComponentType The type. + * @throws IllegalArgumentException When no component type carries [code]. + */ + public fun fromCode(code: Int): GltfComponentType = + entries.firstOrNull { componentType -> componentType.code == code } + ?: throw IllegalArgumentException("unknown glTF componentType $code") + + /** + * Whether [code] is one the format states. + * + * [firstGltfProblem] reports an unknown code as the document's first problem, so it needs a check that + * does not throw; [fromCode] is the lookup a caller uses after the file is validated. + * + * @param Int code The accessor's `componentType`. + * @return Boolean True when a component type carries [code]. + */ + public fun knowsCode(code: Int): Boolean = entries.any { componentType -> componentType.code == code } + } +} + +/** glTF 2.0 §3.2.4: how many components one element holds. */ +public enum class GltfComponentCount(val code: String, val components: Int) { + Scalar("SCALAR", 1), + Vec2("VEC2", 2), + Vec3("VEC3", 3), + Vec4("VEC4", 4); + + public companion object { + /** + * The component count for [code]. + * + * @param String code The accessor's `type`. + * @return GltfComponentCount The count. + * @throws IllegalArgumentException When no component count carries [code]. + */ + public fun fromCode(code: String): GltfComponentCount = + entries.firstOrNull { componentCount -> componentCount.code == code } + ?: throw IllegalArgumentException("unknown glTF accessor type $code") + + /** + * Whether [code] is one the format states. + * + * [firstGltfProblem] reports an unknown code as the document's first problem, so it needs a check that + * does not throw; [fromCode] is the lookup a caller uses after the file is validated. + * + * @param String code The accessor's `type`. + * @return Boolean True when a component count carries [code]. + */ + public fun knowsCode(code: String): Boolean = entries.any { componentCount -> componentCount.code == code } + } +} + +/** glTF 2.0 §3.2: the topology a primitive declares. */ +public enum class GltfPrimitiveMode(val code: Int) { + Points(1), + Lines(2), + LineStrip(3), + LineLoop(4), + Triangles(5), + TriangleStrip(6), + TriangleFan(7); + + public companion object { + /** + * The mode for [code]. + * + * @param Int code The primitive's `mode`. + * @return GltfPrimitiveMode The mode. + * @throws IllegalArgumentException When no mode carries [code]. + */ + public fun fromCode(code: Int): GltfPrimitiveMode = + entries.firstOrNull { mode -> mode.code == code } + ?: throw IllegalArgumentException("unknown glTF primitive mode $code") + + /** + * Whether [code] is one the format states. + * + * [firstGltfProblem] reports an unknown code as the document's first problem, so it needs a check that + * does not throw; [fromCode] is the lookup a caller uses after the file is validated. + * + * @param Int code The primitive's `mode`. + * @return Boolean True when a mode carries [code]. + */ + public fun knowsCode(code: Int): Boolean = entries.any { mode -> mode.code == code } + } +} + +/** glTF 2.0 §3.2: what a buffer view is bound to, when the file says so. */ +public enum class GltfBufferViewTarget(val code: Int) { + ArrayBuffer(34962), + ElementArrayBuffer(34963); + + public companion object { + /** + * The target for [code]. + * + * @param Int code The buffer view's `target`. + * @return GltfBufferViewTarget? The target, or null when the file names none. + * @throws IllegalArgumentException When [code] is not null and no target carries it. + */ + public fun fromCodeOrNull(code: Int?): GltfBufferViewTarget? = + code?.let { targetCode -> + entries.firstOrNull { target -> target.code == targetCode } + ?: throw IllegalArgumentException("unknown glTF bufferView target $targetCode") + } + + /** + * Whether [code] is one the format states. + * + * [firstGltfProblem] reports an unknown code as the document's first problem, so it needs a check that + * does not throw; [fromCodeOrNull] is the lookup a caller uses after the file is validated. + * + * @param Int code The buffer view's `target`. + * @return Boolean True when a target carries [code]. + */ + public fun knowsCode(code: Int): Boolean = entries.any { target -> target.code == code } + } +} diff --git a/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfFile.kt b/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfFile.kt new file mode 100644 index 0000000..cc6180f --- /dev/null +++ b/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfFile.kt @@ -0,0 +1,27 @@ +package org.umamo.format.gltf + +/** + * A parsed glTF document plus the bytes its accessors read from: one entry per buffer, in document order. + * + * The document is the JSON half on its own, and it is not enough to read a value: an accessor names a buffer + * view, a buffer view names a buffer, and the buffer is the only thing that holds bytes. Keeping the bytes + * beside the document is what makes an accessor read possible without a second pass over the file. + * + * @property GltfDocument document The JSON half. + * @property List buffers One entry per buffer, in document order. + */ +public class GltfFile( + public val document: GltfDocument, + public val buffers: List, +) { + /** + * The bytes a buffer view reads from. + * + * @param GltfBufferView bufferView The view. + * @return ByteArray The buffer it names. + * @throws IllegalArgumentException When the view names a buffer the document does not have. + */ + public fun bufferOf(bufferView: GltfBufferView): ByteArray = + buffers.getOrNull(bufferView.bufferIndex) + ?: throw IllegalArgumentException("the buffer view names buffer ${bufferView.bufferIndex}, the document has ${buffers.size} buffers") +} 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 new file mode 100644 index 0000000..1252f67 --- /dev/null +++ b/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfJson.kt @@ -0,0 +1,178 @@ +package org.umamo.format.gltf + +import kotlinx.serialization.SerialName +import kotlinx.serialization.Serializable +import kotlinx.serialization.json.Json +import org.umamo.format.uma.UMA_MAXIMUM_JSON_DEPTH +import org.umamo.format.uma.jsonTextNestsTooDeep + +/* + * The glTF JSON half, modelled only as far as a poseable reference layer needs it: buffers, buffer views, + * accessors, meshes, nodes, skins, and the default scene. Materials, images, textures, samplers, and + * animation are deliberately absent - the reference layer draws flat shapes and has no material to read. + * + * Component codes stay the format's own numbers and strings and are resolved to enums on read, because a + * wrong component size shifts every value after it rather than failing. + */ + +/** + * The JSON a glTF document decodes from. + * + * Unknown keys are ignored because glTF carries `extensions` and `extras` on every object, so a reader that + * refused them could not open a file written by another tool. + */ +private val GltfJson: Json = Json { ignoreUnknownKeys = true } + +/** + * The JSON chunk as a document, checked against the nesting limit the UMA reader already uses. + * + * The limit is applied to the text before parsing: the parser recurses once per nested object, so a document + * too deep to walk is too deep to parse. + * + * @param String text The JSON chunk, with its padding trimmed. + * @return GltfDocument The document. + * @throws IllegalArgumentException When the text nests deeper than [UMA_MAXIMUM_JSON_DEPTH] levels. + */ +public fun decodeGltfJson(text: String): GltfDocument { + if (jsonTextNestsTooDeep(text)) { + throw IllegalArgumentException("the glTF JSON nests deeper than $UMA_MAXIMUM_JSON_DEPTH levels") + } + return GltfJson.decodeFromString(text) +} + +/** glTF 2.0 §3.2: the `asset` block. Its presence is what makes a JSON document a glTF document. */ +@Serializable +public data class GltfAsset( + val version: String, + val minVersion: String? = null, +) + +/** glTF 2.0 §3.2: the document root, restricted to the parts a reference layer reads. */ +@Serializable +public data class GltfDocument( + val asset: GltfAsset, + val buffers: List = emptyList(), + val bufferViews: List = emptyList(), + val accessors: List = emptyList(), + val meshes: List = emptyList(), + val nodes: List = emptyList(), + val skins: List = emptyList(), + val scenes: List = emptyList(), + /** glTF 2.0 §3.2: the key is `scene`, not `defaultScene`, and it names an index into `scenes`. */ + @SerialName("scene") val defaultSceneIndex: Int? = null, +) { + /** + * The scene to draw: the one the document names, or the only one when it names none. + * + * @return GltfScene? The scene, or null when the document carries none. + */ + public fun scene(): GltfScene? = + defaultSceneIndex?.let { sceneIndex -> scenes[sceneIndex] } ?: scenes.firstOrNull() +} + +/** glTF 2.0 §3.2: one buffer. In a GLB the first buffer is the BIN chunk and has no `uri`. */ +@Serializable +public data class GltfBuffer( + val name: String? = null, + val byteLength: Int, + val uri: String? = null, +) + +/** glTF 2.0 §3.2: one window into a buffer. */ +@Serializable +public data class GltfBufferView( + @SerialName("buffer") val bufferIndex: Int, + val byteOffset: Int = 0, + val byteLength: Int, + val byteStride: Int? = null, + val target: Int? = null, +) + +/** glTF 2.0 §3.2.4: one accessor - how to read a run of components out of a buffer view. */ +@Serializable +public data class GltfAccessor( + @SerialName("bufferView") val bufferViewIndex: Int? = null, + val byteOffset: Int = 0, + @SerialName("componentType") val componentTypeCode: Int, + @SerialName("type") val componentCountCode: String, + val count: Int, + val normalized: Boolean = false, + /** glTF 2.0 §3.2.4: a sparse accessor. Refused by [firstGltfProblem], so it is never read as a zero fill. */ + val sparse: GltfSparse? = null, +) { + /** + * The component type as an enum. + * + * @return GltfComponentType The type. + * @throws IllegalArgumentException When no component type carries that code. + */ + public fun componentType(): GltfComponentType = GltfComponentType.fromCode(componentTypeCode) + + /** + * The number of components per element, as an enum. + * + * @return GltfComponentCount The count. + * @throws IllegalArgumentException When no component count carries that code. + */ + public fun componentCount(): GltfComponentCount = GltfComponentCount.fromCode(componentCountCode) +} + +/** glTF 2.0 §3.2.4: a sparse accessor's two halves, each an accessor of its own. */ +@Serializable +public data class GltfSparse( + val count: Int, + val indices: GltfAccessor, + val values: GltfAccessor, +) + +/** glTF 2.0 §3.2: one mesh, as the reference layer sees it: primitives, no material. */ +@Serializable +public data class GltfMesh( + val name: String? = null, + val primitives: List = emptyList(), +) + +/** glTF 2.0 §3.2: one primitive - an index accessor plus named attribute accessors. */ +@Serializable +public data class GltfPrimitive( + @SerialName("mode") val modeCode: Int = 5, + @SerialName("indices") val indicesAccessorIndex: Int? = null, + val attributes: Map = emptyMap(), +) { + /** + * The topology as an enum. + * + * @return GltfPrimitiveMode The mode. + * @throws IllegalArgumentException When no mode carries that code. + */ + public fun mode(): GltfPrimitiveMode = GltfPrimitiveMode.fromCode(modeCode) +} + +/** glTF 2.0 §3.2: one node of the scene graph. */ +@Serializable +public data class GltfNode( + val name: String? = null, + val children: List = emptyList(), + @SerialName("mesh") val meshIndex: Int? = null, + @SerialName("skin") val skinIndex: Int? = null, + val translation: List = emptyList(), + val rotation: List = emptyList(), + val scale: List = emptyList(), + val matrix: List = emptyList(), +) + +/** glTF 2.0 §3.2: one skin - the joints it binds and the inverse bind matrices it reads. */ +@Serializable +public data class GltfSkin( + val name: String? = null, + val joints: List = emptyList(), + @SerialName("skeleton") val skeletonNodeIndex: Int? = null, + @SerialName("inverseBindMatrices") val inverseBindMatricesAccessorIndex: Int? = null, +) + +/** glTF 2.0 §3.2: one scene - the roots it holds. */ +@Serializable +public data class GltfScene( + val name: String? = null, + val nodes: List = emptyList(), +) 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 new file mode 100644 index 0000000..5b7b331 --- /dev/null +++ b/module/format/src/commonMain/kotlin/org/umamo/format/gltf/GltfValidation.kt @@ -0,0 +1,268 @@ +package org.umamo.format.gltf + +/* + * Structural checks over a parsed glTF document, run once at read time. + * + * These are the rules that cannot be enforced at the point a value is read, because they are about references: + * an accessor index that names nothing, a skin joint that names a node the document does not have, a buffer view + * that runs past its buffer. Reporting the first problem as a path, rather than throwing at the first bad index, + * is what the UMA reader already does, and it is what lets a caller show one message instead of the first thing + * that happened to be touched. + */ + +/** + * The first thing about [file] that does not match what glTF 2.0 states, as a path, or null when the document is + * sound. + * + * @param GltfFile file The parsed document and its buffers. + * @return String? The problem, or null. + */ +public fun firstGltfProblem(file: GltfFile): String? { + firstDocumentProblem(file)?.let { problem -> return problem } + firstBufferProblem(file)?.let { problem -> return problem } + for (accessorIndex in file.document.accessors.indices) { + firstAccessorProblem(file, accessorIndex)?.let { problem -> return problem } + } + for (meshIndex in file.document.meshes.indices) { + for (primitiveIndex in file.document.meshes[meshIndex].primitives.indices) { + firstPrimitiveProblem(file, meshIndex, primitiveIndex)?.let { problem -> return problem } + } + } + for (nodeIndex in file.document.nodes.indices) { + firstNodeProblem(file, nodeIndex)?.let { problem -> return problem } + } + for (skinIndex in file.document.skins.indices) { + firstSkinProblem(file, skinIndex)?.let { problem -> return problem } + } + return firstSceneProblem(file) +} + +/** + * The document-level rules: a GLB carries exactly one buffer, and that buffer is the BIN chunk. + * + * A buffer with a `uri` is refused because this reader has no file system: it is given the bytes of one file, and + * a glTF that names another file cannot be read from them. + * + * @param GltfFile file The parsed document and its buffers. + * @return String? The problem, or null. + */ +private fun firstDocumentProblem(file: GltfFile): String? { + if (file.document.buffers.size != 1) { + return "the document declares ${file.document.buffers.size} buffers; a GLB carries exactly one, the BIN chunk" + } + if (file.document.buffers[0].uri != null) { + return "buffer 0 names a uri, so its bytes are not in this file" + } + if (file.buffers[0].size != file.document.buffers[0].byteLength) { + return "buffer 0 declares ${file.document.buffers[0].byteLength} bytes, the BIN chunk holds ${file.buffers[0].size}" + } + return null +} + +/** + * The buffer view rules: every view lies inside its buffer, and a declared `byteStride` is one the format allows. + * + * glTF 2.0 §3.2.4 states `byteStride` must be a multiple of four and at least as large as the element it strides + * over. A stride smaller than the element overlaps two elements onto the same bytes, which reads as a mesh with + * duplicated vertices rather than as an error. + * + * @param GltfFile file The parsed document and its buffers. + * @return String? The problem, or null. + */ +private fun firstBufferProblem(file: GltfFile): String? { + for (viewIndex in file.document.bufferViews.indices) { + val view = file.document.bufferViews[viewIndex] + if (view.bufferIndex !in file.buffers.indices) { + return "buffer view $viewIndex names buffer ${view.bufferIndex}, the document has ${file.buffers.size}" + } + if (view.byteLength <= 0) { + return "buffer view $viewIndex declares byteLength ${view.byteLength}, glTF requires it to be greater than zero" + } + if (view.byteOffset + view.byteLength > file.buffers[view.bufferIndex].size) { + return "buffer view $viewIndex runs from ${view.byteOffset} to ${view.byteOffset + view.byteLength}, past the ${file.buffers[view.bufferIndex].size}-byte buffer ${view.bufferIndex}" + } + val byteStride = view.byteStride + if (byteStride != null && byteStride % 4 != 0) { + return "buffer view $viewIndex declares byteStride $byteStride, which is not a multiple of four" + } + val target = view.target + if (target != null && !GltfBufferViewTarget.knowsCode(target)) { + return "buffer view $viewIndex declares target $target, which is not one glTF states" + } + } + return null +} + +/** + * The accessor rules for [accessorIndex]: alignment, range, and the shape the format requires. + * + * @param GltfFile file The parsed document and its buffers. + * @param Int accessorIndex The accessor to check. + * @return String? The problem, or null. + */ +private fun firstAccessorProblem(file: GltfFile, accessorIndex: Int): String? { + val accessor = file.document.accessors[accessorIndex] + if (!GltfComponentType.knowsCode(accessor.componentTypeCode)) { + return "accessor $accessorIndex declares componentType ${accessor.componentTypeCode}, which is not one glTF states" + } + if (!GltfComponentCount.knowsCode(accessor.componentCountCode)) { + return "accessor $accessorIndex declares type '${accessor.componentCountCode}', which is not one glTF states" + } + if (accessor.count <= 0) { + return "accessor $accessorIndex declares count ${accessor.count}, glTF requires it to be greater than zero" + } + if (accessor.sparse != null) { + return "accessor $accessorIndex is sparse, and a reference layer needs the concrete values" + } + val viewIndex = accessor.bufferViewIndex ?: return "accessor $accessorIndex has no buffer view, so it can only be sparse" + if (viewIndex !in file.document.bufferViews.indices) { + return "accessor $accessorIndex names buffer view $viewIndex, the document has ${file.document.bufferViews.size}" + } + val view = file.document.bufferViews[viewIndex] + val componentType = accessor.componentType() + if (accessor.byteOffset % componentType.byteSize != 0) { + return "accessor $accessorIndex has byteOffset ${accessor.byteOffset}, which is not a multiple of the ${componentType.byteSize}-byte component size" + } + val elementSize = accessor.componentCount().components * componentType.byteSize + val stride = view.byteStride ?: elementSize + if (stride < elementSize) { + return "accessor $accessorIndex's buffer view declares byteStride $stride, smaller than the ${elementSize}-byte element" + } + if (accessor.byteOffset + accessor.count * stride > view.byteLength) { + return "accessor $accessorIndex reads ${accessor.count} elements at stride $stride, past the ${view.byteLength}-byte buffer view $viewIndex" + } + return null +} + +/** + * The primitive rules for one primitive: it must have attributes, and every accessor it names must exist and be + * of the kind the attribute is. + * + * @param GltfFile file The parsed document and its buffers. + * @param Int meshIndex The mesh the primitive belongs to. + * @param Int primitiveIndex The primitive inside that mesh. + * @return String? The problem, or null. + */ +private fun firstPrimitiveProblem(file: GltfFile, meshIndex: Int, primitiveIndex: Int): String? { + val primitive = file.document.meshes[meshIndex].primitives[primitiveIndex] + val path = "mesh $meshIndex primitive $primitiveIndex" + if (!GltfPrimitiveMode.knowsCode(primitive.modeCode)) { + return "$path declares mode ${primitive.modeCode}, which is not one glTF states" + } + if (primitive.attributes.isEmpty()) { + return "$path has no attributes" + } + val indicesAccessorIndex = primitive.indicesAccessorIndex + if (indicesAccessorIndex != null) { + if (indicesAccessorIndex !in file.document.accessors.indices) { + return "$path names accessor $indicesAccessorIndex, the document has ${file.document.accessors.size}" + } + val indices = file.document.accessors[indicesAccessorIndex] + if (GltfComponentCount.fromCode(indices.componentCountCode) != GltfComponentCount.Scalar) { + return "$path reads its indices from a ${indices.componentCountCode} accessor, and glTF requires an index accessor to be SCALAR" + } + val componentType = GltfComponentType.fromCode(indices.componentTypeCode) + if (componentType != GltfComponentType.Uint8 && componentType != GltfComponentType.Uint16 && componentType != GltfComponentType.Uint32) { + return "$path reads its indices from a $componentType accessor, and glTF requires an index accessor to be unsigned" + } + } + for (attributeName in primitive.attributes.keys) { + val accessorIndex = primitive.attributes[attributeName]!! + if (accessorIndex !in file.document.accessors.indices) { + return "$path attribute '$attributeName' names accessor $accessorIndex, the document has ${file.document.accessors.size}" + } + } + return null +} + +/** + * The node rules for [nodeIndex]: the children, mesh, and skin it names must exist, and its transform must be one + * of the two shapes glTF allows. + * + * @param GltfFile file The parsed document and its buffers. + * @param Int nodeIndex The node to check. + * @return String? The problem, or null. + */ +private fun firstNodeProblem(file: GltfFile, nodeIndex: Int): String? { + val node = file.document.nodes[nodeIndex] + for (childIndex in node.children) { + if (childIndex !in file.document.nodes.indices) { + return "node $nodeIndex names child $childIndex, the document has ${file.document.nodes.size}" + } + } + if (node.meshIndex != null && node.meshIndex !in file.document.meshes.indices) { + return "node $nodeIndex names mesh ${node.meshIndex}, the document has ${file.document.meshes.size}" + } + if (node.skinIndex != null && node.skinIndex !in file.document.skins.indices) { + return "node $nodeIndex names skin ${node.skinIndex}, the document has ${file.document.skins.size}" + } + if (node.matrix.isNotEmpty()) { + if (node.matrix.size != 16) { + return "node $nodeIndex declares a ${node.matrix.size}-element matrix, glTF requires sixteen" + } + if (node.translation.isNotEmpty() || node.rotation.isNotEmpty() || node.scale.isNotEmpty()) { + return "node $nodeIndex declares both a matrix and a TRS transform" + } + return null + } + if (node.translation.size > 3 || node.rotation.size > 4 || node.scale.size > 3) { + return "node $nodeIndex declares a TRS transform with the wrong number of components" + } + return null +} + +/** + * 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. + * + * @param GltfFile file The parsed document and its buffers. + * @param Int skinIndex The skin to check. + * @return String? The problem, or null. + */ +private fun firstSkinProblem(file: GltfFile, skinIndex: Int): String? { + val skin = file.document.skins[skinIndex] + if (skin.joints.isEmpty()) { + return "skin $skinIndex binds no joints" + } + for (jointNodeIndex in skin.joints) { + if (jointNodeIndex !in file.document.nodes.indices) { + return "skin $skinIndex names joint node $jointNodeIndex, the document has ${file.document.nodes.size}" + } + } + if (skin.skeletonNodeIndex != null && skin.skeletonNodeIndex !in file.document.nodes.indices) { + return "skin $skinIndex names skeleton node ${skin.skeletonNodeIndex}, the document has ${file.document.nodes.size}" + } + val accessorIndex = skin.inverseBindMatricesAccessorIndex ?: return null + if (accessorIndex !in file.document.accessors.indices) { + 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 (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}" + } + return null +} + +/** + * The scene rules: the scene the document names must exist, and every root it holds must be a node. + * + * @param GltfFile file The parsed document and its buffers. + * @return String? The problem, or null. + */ +private fun firstSceneProblem(file: GltfFile): String? { + val document = file.document + if (document.defaultSceneIndex != null && document.defaultSceneIndex !in document.scenes.indices) { + return "the document names scene ${document.defaultSceneIndex}, it has ${document.scenes.size}" + } + for (sceneIndex in document.scenes.indices) { + for (nodeIndex in document.scenes[sceneIndex].nodes) { + if (nodeIndex !in document.nodes.indices) { + return "scene $sceneIndex names node $nodeIndex, the document has ${document.nodes.size}" + } + } + } + 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 new file mode 100644 index 0000000..7b7db1b --- /dev/null +++ b/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GlbContainerTest.kt @@ -0,0 +1,147 @@ +package org.umamo.format.gltf + +import kotlin.test.Test +import kotlin.test.assertEquals +import kotlin.test.assertFailsWith +import kotlin.test.assertFalse +import kotlin.test.assertTrue + +/** + * The GLB container rules (glTF 2.0 §3.2), tested without an asset: every rule here is a length, an alignment, + * or an order, so a file can be built inside the test and the failure asserted directly. + */ +class GlbContainerTest { + @Test + fun readsAWellFormedGlb() { + val bin = byteArrayOf(1, 2, 3, 4, 5, 6, 7, 8) + val json = """{"asset":{"version":"2.0"}}""" + val chunks = readGlb(buildGlb(json, bin)) + assertTrue(bin.contentEquals(chunks.binBytes)) + assertEquals(json, chunks.jsonText()) + } + + @Test + fun rejectsAFileShorterThanTheHeader() { + assertFailsWith { + readGlb(ByteArray(11)) + } + } + + @Test + fun rejectsAWrongMagic() { + val file = buildGlb("""{"asset":{"version":"2.0"}}""", ByteArray(0)).copyOf() + file[0] = 'g'.code.toByte() + file[1] = 'l'.code.toByte() + file[2] = 'x'.code.toByte() + file[3] = 'F'.code.toByte() + assertFailsWith { + readGlb(file) + } + } + + @Test + fun rejectsAContainerVersionOtherThanTwo() { + val file = buildGlb("""{"asset":{"version":"2.0"}}""", ByteArray(0)).copyOf() + file[4] = 1 + assertFailsWith { + readGlb(file) + } + } + + @Test + fun rejectsADeclaredLengthThatIsNotTheActualLength() { + // The header states a length the file does not have: a truncated file reads as an error, not as a + // short read. + val json = padToAlignment("""{"asset":{"version":"2.0"}}""".encodeToByteArray(), ' '.code.toByte()) + assertFailsWith { + readGlb(buildGlbFromChunks(listOf(GlbChunkTest(CHUNK_JSON_TEST, json)), declaredTotalLength = 40)) + } + } + + @Test + fun rejectsAChunkThatRunsPastTheEndOfTheFile() { + assertFailsWith { + readGlb(buildGlbWithOverstatedLastChunk("""{"asset":{"version":"2.0"}}""", CHUNK_BIN_TEST, 12, ByteArray(8))) + } + } + + @Test + fun rejectsAChunkLengthThatIsNotAMultipleOfFour() { + // A JSON chunk of 22 bytes: not padded, so the format does not allow it. + assertFailsWith { + readGlb(buildGlbFromChunks(listOf(GlbChunkTest(CHUNK_JSON_TEST, """{"asset":{"version":"2.0"}}""".encodeToByteArray() + ByteArray(2))))) + } + } + + @Test + fun skipsAnUnknownChunkType() { + val json = """{"asset":{"version":"2.0"}}""".encodeToByteArray() + val chunks = readGlb( + buildGlbFromChunks( + listOf( + GlbChunkTest(CHUNK_JSON_TEST, padToAlignment(json, ' '.code.toByte())), + GlbChunkTest(CHUNK_UNKNOWN_TEST, ByteArray(8)), + ), + ), + ) + // The chunk is skipped, so its bytes are not in the result; the JSON chunk is returned as the file + // holds it, padding included. + assertEquals(json.size + 1, chunks.jsonBytes.size) + assertTrue(chunks.binBytes.isEmpty()) + } + + @Test + fun rejectsMoreThanOneChunkOfAKnownType() { + val json = padToAlignment("""{"asset":{"version":"2.0"}}""".encodeToByteArray(), ' '.code.toByte()) + assertFailsWith { + readGlb(buildGlbFromChunks(listOf(GlbChunkTest(CHUNK_JSON_TEST, json), GlbChunkTest(CHUNK_JSON_TEST, json)))) + } + assertFailsWith { + readGlb(buildGlbFromChunks(listOf(GlbChunkTest(CHUNK_JSON_TEST, json), GlbChunkTest(CHUNK_BIN_TEST, ByteArray(4)), GlbChunkTest(CHUNK_BIN_TEST, ByteArray(4))))) + } + } + + @Test + fun rejectsAJsonChunkThatIsNotTheFirstChunk() { + val json = padToAlignment("""{"asset":{"version":"2.0"}}""".encodeToByteArray(), ' '.code.toByte()) + assertFailsWith { + readGlb(buildGlbFromChunks(listOf(GlbChunkTest(CHUNK_UNKNOWN_TEST, ByteArray(4)), GlbChunkTest(CHUNK_JSON_TEST, json)))) + } + } + + @Test + fun rejectsABinChunkBeforeTheJsonChunk() { + val json = padToAlignment("""{"asset":{"version":"2.0"}}""".encodeToByteArray(), ' '.code.toByte()) + assertFailsWith { + readGlb(buildGlbFromChunks(listOf(GlbChunkTest(CHUNK_BIN_TEST, ByteArray(4)), GlbChunkTest(CHUNK_JSON_TEST, json)))) + } + } + + @Test + fun rejectsAFileWithNoJsonChunk() { + assertFailsWith { + readGlb(buildGlbFromChunks(listOf(GlbChunkTest(CHUNK_BIN_TEST, ByteArray(4))))) + } + } + + @Test + fun jsonPaddingIsPartOfTheChunkLengthSoTheTextHasToBeTrimmed() { + // 24 bytes of content plus 4 bytes of space padding: the chunk length is 28, the content is 24. + val content = """{"asset":{"version":"2.0"}}""".encodeToByteArray() + val chunk = padToAlignment(content, ' '.code.toByte()) + assertEquals(28, chunk.size) + assertTrue(jsonPaddingIsSpaces(chunk, content.size)) + val wrongPadding = chunk.copyOf() + wrongPadding[content.size] = 'x'.code.toByte() + assertFalse(jsonPaddingIsSpaces(wrongPadding, content.size)) + } + + @Test + fun jsonTextTrimsThePaddingAndJsonBytesKeepsIt() { + val content = """{"asset":{"version":"2.0"}}""".encodeToByteArray() + val chunks = readGlb(buildGlb(content.decodeToString(), ByteArray(0))) + // jsonBytes is the chunk as the file holds it: 27 bytes of content plus its padding. + assertEquals(28, chunks.jsonBytes.size) + assertEquals(content.decodeToString(), chunks.jsonText()) + } +} 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 new file mode 100644 index 0000000..95ba577 --- /dev/null +++ b/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GlbFixtures.kt @@ -0,0 +1,156 @@ +package org.umamo.format.gltf + +/** + * One chunk as a test builds it: a type and data, with the data already padded to the alignment the format + * states. + * + * @property Int type The four-character type as a little-endian uint32. + * @property ByteArray data The chunk data, padding included. + */ +internal class GlbChunkTest( + internal val type: Int, + internal val data: ByteArray, +) + +/** The JSON chunk type, as a test constant: [CHUNK_JSON] is private to the reader. */ +internal const val CHUNK_JSON_TEST = 0x4E4F4A42 + +/** The BIN chunk type, as a test constant: [CHUNK_BIN] is private to the reader. */ +internal const val CHUNK_BIN_TEST = 0x004E4942 + +/** An unknown chunk type a reader is required to skip. */ +internal const val CHUNK_UNKNOWN_TEST = 0x01000000 + +/** + * Builds a GLB from [chunks], in the order given. + * + * The header's declared total length is the real length unless [declaredTotalLength] says otherwise, which is + * how a truncated or overstated file is tested. + * + * @param List chunks The chunks, in file order. + * @param Int? declaredTotalLength The length the header declares, or null to use the actual length. + * @return ByteArray The complete file. + */ +internal fun buildGlbFromChunks( + chunks: List, + declaredTotalLength: Int? = null, +): ByteArray { + val actual = 12 + chunks.sumOf { chunk -> 8 + chunk.data.size } + val out = ByteArray(actual) + var at = 0 + at = writeU32(out, at, GLB_MAGIC) + at = writeU32(out, at, GLB_VERSION) + at = writeU32(out, at, declaredTotalLength ?: actual) + for (chunk in chunks) { + at = writeU32(out, at, chunk.data.size) + at = writeU32(out, at, chunk.type) + chunk.data.copyInto(out, at) + at += chunk.data.size + } + return out +} + +/** + * Builds a GLB whose last chunk declares [declaredLength] bytes while only [actualData] bytes follow it: the + * shape a truncated file has, where the header and the chunk both state more than the file holds. + * + * @param String jsonText The JSON chunk content, unpadded. + * @param Int lastChunkType The type of the overstated chunk. + * @param Int declaredLength The length that chunk declares. + * @param ByteArray actualData The bytes that are actually there. + * @return ByteArray The complete file. + */ +internal fun buildGlbWithOverstatedLastChunk( + jsonText: String, + lastChunkType: Int, + declaredLength: Int, + actualData: ByteArray, +): ByteArray { + val json = padToAlignment(jsonText.encodeToByteArray(), ' '.code.toByte()) + val out = ByteArray(12 + 8 + json.size + 8 + actualData.size) + var at = 0 + at = writeU32(out, at, GLB_MAGIC) + at = writeU32(out, at, GLB_VERSION) + at = writeU32(out, at, out.size) + at = writeU32(out, at, json.size) + at = writeU32(out, at, CHUNK_JSON_TEST) + json.copyInto(out, at) + at += json.size + at = writeU32(out, at, declaredLength) + at = writeU32(out, at, lastChunkType) + actualData.copyInto(out, at) + return out +} + +/** + * Builds a well-formed GLB, padding both chunks the way the format states: JSON with spaces, BIN with zeros. + * + * @param String jsonText The JSON chunk content, unpadded. + * @param ByteArray binBytes The BIN chunk content, unpadded. + * @return ByteArray The complete file. + */ +internal fun buildGlb( + jsonText: String, + binBytes: ByteArray, +): ByteArray { + val chunks = mutableListOf(GlbChunkTest(CHUNK_JSON_TEST, padToAlignment(jsonText.encodeToByteArray(), ' '.code.toByte()))) + if (binBytes.isNotEmpty()) { + chunks += GlbChunkTest(CHUNK_BIN_TEST, padToAlignment(binBytes, 0)) + } + return buildGlbFromChunks(chunks) +} + +/** + * Writes one little-endian uint32. + * + * @param ByteArray out The file being built. + * @param Int at Where the value goes. + * @param Int value The value. + * @return Int The offset after the value. + */ +private fun writeU32( + out: ByteArray, + at: Int, + value: Int, +): Int { + out[at] = (value and 0xFF).toByte() + out[at + 1] = ((value shr 8) and 0xFF).toByte() + out[at + 2] = ((value shr 16) and 0xFF).toByte() + out[at + 3] = ((value shr 24) and 0xFF).toByte() + return at + 4 +} + +/** + * Pads [data] to a 4-byte boundary with [paddingByte]. + * + * @param ByteArray data The content. + * @param Byte paddingByte The byte the format pads with. + * @return ByteArray The content plus its padding. + */ +internal fun padToAlignment( + data: ByteArray, + paddingByte: Byte, +): ByteArray = + if (data.size % 4 == 0) { + data + } else { + data + ByteArray(4 - data.size % 4) { paddingByte } + } + +/** + * Encodes [values] as little-endian float32. + * + * @param FloatArray values The values. + * @return ByteArray The bytes. + */ +internal fun floatBytes(vararg values: Float): ByteArray = + ByteArray(values.size * 4) { index -> ((values[index / 4].toRawBits() shr ((index % 4) * 8)) and 0xFF).toByte() } + +/** + * A JSON document with one buffer, one buffer view, and one accessor over [byteLength] bytes. + * + * @param Int byteLength The buffer length the document declares. + * @return String The JSON text. + */ +internal fun glbJson(byteLength: Int): String = + """{"asset":{"version":"2.0"},"buffers":[{"byteLength":$byteLength}],"bufferViews":[{"buffer":0,"byteOffset":0,"byteLength":$byteLength}],"accessors":[{"bufferView":0,"byteOffset":0,"componentType":5126,"type":"VEC3","count":${byteLength / 12}}]}""" 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 new file mode 100644 index 0000000..0f74e17 --- /dev/null +++ b/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfAccessorTest.kt @@ -0,0 +1,174 @@ +package org.umamo.format.gltf + +import kotlin.test.Test +import kotlin.test.assertEquals +import kotlin.test.assertFailsWith + +/* + * The accessor rules, tested on a document built in the test rather than through the codec, so a failure names + * the accessor rule and not the whole-file validator. The codec path is covered by [GltfValidationTest]. + */ +class GltfAccessorTest { + /** + * A file from a JSON document and the bytes its buffer holds. + * + * @param String json The JSON half. + * @param ByteArray bin The buffer bytes. + * @return GltfFile The file, unvalidated. + */ + private fun file( + json: String, + bin: ByteArray, + ): GltfFile = GltfFile(decodeGltfJson(json), listOf(bin)) + + @Test + fun readsFloatsFromAFloat32Accessor() { + val bin = floatBytes(1f, 2f, 3f, 4f, 5f, 6f, 7f, 8f, 9f) + 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":"VEC3","count":3}]}""" + assertEquals(floatArrayOf(1f, 2f, 3f, 4f, 5f, 6f, 7f, 8f, 9f).toList(), readFloats(file(json, bin), 0).toList()) + } + + @Test + fun rejectsAnAccessorByteOffsetThatIsNotAMultipleOfTheComponentSize() { + val bin = floatBytes(1f, 2f, 3f) + val json = jsonWith(bin.size, byteOffset = 2, componentTypeCode = 5126, componentCountCode = "VEC3", count = 1) + val problem = assertFailsWith { + readComponents(file(json, bin), 0) + } + // The message states the constraint, not just the fact that it failed. + assertEquals("accessor 0 has byteOffset 2, which is not a multiple of the 4-byte component size", problem.message) + } + + @Test + fun rejectsAnAccessorThatReadsPastItsBufferView() { + // The buffer holds one VEC3, the accessor asks for two. + val bin = floatBytes(1f, 2f, 3f) + val json = jsonWith(bin.size, byteOffset = 0, componentTypeCode = 5126, componentCountCode = "VEC3", count = 2) + assertFailsWith { + readComponents(file(json, bin), 0) + } + } + + @Test + fun readsElementsThroughAStridedBufferView() { + // Two VEC3 floats at a stride of 16: element 0 at 0, element 1 at 16. + val bin = floatBytes(1f, 2f, 3f) + ByteArray(4) + floatBytes(4f, 5f, 6f) + ByteArray(4) + val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":${bin.size}}],"bufferViews":[{"buffer":0,"byteOffset":0,"byteLength":${bin.size},"byteStride":16}],"accessors":[{"bufferView":0,"byteOffset":0,"componentType":5126,"type":"VEC3","count":2}]}""" + assertEquals(floatArrayOf(1f, 2f, 3f, 4f, 5f, 6f).toList(), readFloats(file(json, bin), 0).toList()) + } + + @Test + fun readsEveryComponentTypeTheFormatDefines() { + // One component of each type, each at an offset its own size allows: 0, 1, 2, 4, 8, 12, 16. + val bin = ByteArray(20) + bin[0] = -1 + bin[1] = -1 + bin[2] = -1; bin[3] = -1 + bin[4] = -1; bin[5] = -1 + bin[8] = -1; bin[9] = -1; bin[10] = -1; bin[11] = -1 + bin[12] = -1; bin[13] = -1; bin[14] = -1; bin[15] = -1 + floatBytes(1f).copyInto(bin, 16) + val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":20}],"bufferViews":[{"buffer":0,"byteOffset":0,"byteLength":20}],""" + + """"accessors":[""" + + """{"bufferView":0,"byteOffset":0,"componentType":5120,"type":"SCALAR","count":1},""" + + """{"bufferView":0,"byteOffset":1,"componentType":5121,"type":"SCALAR","count":1},""" + + """{"bufferView":0,"byteOffset":2,"componentType":5122,"type":"SCALAR","count":1},""" + + """{"bufferView":0,"byteOffset":4,"componentType":5123,"type":"SCALAR","count":1},""" + + """{"bufferView":0,"byteOffset":8,"componentType":5124,"type":"SCALAR","count":1},""" + + """{"bufferView":0,"byteOffset":12,"componentType":5125,"type":"SCALAR","count":1},""" + + """{"bufferView":0,"byteOffset":16,"componentType":5126,"type":"SCALAR","count":1}]}""" + val file = file(json, bin) + val expected = listOf(-1L, 255L, -1L, 65535L, -1L, 4294967295L, 1065353216L) + for (accessorIndex in expected.indices) { + assertEquals(expected[accessorIndex], readComponents(file, accessorIndex)[0], "componentType code ${5120 + accessorIndex}") + } + } + + @Test + fun readsIndicesFromAnUnsignedScalarAccessor() { + val bin = byteArrayOf(1, 0, 2, 0, 3, 0, 4, 0) + val json = jsonWith(bin.size, byteOffset = 0, componentTypeCode = 5123, componentCountCode = "SCALAR", count = 4) + assertEquals(listOf(1, 2, 3, 4), readIndices(file(json, bin), 0).toList()) + } + + @Test + fun rejectsAnIndexAccessorThatIsSigned() { + // glTF 2.0 §3.2.4 allows only an unsigned component type for indices; 5124 (INT) is not one. + val bin = byteArrayOf(1, 0, 0, 0, 2, 0, 0, 0) + val json = jsonWith(bin.size, byteOffset = 0, componentTypeCode = 5124, componentCountCode = "SCALAR", count = 2) + assertFailsWith { + readIndices(file(json, bin), 0) + } + } + + @Test + fun rejectsASparseAccessor() { + val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":4}],"bufferViews":[{"buffer":0,"byteOffset":0,"byteLength":4}],""" + + """"accessors":[{"bufferView":0,"byteOffset":0,"componentType":5126,"type":"SCALAR","count":1,"sparse":{"count":1,"indices":{"componentType":5123,"type":"SCALAR","count":1},"values":{"componentType":5126,"type":"SCALAR","count":1}}]}]}""" + assertFailsWith { + readComponents(file(json, ByteArray(4)), 0) + } + } + + @Test + fun rejectsAnAccessorWithZeroCount() { + val json = jsonWith(4, byteOffset = 0, componentTypeCode = 5126, componentCountCode = "SCALAR", count = 0) + assertFailsWith { + readComponents(file(json, floatBytes(1f)), 0) + } + } + + @Test + fun rejectsAnAccessorWithNoBufferView() { + val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":4}],"accessors":[{"byteOffset":0,"componentType":5126,"type":"SCALAR","count":1}]}""" + assertFailsWith { + readComponents(file(json, floatBytes(1f)), 0) + } + } + + @Test + fun readsMatricesOnlyFromAScalarFloat32Accessor() { + 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) + assertEquals(16, readMatrixElements(file(json, bin), 0).size) + val notScalar = jsonWith(bin.size, byteOffset = 0, componentTypeCode = 5126, componentCountCode = "VEC4", count = 4) + assertFailsWith { + readMatrixElements(file(notScalar, bin), 0) + } + val notSixteen = jsonWith(bin.size, byteOffset = 0, componentTypeCode = 5126, componentCountCode = "SCALAR", count = 12) + assertFailsWith { + readMatrixElements(file(notSixteen, bin), 0) + } + } + + @Test + fun normalizedIsNotApplied() { + // A normalized Uint16 accessor reads the raw value. Normalizing a position would scale it by 65535, + // so the reader keeps the number the file states and lets the caller decide. + val bin = byteArrayOf(-1, -1) + val json = jsonWith(bin.size, byteOffset = 0, componentTypeCode = 5123, componentCountCode = "SCALAR", count = 1) + val file = file(json, bin) + assertEquals(65535L, readComponents(file, 0)[0]) + } + + /** + * A JSON document with one buffer of [binLength] bytes, one buffer view over it, and one accessor. + * + * @param Int binLength The buffer length. + * @param Int byteOffset The accessor's byteOffset. + * @param Int componentTypeCode The component type code. + * @param String componentCountCode The component count code. + * @param Int count The element count. + * @return String The JSON text. + */ + private fun jsonWith( + binLength: Int, + byteOffset: Int, + componentTypeCode: Int, + componentCountCode: String, + count: Int, + ): String = + """{"asset":{"version":"2.0"},"buffers":[{"byteLength":$binLength}],""" + + """"bufferViews":[{"buffer":0,"byteOffset":0,"byteLength":$binLength}],""" + + """"accessors":[{"bufferView":0,"byteOffset":$byteOffset,"componentType":$componentTypeCode,"type":"$componentCountCode","count":$count}]}""" +} diff --git a/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfJsonDepthTest.kt b/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfJsonDepthTest.kt new file mode 100644 index 0000000..4816dde --- /dev/null +++ b/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfJsonDepthTest.kt @@ -0,0 +1,36 @@ +package org.umamo.format.gltf + +import kotlin.test.Test +import kotlin.test.assertFailsWith +import kotlin.test.assertNotNull + +/** + * The JSON depth guard, applied to the glTF chunk. + * + * The limit is the one the UMA reader already uses ([UMA_MAXIMUM_JSON_DEPTH]), because the parser and every walk + * over the tree recurse once per level: a document too deep to walk is too deep to parse. + */ +class GltfJsonDepthTest { + @Test + fun refusesTextNestingPastTheLimit() { + // 256 nested arrays inside the root object: depth 257, one past the limit. + assertFailsWith { + decodeGltfJson(root + "[".repeat(256) + "]".repeat(256) + "}") + } + } + + @Test + fun acceptsTextNestingToTheLimit() { + // 255 nested arrays inside the root object: depth 256, exactly the limit. + assertNotNull(decodeGltfJson(root + "[".repeat(255) + "]".repeat(255) + "}")) + } + + @Test + fun bracketsInsideStringsAreNotCounted() { + val bracketsInsideAString = "[".repeat(300) + assertNotNull(decodeGltfJson("""{"asset":{"version":"2.0"},"name":"$bracketsInsideAString"}""")) + } + + /** The root object up to the value being nested. */ + private val root = """{"asset":{"version":"2.0"},"extras":""" +} 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 new file mode 100644 index 0000000..cbee8ec --- /dev/null +++ b/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfSceneGraphTest.kt @@ -0,0 +1,68 @@ +package org.umamo.format.gltf + +import kotlin.test.Test +import kotlin.test.assertEquals + +/** + * The scene graph: which scene is drawn, which nodes it holds, which mesh and skin a node names, and the joints a + * skin binds. Nothing here renders; the point is that the references resolve. + */ +class GltfSceneGraphTest { + @Test + fun drawsTheSceneTheDocumentNames() { + val document = decodeGltfJson( + """{"asset":{"version":"2.0"},"scenes":[{"name":"first","nodes":[0]},{"name":"second","nodes":[1]}],"scene":1}""" + ) + assertEquals("second", document.scene()?.name) + } + + @Test + fun fallsBackToTheOnlySceneWhenTheDocumentNamesNone() { + val document = decodeGltfJson("""{"asset":{"version":"2.0"},"scenes":[{"name":"only","nodes":[]}]}""") + assertEquals("only", document.scene()?.name) + } + + @Test + fun resolvesANodeToItsMeshAndSkin() { + val document = decodeGltfJson( + """{"asset":{"version":"2.0"},"meshes":[{"name":"body","primitives":[{"attributes":{"POSITION":0}}]}],""" + + """"nodes":[{"name":"root","children":[1],"mesh":0,"skin":0},{"name":"joint"}],"skins":[{"name":"rig","joints":[1]}]}""" + ) + val root = document.nodes[0] + assertEquals(listOf(1), root.children) + assertEquals("body", document.meshes[root.meshIndex!!].name) + assertEquals("rig", document.skins[root.skinIndex!!].name) + assertEquals(listOf(1), document.skins[0].joints) + } + + @Test + fun aPrimitiveWithoutAModeIsTriangles() { + // glTF 2.0 §3.2 states the default mode is 5, so a file that says nothing still says TRIANGLES. + val document = decodeGltfJson("""{"asset":{"version":"2.0"},"meshes":[{"primitives":[{"attributes":{"POSITION":0}}]}]}""") + assertEquals(GltfPrimitiveMode.Triangles, document.meshes[0].primitives[0].mode()) + } + + @Test + fun aNodeCarriesEitherATrsTransformOrAMatrixNotBoth() { + val trs = decodeGltfJson("""{"asset":{"version":"2.0"},"nodes":[{"translation":[1,2,3],"rotation":[0,0,0,1],"scale":[1,1,1]}]}""").nodes[0] + assertEquals(listOf(1f, 2f, 3f), trs.translation) + assertEquals(listOf(0f, 0f, 0f, 1f), trs.rotation) + + val matrix = decodeGltfJson("""{"asset":{"version":"2.0"},"nodes":[{"matrix":[1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1]}]}""").nodes[0] + assertEquals(16, matrix.matrix.size) + } + + @Test + fun readsTheInverseBindMatricesASixteenFloatsPerJoint() { + 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}],""" + + """"nodes":[{}],"skins":[{"joints":[0],"inverseBindMatrices":0}]}""" + val file = GltfFile(decodeGltfJson(json), listOf(bin)) + val matrices = readMatrixElements(file, 0) + assertEquals(16, matrices.size) + assertEquals(1f, matrices[0]) + assertEquals(1f, matrices[5]) + } +} 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 new file mode 100644 index 0000000..a47a869 --- /dev/null +++ b/module/format/src/commonTest/kotlin/org/umamo/format/gltf/GltfValidationTest.kt @@ -0,0 +1,147 @@ +package org.umamo.format.gltf + +import kotlin.test.Test +import kotlin.test.assertEquals +import kotlin.test.assertFailsWith +import kotlin.test.assertNull + +/** + * The structural rules, tested through the codec, so a failure is reported as the codec would report it: one + * message naming the first problem, not the first thing that happened to be touched. + */ +class GltfValidationTest { + /** + * Reads a GLB built from [json] and [bin] and returns the problem the codec reports, or null. + * + * @param String json The JSON half. + * @param ByteArray bin The buffer bytes. + * @return String? The problem, or null when the document is sound. + */ + private fun problem( + json: String, + bin: ByteArray, + ): String? = firstGltfProblem(GltfFile(decodeGltfJson(json), listOf(bin))) + + @Test + fun aSoundDocumentHasNoProblem() { + val bin = floatBytes(1f, 2f, 3f) + val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":12}],""" + + """"bufferViews":[{"buffer":0,"byteOffset":0,"byteLength":12,"target":34962}],""" + + """"accessors":[{"bufferView":0,"byteOffset":0,"componentType":5126,"type":"VEC3","count":1}],""" + + """"meshes":[{"primitives":[{"attributes":{"POSITION":0}}]}],""" + + """"nodes":[{"mesh":0}],"scenes":[{"nodes":[0]}],"scene":0}""" + assertNull(problem(json, bin)) + } + + @Test + fun refusesADocumentWithMoreThanOneBuffer() { + val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":4},{"byteLength":4}]}""" + assertEquals("the document declares 2 buffers; a GLB carries exactly one, the BIN chunk", problem(json, ByteArray(4))) + } + + @Test + fun refusesABufferThatNamesAnExternalFile() { + // A reader given the bytes of one file cannot read a buffer that lives in another. + val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":4,"uri":"data:application/octet-stream;base64,AAAA"}]}""" + assertEquals("buffer 0 names a uri, so its bytes are not in this file", problem(json, ByteArray(4))) + } + + @Test + fun refusesABufferWhoseDeclaredLengthIsNotWhatTheChunkHolds() { + val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":16}]}""" + assertEquals("buffer 0 declares 16 bytes, the BIN chunk holds 4", problem(json, ByteArray(4))) + } + + @Test + fun refusesABufferViewThatRunsPastItsBuffer() { + val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":8}],"bufferViews":[{"buffer":0,"byteOffset":4,"byteLength":8}]}""" + assertEquals("buffer view 0 runs from 4 to 12, past the 8-byte buffer 0", problem(json, ByteArray(8))) + } + + @Test + fun refusesABufferViewWhoseStrideIsNotAMultipleOfFour() { + val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":8}],"bufferViews":[{"buffer":0,"byteOffset":0,"byteLength":8,"byteStride":6}]}""" + assertEquals("buffer view 0 declares byteStride 6, which is not a multiple of four", problem(json, ByteArray(8))) + } + + @Test + fun refusesABufferViewWithAnUnknownTarget() { + val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":8}],"bufferViews":[{"buffer":0,"byteOffset":0,"byteLength":8,"target":34964}]}""" + assertEquals("buffer view 0 declares target 34964, which is not one glTF states", problem(json, ByteArray(8))) + } + + @Test + fun refusesABufferViewWhoseStrideIsSmallerThanItsElement() { + // A stride of 4 over a 12-byte element: two elements land on the same bytes, which reads as a mesh + // with duplicated vertices rather than as an error. + val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":12}],""" + + """"bufferViews":[{"buffer":0,"byteOffset":0,"byteLength":12,"byteStride":4}],""" + + """"accessors":[{"bufferView":0,"byteOffset":0,"componentType":5126,"type":"VEC3","count":1}]}""" + assertEquals("accessor 0's buffer view declares byteStride 4, smaller than the 12-byte element", problem(json, ByteArray(12))) + } + + @Test + fun refusesAnAccessorWithAnUnknownComponentCode() { + // The code is checked before it is used, so an unknown one is reported as a problem rather than + // thrown from the lookup. + val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":4}],""" + + """"bufferViews":[{"buffer":0,"byteOffset":0,"byteLength":4}],""" + + """"accessors":[{"bufferView":0,"byteOffset":0,"componentType":5127,"type":"SCALAR","count":1}]}""" + assertEquals("accessor 0 declares componentType 5127, which is not one glTF states", problem(json, ByteArray(4))) + } + + @Test + fun refusesAPrimitiveWithNoAttributes() { + val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":4}],"meshes":[{"primitives":[{"mode":5}]}]}""" + assertEquals("mesh 0 primitive 0 has no attributes", problem(json, ByteArray(4))) + } + + @Test + fun refusesAPrimitiveThatNamesAnAccessorTheDocumentDoesNotHave() { + val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":4}],"meshes":[{"primitives":[{"attributes":{"POSITION":3}}]}]}""" + assertEquals("mesh 0 primitive 0 attribute 'POSITION' names accessor 3, the document has 0", problem(json, ByteArray(4))) + } + + @Test + fun refusesANodeThatNamesAChildTheDocumentDoesNotHave() { + val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":4}],"nodes":[{"children":[2]}]}""" + assertEquals("node 0 names child 2, the document has 1", problem(json, ByteArray(4))) + } + + @Test + fun refusesANodeThatDeclaresBothAMatrixAndATrsTransform() { + val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":4}],"nodes":[{"matrix":[1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1],"translation":[0,0,0]}]}""" + assertEquals("node 0 declares both a matrix and a TRS transform", problem(json, ByteArray(4))) + } + + @Test + fun refusesASkinThatBindsNoJoints() { + val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":4}],"skins":[{"joints":[]}]}""" + assertEquals("skin 0 binds no joints", problem(json, ByteArray(4))) + } + + @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}],""" + + """"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))) + } + + @Test + fun refusesASceneIndexTheDocumentDoesNotHave() { + val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":4}],"scenes":[{"nodes":[]}],"scene":1}""" + assertEquals("the document names scene 1, it has 1", problem(json, ByteArray(4))) + } + + @Test + fun theCodecReportsTheFirstProblemItFinds() { + val json = """{"asset":{"version":"2.0"},"buffers":[{"byteLength":4}],"nodes":[{"children":[2]}]}""" + val problem = assertFailsWith { + Gltf.read(buildGlb(json, ByteArray(4))) + } + assertEquals("glTF: node 0 names child 2, the document has 1", problem.message) + } +} diff --git a/module/format/src/jvmAndroidMain/kotlin/org/umamo/format/FormatRegistry.kt b/module/format/src/jvmAndroidMain/kotlin/org/umamo/format/FormatRegistry.kt index d2f436a..0cc73b9 100644 --- a/module/format/src/jvmAndroidMain/kotlin/org/umamo/format/FormatRegistry.kt +++ b/module/format/src/jvmAndroidMain/kotlin/org/umamo/format/FormatRegistry.kt @@ -3,6 +3,7 @@ package org.umamo.format import org.umamo.format.bmp.BmpCodec import org.umamo.format.clip.ClipReader import org.umamo.format.cmo3.Cmo3 +import org.umamo.format.gltf.Gltf import org.umamo.format.jpeg.JpegReader import org.umamo.format.kra.KraReader import org.umamo.format.moc3.Moc3 @@ -25,14 +26,14 @@ import org.umamo.format.webp.WebPReader public object FormatRegistry { /** * Every registered codec, in priority order (first magic match wins in [detect]): the native UMA - * container, the model codecs (CMO3, MOC3), the layered art readers (CLIP, KRA, PSD), and the flat raster - * codecs (PNG, BMP, JPEG, WebP, TIFF). The registry sits in jvmAndroidMain because the CMO3 codec does. - * The magics do not collide: UMA and KRA are both ZIPs announcing themselves through a mimetype entry, - * but each probe matches only its own mimetype string. The raster codecs sit last, so BMP's short - * 2-byte "BM" magic is checked after the longer signatures. + * container, the model codecs (CMO3, MOC3), the reference-model codec (glTF), the layered art readers + * (CLIP, KRA, PSD), and the flat raster codecs (PNG, BMP, JPEG, WebP, TIFF). The registry sits in + * jvmAndroidMain because the CMO3 codec does. The magics do not collide: UMA and KRA are both ZIPs + * announcing themselves through a mimetype entry, but each probe matches only its own mimetype string. The + * raster codecs sit last, so BMP's short 2-byte "BM" magic is checked after the longer signatures. */ private val codecs: List> = - listOf(Uma, Cmo3, Moc3, ClipReader, KraReader, PsdReader, PngCodec, BmpCodec, JpegReader, WebPReader, TiffReader) + listOf(Uma, Cmo3, Moc3, Gltf, ClipReader, KraReader, PsdReader, PngCodec, BmpCodec, JpegReader, WebPReader, TiffReader) /** * Identifies the codec for [bytes], preferring a reliable magic-byte match and falling back to the diff --git a/module/format/src/jvmTest/kotlin/org/umamo/format/gltf/GltfCodecTest.kt b/module/format/src/jvmTest/kotlin/org/umamo/format/gltf/GltfCodecTest.kt new file mode 100644 index 0000000..ec3029c --- /dev/null +++ b/module/format/src/jvmTest/kotlin/org/umamo/format/gltf/GltfCodecTest.kt @@ -0,0 +1,72 @@ +package org.umamo.format.gltf + +import org.umamo.format.FileKind +import org.umamo.format.FileRole +import org.umamo.format.FormatRegistry +import kotlin.test.Test +import kotlin.test.assertEquals +import kotlin.test.assertFailsWith +import kotlin.test.assertTrue + +/** + * The codec's face to the rest of the editor: its kind, its magic sniff, and the refusal that states it is + * read-only. + * + * The picker filters are built from [FileRole], so the role a glTF kind carries is not decoration: it decides + * whether a `.glb` shows up in Import Artwork, which adds layers to the document. A reference model is not + * artwork, so it must not appear there. + */ +class GltfCodecTest { + @Test + fun itsKindIsTheReferenceRole() { + assertEquals(FileKind.Gltf, Gltf.kind) + assertEquals(FileRole.Reference, Gltf.kind.role) + assertTrue(Gltf.kind.readable) + assertEquals(false, Gltf.kind.writable) + } + + @Test + fun writeRefuses() { + val problem = assertFailsWith { + Gltf.write(GltfFile(decodeGltfJson("""{"asset":{"version":"2.0"}}"""), listOf(ByteArray(0)))) + } + assertEquals("GLB is read-only", problem.message) + } + + @Test + fun detectsAGlbByMagic() { + val file = buildGlb("""{"asset":{"version":"2.0"}}""", ByteArray(4)) + assertTrue(Gltf.matches(file)) + assertEquals(Gltf, FormatRegistry.detect(file, "model.glb")) + } + + @Test + fun doesNotDetectAFileThatOnlyCarriesTheExtension() { + // Magic comes first: a file named .glb whose bytes are a real PNG signature is a PNG, not a glTF. + val pngSignature = byteArrayOf(0x89.toByte(), 'P'.code.toByte(), 'N'.code.toByte(), 'G'.code.toByte(), 0x0D, 0x0A, 0x1A, 0x0A) + assertEquals(false, Gltf.matches(pngSignature)) + assertEquals(FormatRegistry.detect(pngSignature, "model.glb"), FormatRegistry.forKind(FileKind.Png)) + } + + @Test + fun theExtensionFallbackStillResolvesBothNames() { + assertEquals(FileKind.Gltf, FormatRegistry.kindForFileName("model.glb")) + assertEquals(FileKind.Gltf, FormatRegistry.kindForFileName("MODEL.GLTf")) + } + + @Test + fun aGlbIsInTheReferenceFilterAndNotInTheArtworkFilter() { + val referenceExtensions = FormatRegistry.extensionsFor(FileRole.Reference) + assertTrue("glb" in referenceExtensions) + assertTrue("gltf" in referenceExtensions) + assertEquals(false, "glb" in FormatRegistry.extensionsFor(FileRole.Artwork)) + } + + @Test + fun probesTheContainerVersionWithoutParsing() { + val file = buildGlb("""{"asset":{"version":"2.0"}}""", ByteArray(0)) + val version = Gltf.getVersion(file) + assertEquals("glTF 2", version?.label) + assertEquals(null, Gltf.getVersion(ByteArray(4))) + } +} 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 new file mode 100644 index 0000000..9960ed7 --- /dev/null +++ b/module/format/src/jvmTest/kotlin/org/umamo/format/gltf/GltfCorpusTest.kt @@ -0,0 +1,77 @@ +package org.umamo.format.gltf + +import java.io.File +import kotlin.test.Test +import kotlin.test.assertTrue + +/** + * Corpus-gated end-to-end glTF read: every `.glb` under `test/corpus/gltf/` (or the single file named by + * `-Dgltf.samples=/path/to.glb`) must read, and every accessor it declares must resolve inside its buffer view. + * + * The corpus is not committed, so this self-skips when absent; the committed [GlbContainerTest], + * [GltfAccessorTest], and [GltfValidationTest] fixtures carry the per-rule coverage. + * + * A `.gltf` sample is skipped rather than failed: a JSON-only file names its buffer by `uri`, and this reader is + * given the bytes of one file, so it cannot read one. + */ +class GltfCorpusTest { + /** + * Locates every GLB sample: `-Dgltf.samples` when set, else the `test/corpus/gltf` directory found by walking + * up from the working directory. + * + * @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 } + } + var directory: File? = File(System.getProperty("user.dir")) + while (directory != null) { + val corpus = File(directory, "test/corpus/gltf") + if (corpus.isDirectory) { + return corpus.listFiles { file -> file.isFile && file.extension.equals("glb", ignoreCase = true) } + ?.toList() + ?.sortedBy { it.name } + ?: emptyList() + } + directory = directory.parentFile + } + return emptyList() + } + + @Test + fun readsEveryCorpusGlb() { + val samples = locateSamples() + if (samples.isEmpty()) { + println("no gltf.samples and no test/corpus/gltf GLBs; skipping glTF corpus test") + return + } + for (sample in samples) { + val bytes = sample.readBytes() + assertTrue(Gltf.matches(bytes), "${sample.name}: detected as GLB by magic") + val file = Gltf.read(bytes) + val scene = file.document.scene() + assertTrue(scene != null || file.document.meshes.isEmpty(), "${sample.name}: a scene, or nothing to draw") + var positionComponentsRead = 0 + for (mesh in file.document.meshes) { + for (primitive in mesh.primitives) { + val positionIndex = primitive.attributes["POSITION"] + if (positionIndex != null) { + val positions = readFloats(file, positionIndex) + assertTrue(positions.isNotEmpty(), "${sample.name}: the POSITION accessor produced values") + assertTrue(positions.all { value -> value.isFinite() }, "${sample.name}: every position is finite") + positionComponentsRead += positions.size + val vertexCount = file.document.accessors[positionIndex].count + val indices = primitive.indicesAccessorIndex?.let { index -> readIndices(file, index) } + if (indices != null) { + // An index that names a vertex the primitive does not have draws nothing, or draws the + // wrong vertex: both read as a broken mesh rather than as an error. + assertTrue(indices.all { index -> index < vertexCount }, "${sample.name}: every index names a vertex of this primitive") + } + } + } + } + println("read ${sample.name}: ${file.document.meshes.size} meshes, ${file.document.nodes.size} nodes, ${file.document.skins.size} skins, $positionComponentsRead position components") + } + } +}