2 Commits
Author SHA1 Message Date
litruv da0d13e101 glTF reader: the rules a real file corrected
Verification / build (pull_request) Failing after 9m17s
CI / verify (pull_request) Failing after 9m17s
Two rules the fixtures asserted in the wrong direction, found by reading CesiumMan.glb:

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

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

node.matrix is column-major while Mat4 is row-major, and a skin's joints have to be resolved by node
index: in CesiumMan.glb the scene root holds only the mesh node and the nineteen joints hang off a
skeleton node the scene does not reach. Both are recorded on the shapes the reader returns.
2026-11-03 21:05:43 +11:00
litruv bfec51c184 glTF/GLB reader for the reference layer (#1)
Verification / build (pull_request) Failing after 13m5s
CI / verify (pull_request) Failing after 13m5s
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: 60 glTF tests (59 run without a corpus), `:format:jvmTest` green.
2026-11-03 19:34:14 +11:00
18 changed files with 2066 additions and 6 deletions
+3
View File
@@ -167,6 +167,9 @@ umamoTestCorpus {
// dump never floods build/ on a plain test run. // dump never floods build/ on a plain test run.
"cmo3.resave", "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 // 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 // file-existence check. Without the forwarding the generator reads a property nobody set and
// returns immediately: a @Test reporting PASSED while generating nothing. // returns immediately: a @Test reporting PASSED while generating nothing.
@@ -17,6 +17,13 @@ enum class FileRole {
/** Read beside a document, never opened as one: the MOC3 JSON family. */ /** Read beside a document, never opened as one: the MOC3 JSON family. */
Sidecar, 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 writable = false
override val role = FileRole.Artwork 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
}
} }
@@ -0,0 +1,202 @@
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
/**
* 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 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
/** 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, CHUNK_BIN_NUL -> {
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
}
@@ -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<GltfFile> {
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."
}
}
@@ -0,0 +1,158 @@
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 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 * 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.Mat4) {
throw IllegalArgumentException("accessor $accessorIndex is ${accessor.componentCount()}, and a skin's matrices are MAT4")
}
return readFloats(file, accessorIndex)
}
@@ -0,0 +1,153 @@
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.
*
* 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),
Mat2("MAT2", 4),
Mat3("MAT3", 9),
Mat4("MAT4", 16);
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 }
}
}
@@ -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<ByteArray> buffers One entry per buffer, in document order.
*/
public class GltfFile(
public val document: GltfDocument,
public val buffers: List<ByteArray>,
) {
/**
* 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")
}
@@ -0,0 +1,195 @@
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<GltfBuffer> = emptyList(),
val bufferViews: List<GltfBufferView> = emptyList(),
val accessors: List<GltfAccessor> = emptyList(),
val meshes: List<GltfMesh> = emptyList(),
val nodes: List<GltfNode> = emptyList(),
val skins: List<GltfSkin> = emptyList(),
val scenes: List<GltfScene> = 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<GltfPrimitive> = 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<String, Int> = 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.
*
* [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,
val children: List<Int> = emptyList(),
@SerialName("mesh") val meshIndex: Int? = null,
@SerialName("skin") val skinIndex: Int? = null,
val translation: List<Float> = emptyList(),
val rotation: List<Float> = emptyList(),
val scale: List<Float> = emptyList(),
val matrix: List<Float> = emptyList(),
)
/**
* glTF 2.0 §3.2: one skin - the joints it binds and the inverse bind matrices it reads.
*
* [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,
val joints: List<Int> = 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<Int> = emptyList(),
)
@@ -0,0 +1,269 @@
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 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.
* @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.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) {
return "skin $skinIndex binds ${skin.joints.size} joints, and its inverse bind matrices accessor declares count ${accessor.count}, fewer than the joints"
}
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
}
@@ -0,0 +1,175 @@
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 chunkTypeCodesComeFromTheirCharacters() {
// The drift guard for a transposed hex literal. The reader carried 0x4E4F4A42 for "JSON", which
// reads as "BJON" little-endian, so every file written by another tool failed while the fixtures,
// built from the same wrong number, stayed green.
assertEquals(0x4E4F534A, chunkTypeOf("JSON"))
assertEquals(0x204E4942, chunkTypeOf("BIN "))
assertEquals(0x004E4942, chunkTypeOf("BIN\u0000"))
assertEquals(GLB_MAGIC, chunkTypeOf("glTF"))
}
@Test
fun acceptsABinChunkSpelledWithANul() {
// §3.2 states "BIN " with a trailing space; Khronos's Box.glb writes a NUL. Both name the same
// chunk, and a reader that accepted only the spec's spelling rejected a real file.
val json = """{"asset":{"version":"2.0"}}"""
val bin = byteArrayOf(1, 2, 3, 4)
val chunks = readGlb(
buildGlbFromChunks(
listOf(
GlbChunkTest(CHUNK_JSON_TEST, padToAlignment(json.encodeToByteArray(), ' '.code.toByte())),
GlbChunkTest(CHUNK_BIN_NUL_TEST, bin),
),
),
)
assertTrue(bin.contentEquals(chunks.binBytes))
}
@Test
fun rejectsAFileShorterThanTheHeader() {
assertFailsWith<IllegalArgumentException> {
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<IllegalArgumentException> {
readGlb(file)
}
}
@Test
fun rejectsAContainerVersionOtherThanTwo() {
val file = buildGlb("""{"asset":{"version":"2.0"}}""", ByteArray(0)).copyOf()
file[4] = 1
assertFailsWith<IllegalArgumentException> {
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<IllegalArgumentException> {
readGlb(buildGlbFromChunks(listOf(GlbChunkTest(CHUNK_JSON_TEST, json)), declaredTotalLength = 40))
}
}
@Test
fun rejectsAChunkThatRunsPastTheEndOfTheFile() {
assertFailsWith<IllegalArgumentException> {
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<IllegalArgumentException> {
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<IllegalArgumentException> {
readGlb(buildGlbFromChunks(listOf(GlbChunkTest(CHUNK_JSON_TEST, json), GlbChunkTest(CHUNK_JSON_TEST, json))))
}
assertFailsWith<IllegalArgumentException> {
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<IllegalArgumentException> {
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<IllegalArgumentException> {
readGlb(buildGlbFromChunks(listOf(GlbChunkTest(CHUNK_BIN_TEST, ByteArray(4)), GlbChunkTest(CHUNK_JSON_TEST, json))))
}
}
@Test
fun rejectsAFileWithNoJsonChunk() {
assertFailsWith<IllegalArgumentException> {
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())
}
}
@@ -0,0 +1,159 @@
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 val CHUNK_JSON_TEST = chunkTypeOf("JSON")
/** The BIN chunk type, as a test constant: [CHUNK_BIN] is private to the reader. */
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
/**
* 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<GlbChunkTest> 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<GlbChunkTest>,
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}}]}"""
@@ -0,0 +1,176 @@
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<IllegalArgumentException> {
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<IllegalArgumentException> {
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<IllegalArgumentException> {
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<IllegalArgumentException> {
readComponents(file(json, ByteArray(4)), 0)
}
}
@Test
fun rejectsAnAccessorWithZeroCount() {
val json = jsonWith(4, byteOffset = 0, componentTypeCode = 5126, componentCountCode = "SCALAR", count = 0)
assertFailsWith<IllegalArgumentException> {
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<IllegalArgumentException> {
readComponents(file(json, floatBytes(1f)), 0)
}
}
@Test
fun readsMatricesOnlyFromAMat4Float32Accessor() {
val bin = floatBytes(1f, 0f, 0f, 0f, 0f, 1f, 0f, 0f, 0f, 0f, 1f, 0f, 0f, 0f, 0f, 1f)
// 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 notMatrix = jsonWith(bin.size, byteOffset = 0, componentTypeCode = 5126, componentCountCode = "VEC4", count = 4)
assertFailsWith<IllegalArgumentException> {
readMatrixElements(file(notMatrix, bin), 0)
}
val notFloat = jsonWith(bin.size, byteOffset = 0, componentTypeCode = 5123, componentCountCode = "MAT4", count = 1)
assertFailsWith<IllegalArgumentException> {
readMatrixElements(file(notFloat, 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}]}"""
}
@@ -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<IllegalArgumentException> {
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":"""
}
@@ -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":"MAT4","count":1}],""" +
""""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])
}
}
@@ -0,0 +1,168 @@
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 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 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
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<IllegalArgumentException> {
Gltf.read(buildGlb(json, ByteArray(4)))
}
assertEquals("glTF: node 0 names child 2, the document has 1", problem.message)
}
}
@@ -3,6 +3,7 @@ package org.umamo.format
import org.umamo.format.bmp.BmpCodec import org.umamo.format.bmp.BmpCodec
import org.umamo.format.clip.ClipReader import org.umamo.format.clip.ClipReader
import org.umamo.format.cmo3.Cmo3 import org.umamo.format.cmo3.Cmo3
import org.umamo.format.gltf.Gltf
import org.umamo.format.jpeg.JpegReader import org.umamo.format.jpeg.JpegReader
import org.umamo.format.kra.KraReader import org.umamo.format.kra.KraReader
import org.umamo.format.moc3.Moc3 import org.umamo.format.moc3.Moc3
@@ -25,14 +26,14 @@ import org.umamo.format.webp.WebPReader
public object FormatRegistry { public object FormatRegistry {
/** /**
* Every registered codec, in priority order (first magic match wins in [detect]): the native UMA * 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 * container, the model codecs (CMO3, MOC3), the reference-model codec (glTF), the layered art readers
* codecs (PNG, BMP, JPEG, WebP, TIFF). The registry sits in jvmAndroidMain because the CMO3 codec does. * (CLIP, KRA, PSD), and the flat raster codecs (PNG, BMP, JPEG, WebP, TIFF). The registry sits in
* The magics do not collide: UMA and KRA are both ZIPs announcing themselves through a mimetype entry, * jvmAndroidMain because the CMO3 codec does. The magics do not collide: UMA and KRA are both ZIPs
* but each probe matches only its own mimetype string. The raster codecs sit last, so BMP's short * announcing themselves through a mimetype entry, but each probe matches only its own mimetype string. The
* 2-byte "BM" magic is checked after the longer signatures. * raster codecs sit last, so BMP's short 2-byte "BM" magic is checked after the longer signatures.
*/ */
private val codecs: List<FormatCodec<*>> = private val codecs: List<FormatCodec<*>> =
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 * Identifies the codec for [bytes], preferring a reliable magic-byte match and falling back to the
@@ -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<UnsupportedOperationException> {
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)))
}
}
@@ -0,0 +1,103 @@
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.
*
* The property may name files or a directory, because the corpus default the build forwards is the directory.
* A property that resolves to nothing is not silently dropped: the caller then falls back to the walk-up, so a
* gate that cannot find its samples still reports that it skipped rather than passing on an empty list.
*
* @return List<File> The sample files, empty when none are configured.
*/
private fun locateSamples(): List<File> {
System.getProperty("gltf.samples")?.let { value ->
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) {
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")
}
}
}
}
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")
}
}
}