Design for a poseable mannequin plus glTF/GLB import overlay in Umamo: world axes, orbit camera, draw path, UMA persistence, UI, risks. docs/seams.md lists the RenderDevice additions the feature needs: PrimitiveTopology, DepthState, depthAttachment, WorldToClip, ReferenceMeshSpec. sketch/ mirrors the algorithms in Kotlin. verify/verify.py proves them: 30 checks, all passing. Two findings: accessor byteOffset must be a multiple of the component size, and the screen-right basis collapses to a zero vector at pitch +/-90 degrees, so pitch is clamped to an open interval.
94 lines
3.2 KiB
Kotlin
94 lines
3.2 KiB
Kotlin
package org.umamo.format.gltf
|
|
|
|
// Reference sketch for PR 1. Container rules only - the JSON half is
|
|
// kotlinx-serialization-json, already a :format dependency. Everything here is
|
|
// commonMain-safe: no java.nio, no platform math, no assumption about byte order
|
|
// beyond the one the format states.
|
|
|
|
/** GLB magic, "glTF" read as a little-endian uint32. */
|
|
public const val GLB_MAGIC: Int = 0x46546C67
|
|
|
|
/** The only container version this reader accepts. */
|
|
public const val GLB_VERSION: Int = 2
|
|
|
|
private const val CHUNK_JSON: Int = 0x4E4F4A42
|
|
private const val CHUNK_BIN: Int = 0x004E4942
|
|
|
|
/** The two chunks a GLB carries, in the order they were read. */
|
|
public class GlbChunks(
|
|
public val jsonBytes: ByteArray,
|
|
public val binBytes: ByteArray,
|
|
)
|
|
|
|
public class GlbException(message: String) : Exception(message)
|
|
|
|
/**
|
|
* Reads the GLB container.
|
|
*
|
|
* Three rules that are easy to get wrong and are 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 - spaces for JSON, zeros for BIN. The padding is
|
|
* part of the chunk length, so the JSON bytes handed back include it. The JSON parser must
|
|
* not be given the padding as content; trim before parsing.
|
|
* 3. 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.
|
|
*/
|
|
public fun readGlb(data: ByteArray): GlbChunks {
|
|
if (data.size < 12) {
|
|
throw GlbException("shorter than the 12-byte header")
|
|
}
|
|
if (readUint32(data, 0) != GLB_MAGIC) {
|
|
throw GlbException("magic is not 'glTF'")
|
|
}
|
|
val version = readUint32(data, 4)
|
|
if (version != GLB_VERSION) {
|
|
throw GlbException("container version $version, this reader accepts 2")
|
|
}
|
|
val declared = readUint32(data, 8)
|
|
if (declared != data.size) {
|
|
throw GlbException("declared length $declared, actual ${data.size}")
|
|
}
|
|
|
|
var json: ByteArray? = null
|
|
var bin: ByteArray? = null
|
|
var pos = 12
|
|
while (pos + 8 <= data.size) {
|
|
val length = readUint32(data, pos)
|
|
val type = readUint32(data, pos + 4)
|
|
val start = pos + 8
|
|
if (start + length > data.size) {
|
|
throw GlbException("chunk at $pos declares $length bytes, only ${data.size - start} remain")
|
|
}
|
|
val payload = data.copyOfRange(start, start + length)
|
|
if (type == CHUNK_JSON) {
|
|
if (json != null) {
|
|
throw GlbException("more than one JSON chunk")
|
|
}
|
|
json = payload
|
|
} else if (type == CHUNK_BIN) {
|
|
if (bin != null) {
|
|
throw GlbException("more than one BIN chunk")
|
|
}
|
|
bin = payload
|
|
}
|
|
// An unknown type is skipped.
|
|
pos = start + length
|
|
}
|
|
|
|
if (json == null) {
|
|
throw GlbException("no JSON chunk")
|
|
}
|
|
return GlbChunks(json, bin ?: ByteArray(0))
|
|
}
|
|
|
|
/** Little-endian uint32. glTF is little-endian everywhere; there is no host-order reading here. */
|
|
private fun readUint32(data: ByteArray, offset: Int): Int =
|
|
(data[offset].toInt() and 0xFF) or
|
|
((data[offset + 1].toInt() and 0xFF) shl 8) or
|
|
((data[offset + 2].toInt() and 0xFF) shl 16) or
|
|
((data[offset + 3].toInt() and 0xFF) shl 24) |