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.
115 lines
4.1 KiB
Kotlin
115 lines
4.1 KiB
Kotlin
package org.umamo.format.gltf
|
|
|
|
// Reference sketch for PR 1: accessor resolution. This is the part of the reader with rules
|
|
// that produce wrong numbers silently rather than failing, so it is written as its own seam.
|
|
|
|
public class GltfException(message: String) : Exception(message)
|
|
|
|
/** glTF component types. The codes are the format's constants, not Umamo's. */
|
|
public enum class ComponentType(val code: Int, val byteSize: Int) {
|
|
Int8(5120, 1),
|
|
Uint8(5121, 1),
|
|
Int16(5122, 2),
|
|
Uint16(5123, 2),
|
|
Uint32(5125, 4),
|
|
Float32(5126, 4);
|
|
|
|
public companion object {
|
|
/** An unknown code is a hard failure, not a fallback: a wrong component size shifts every value after it. */
|
|
public fun fromCode(code: Int): ComponentType =
|
|
entries.firstOrNull { it.code == code } ?: throw GltfException("unknown componentType $code")
|
|
}
|
|
}
|
|
|
|
/** Number of components per element. */
|
|
public enum class ComponentCount(val code: String, val components: Int) {
|
|
Scalar("SCALAR", 1),
|
|
Vec2("VEC2", 2),
|
|
Vec3("VEC3", 3),
|
|
Vec4("VEC4", 4);
|
|
|
|
public companion object {
|
|
public fun fromCode(code: String): ComponentCount =
|
|
entries.firstOrNull { it.code == code } ?: throw GltfException("unknown accessor type $code")
|
|
}
|
|
}
|
|
|
|
public data class BufferView(
|
|
val bufferIndex: Int,
|
|
val byteOffset: Int,
|
|
val byteLength: Int,
|
|
val byteStride: Int?,
|
|
)
|
|
|
|
public data class Accessor(
|
|
val bufferViewIndex: Int,
|
|
val byteOffset: Int,
|
|
val componentType: ComponentType,
|
|
val componentCount: ComponentCount,
|
|
val count: Int,
|
|
val byteStride: Int?,
|
|
)
|
|
|
|
/**
|
|
* Reads one accessor as floats.
|
|
*
|
|
* Two rules enforced here:
|
|
*
|
|
* 1. The resolved byte offset must be a multiple of the component size. glTF states this as a
|
|
* validity requirement; a reader that ignores it reads a shifted value and gets a plausible
|
|
* wrong number rather than an error. This is the single most common glTF corruption.
|
|
* 2. The read must stay inside the buffer view's byteLength. Reading past it is an error, not a
|
|
* zero fill - a zero-filled vertex collapses a mesh quietly.
|
|
*
|
|
* `normalized` is deliberately not applied. A reference layer needs raw positions and indices;
|
|
* normalizing a position would scale it by 65535. If a material factor ever needs it, that is a
|
|
* separate read, not this one.
|
|
*
|
|
* @param ByteArray bin The BIN chunk.
|
|
* @param List<BufferView> views The document's buffer views.
|
|
* @param Accessor accessor The accessor to read.
|
|
* @return FloatArray The values, element-major.
|
|
*/
|
|
public fun readFloats(bin: ByteArray, views: List<BufferView>, accessor: Accessor): FloatArray {
|
|
val view = views[accessor.bufferViewIndex]
|
|
val size = accessor.componentType.byteSize
|
|
val n = accessor.componentCount.components
|
|
val stride = accessor.byteStride ?: view.byteStride ?: size * n
|
|
val start = view.byteOffset + accessor.byteOffset
|
|
|
|
if (start % size != 0) {
|
|
throw GltfException("accessor byte offset $start is not a multiple of component size $size")
|
|
}
|
|
val needed = (accessor.count - 1) * stride + size * n
|
|
if (start + needed > view.byteLength) {
|
|
throw GltfException("accessor reads $needed bytes, buffer view holds ${view.byteLength}")
|
|
}
|
|
|
|
val out = FloatArray(accessor.count * n)
|
|
for (i in 0 until accessor.count) {
|
|
for (c in 0 until n) {
|
|
out[i * n + c] = readComponent(bin, start + i * stride + c * size, accessor.componentType)
|
|
}
|
|
}
|
|
return out
|
|
}
|
|
|
|
private fun readComponent(bin: ByteArray, offset: Int, type: ComponentType): Float {
|
|
val b = (bin[offset].toInt() and 0xFF) or
|
|
((bin[offset + 1].toInt() and 0xFF) shl 8) or
|
|
((bin[offset + 2].toInt() and 0xFF) shl 16) or
|
|
((bin[offset + 3].toInt() and 0xFF) shl 24)
|
|
return when (type) {
|
|
ComponentType.Float32 -> Float.fromBits(b)
|
|
ComponentType.Uint32 -> b.toLong().and(0xFFFFFFFFL).toFloat()
|
|
ComponentType.Int8 -> bin[offset].toInt().toFloat()
|
|
ComponentType.Uint8 -> (bin[offset].toInt() and 0xFF).toFloat()
|
|
ComponentType.Int16 -> shortAt(bin, offset).toInt().toFloat()
|
|
ComponentType.Uint16 -> (shortAt(bin, offset).toInt() and 0xFFFF).toFloat()
|
|
}
|
|
}
|
|
|
|
private fun shortAt(bin: ByteArray, offset: Int): Short {
|
|
val v = (bin[offset].toInt() and 0xFF) or ((bin[offset + 1].toInt() and 0xFF) shl 8)
|
|
return v.toShort()
|
|
} |