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: 60 glTF tests (59 run without a corpus), `:format:jvmTest` green.
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
@@ -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,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)
|
||||
}
|
||||
@@ -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 }
|
||||
}
|
||||
}
|
||||
@@ -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,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<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. */
|
||||
@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. */
|
||||
@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,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
|
||||
}
|
||||
@@ -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<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,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<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,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<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 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<IllegalArgumentException> {
|
||||
readMatrixElements(file(notScalar, bin), 0)
|
||||
}
|
||||
val notSixteen = jsonWith(bin.size, byteOffset = 0, componentTypeCode = 5126, componentCountCode = "SCALAR", count = 12)
|
||||
assertFailsWith<IllegalArgumentException> {
|
||||
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}]}"""
|
||||
}
|
||||
@@ -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":"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])
|
||||
}
|
||||
}
|
||||
@@ -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<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.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<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
|
||||
|
||||
@@ -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,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<File> The sample files, empty when none are configured.
|
||||
*/
|
||||
private fun locateSamples(): List<File> {
|
||||
System.getProperty("gltf.samples")?.let { value ->
|
||||
return value.split(',').map { path -> File(path) }.filter(File::isFile).sortedBy { it.name }
|
||||
}
|
||||
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")
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user